API penjanaan mod mudah

Dikemas kini 2026-09-18 · pasukan Suno-API

Penerangan endpoint

Penjanaan mod mudah menukar penerangan satu ayat menjadi lagu yang lengkap. Perkhidmatan menulis lirik, melodi, susunan muzik dan vokal daripada penerangan anda.

Endpoint: POST /api/music/create

Pengebilan: Berbayar, kini lalai 0.6 ¥ setiap panggilan. Setiap panggilan biasanya mengembalikan 2 lagu; jumlah yang benar-benar dicaj mengikut tetapan harga semasa dalam back-office.

Max Mode / Variety: endpoint ini menyokong parameter pilihan max_mode dan variety (0-4). Dengan max_mode dihidupkan, panggilan ini dibilkan pada 2× harga (0.6 ¥ → 1.2 ¥ setiap panggilan); variety tidak menambah kos. Maksud dan cara menghantarnya ada dalam bahagian "Parameter lanjutan" pada Gambaran keseluruhan API baharu.

Model yang disyorkan: suno-v6

Masa menunggu dan timeout (penting): ini endpoint segerak — pesanan hanya diterima dan dihantar ke penjanaan apabila respons tiba. Berdasarkan ukuran, kebanyakan permintaan membalas dalam 1-3 saat, kira-kira 10% melebihi 30 saat dan paling lama sekitar 230 saat. Tetapkan timeout klien kepada 300 saat atau lebih; tiada respons tidak bermakna tiada apa-apa dijana, dan jangan cuba semula sejurus selepas timeout (ia menggandakan pesanan dan mencaj dua kali). Jika sambungan terputus, periksa kemudian dengan GET /api/music/songs. Lihat "Masa menunggu dan tetapan timeout" dalam Gambaran keseluruhan API baharu.

Parameter permintaan

Headers

Parameter body

Contoh permintaan

curl -X POST https://www.suno-api.io/api/music/create \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "suno-v6",
    "description": "lagu pop Mandarin ceria tentang musim panas di tepi laut",
    "instrumental": false,
    "wait_completion": false
  }'

Bahan rujukan references (pilihan)

references ialah tatasusunan yang melampirkan "bahan rujukan" pada penjanaan ini. Ia sepenuhnya pilihan (ditinggalkan berkelakuan sama seperti sebelum ini), dan anda boleh lampirkan satu jenis atau apa-apa gabungan.

Jenis elemen

Peraturan

• Susunan lagu rujukan ialah susunan maknanya: hantar mengikut susunan yang anda maksudkan (contohnya "melodi daripada lagu pertama, vokal daripada lagu kedua").
• style_prompt / lyrics / duration_s boleh ditinggalkan; platform mengisinya daripada maklumat lagu, dan apa yang anda hantar yang diutamakan.
• Untuk lagu instrumental tulen, lyrics boleh "" atau "[Instrumental]".
• Imej rujukan menyokong jpeg / png / webp, sehingga 10MB setiap satu, dihantar bersama body sebagai base64.
• Apabila melampirkan beberapa lagu rujukan, gunakan juga accept_mode=async (lihat "Mod resit penerimaan" di atas): perkhidmatan perlu menyediakan bahan dahulu, jadi menunggu secara segerak boleh lama.

Contoh: dua lagu rujukan

curl -X POST https://www.suno-api.io/api/music/create \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "suno-v6",
    "description": "gabungkan idea-idea ini menjadi satu lagu",
    "references": [
      { "type": "song", "song_id": "43eb711d-81f8-4e72-a68e-b2498bac88f9" },
      { "type": "song", "song_id": "a90438d2-35fc-4443-88f4-56531e6e5d24" }
    ]
  }'

Contoh: lagu rujukan + suara lama

{
  "model": "suno-v6",
  "description": "nyanyikan idea-idea ini dengan suara ini",
  "references": [
    { "type": "song",  "song_id": "43eb711d-81f8-4e72-a68e-b2498bac88f9" },
    { "type": "voice", "voice_id": "5813cbe1-36f1-414a-a9a8-4d399dfeb292" }
  ]
}

Contoh: lagu rujukan + imej rujukan

{
  "model": "suno-v6",
  "description": "tangkap suasana imej ini",
  "references": [
    { "type": "song",  "song_id": "43eb711d-81f8-4e72-a68e-b2498bac88f9" },
    { "type": "image", "base64": "data:image/jpeg;base64,/9j/4AAQ..." }
  ]
}

Ralat parameter

Kes berikut mengembalikan HTTP 400, disekat sebelum sebarang pengebilan, jadi tiada kos:

Nombor dalam references[0] ialah indeks elemen itu dalam tatasusunan, jadi elemen yang bermasalah mudah dicari.

Respons

Tatasusunan lagu, biasanya mengandungi 2 tugasan atau lagu.

[
  {
    "song_id": "clip_id",
    "song_title": "Bayu Laut Musim Panas",
    "status": "pending",
    "description": "lagu pop Mandarin ceria tentang musim panas di tepi laut",
    "audio_url": "",
    "cover_url": "",
    "video_url": "",
    "model_version": "suno-v6",
    "generation_type": "generate",
    "created_at": "2026-05-21T10:00:00Z"
  }
]

Mod resit penerimaan (pilihan, disyorkan untuk klien yang tidak boleh memegang sambungan lama)

Secara lalai endpoint ini segerak: respons yang tiba menandakan pesanan diterima, dan masa menunggu yang diukur boleh mencecah sekitar 230 saat. Jika klien anda tidak sesuai memegang sambungan lama, hidupkan mod resit penerimaan — salah satu sudah cukup:

• tambah "accept_mode": "async" pada body permintaan
• tambah pengepala X-Accept-Mode: async

Dengannya, endpoint terus mengembalikan HTTP 202, yang hanya bermaksud "diterima dan masuk baris gilir penjanaan", sementara penjanaan berterusan di latar belakang:

{
  "success": true,
  "data": {
    "request_id": "ac_20260920092714315816800d76fv3nq",
    "status": "queued",
    "accepted_at": 1789896434,
    "pre_consumed_quota": 300000,
    "tasks": [
      { "index": 0, "status": "queued" },
      { "index": 1, "status": "queued" }
    ]
  }
}

Peringkat penerimaan tidak mengembalikan song_id. ID lagu sebenar belum wujud, dan baik request_id mahupun tasks[].index bukan ID lagu — jangan simpannya sebagai song_id. song_id sebenar muncul dalam pertanyaan kemajuan di bawah.

Pertanyaan kemajuan penerimaan

Endpoint: GET /api/music/requests/{request_id} (percuma, pengesahan dengan kunci API yang sama)

curl "https://www.suno-api.io/api/music/requests/ac_20260920092714315816800d76fv3nq" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "success": true,
  "data": {
    "request_id": "ac_20260920092714315816800d76fv3nq",
    "status": "processing",
    "tasks": [
      { "index": 0, "status": "processing", "song_id": "f3fa09f5-3d55-4953-826c-0d23f043ec57" },
      { "index": 1, "status": "processing", "song_id": "5fcafe3e-3fae-4d64-8f66-c01bc027b0c3" }
    ]
  }
}

Maksud setiap nilai status:

Setiap tugasan juga mempunyai tasks[].status sendiri, dengan nilai sama seperti API pertanyaan lagu: pending (dihantar, sedang dijana), processing, completed, failed. Item tugasan mungkin juga membawa title, duration dan audio_url yang sudah didaftarkan; yang tiada bermakna belum dijana.

Selepas mendapat song_id sebenar, teruskan dengan API pertanyaan lagu atau endpoint muat turun.

Contoh Python

import time
import requests

BASE = "https://www.suno-api.io"
HEADERS = {"Authorization": "Bearer YOUR_API_KEY", "Content-Type": "application/json"}

accepted = requests.post(
    f"{BASE}/api/music/create",
    headers={**HEADERS, "Idempotency-Key": "your-own-unique-key"},
    json={"description": "lagu pop yang ceria", "model": "suno-v6", "accept_mode": "async"},
    timeout=300,
).json()["data"]

request_id = accepted["request_id"]
while True:
    time.sleep(5)
    progress = requests.get(
        f"{BASE}/api/music/requests/{request_id}", headers=HEADERS, timeout=60
    ).json()["data"]
    if progress["status"] in ("completed", "failed"):
        print(progress)
        break

Keserasian dan nota

• Tanpa accept_mode, kelakuan sama seperti sebelum ini: menunggu secara segerak, mengembalikan 200 dan tatasusunan lagu. Integrasi sedia ada tidak perlu mengubah apa-apa.
• Suis ini kini hanya berfungsi pada POST /api/music/create dan POST /api/music/create/custom; endpoint penjanaan lain belum menyokongnya.
• Hantar juga Idempotency-Key (rentetan unik anda sendiri, ≤128 aksara): kunci yang sama hanya diterima sekali, penghantaran semula mengembalikan resit yang sama dan tidak dicaj dua kali. Dalam mod tak segerak ini lebih penting.
• Dengan accept_mode=async, wait_completion diabaikan (resit terus kembali tanpa menunggu lagu).
• Bayaran masih ditolak di hadapan apabila pesanan diterima; penjanaan yang gagal dipulangkan sepenuhnya secara automatik.
• Had medan teks: description memuat paling banyak 3000 aksara (dikira dalam aksara Unicode, satu aksara Han dikira 1). Teks lebih panjang terus mengembalikan HTTP 400, tidak masuk penjanaan dan tidak dibilkan, dan mesej ralat menyertakan panjang yang diukur, contohnya description must not exceed 3000 characters; received 4120. Endpoint ini tiada medan lirik/gaya; untuk itu lihat "Had medan teks" dalam API penjanaan mod tersuai. Peraturan umum ada dalam "Had medan teks" pada Gambaran keseluruhan API baharu.
• Tanpa references, kelakuan, harga dan respons sama seperti sebelum ini: integrasi sedia ada tidak perlu mengubah apa-apa.
• Apabila bahan rujukan dilampirkan (terutamanya beberapa lagu), pilih mod resit accept_mode=async daripada menunggu segerak yang lama; masa penyediaan bahan bergantung pada jumlah dan sumbernya.

Langkah seterusnya

Jika lagu belum selesai apabila respons tiba, gunakan API pertanyaan lagu untuk mengambil hasil akhir.

Contoh integrasi Node/Electron

Jika anda mengintegrasikan penjanaan standard dalam proses utama Electron, pelayan Node.js atau klien desktop, aliran yang disyorkan ialah:

1. Panggil POST /api/music/create untuk mencipta tugasan penjanaan.
2. Baca song_id atau id daripada respons.
3. Panggil POST /api/music/query setiap 2 saat untuk memeriksa status.
4. Anggap penjanaan selesai sebaik sahaja audio_url muncul dalam hasil pertanyaan.

Berhenti menggunakan laluan lama POST /api/generate atau GET /api/clip?id=...; kedua-duanya bukan sebahagian daripada permukaan integrasi awam yang disyorkan kini.

const http = require('http');
const https = require('https');

const BASE_URL = 'https://www.suno-api.io';
const MODEL = 'suno-v6';
const POLL_INTERVAL_MS = 2000;
const MAX_POLL_ATTEMPTS = 60;

function sleep(ms) {
  return new Promise((resolve) => setTimeout(resolve, ms));
}

function requestJson(urlString, apiKey, body) {
  const url = new URL(urlString);
  const transport = url.protocol === 'https:' ? https : http;
  const payload = JSON.stringify(body);

  return new Promise((resolve, reject) => {
    const req = transport.request(
      {
        method: 'POST',
        hostname: url.hostname,
        port: url.port || undefined,
        path: `${url.pathname}${url.search}`,
        headers: {
          Authorization: `Bearer ${apiKey}`,
          'Content-Type': 'application/json',
          'Content-Length': Buffer.byteLength(payload),
        },
      },
      (res) => {
        let raw = '';

        res.setEncoding('utf8');
        res.on('data', (chunk) => {
          raw += chunk;
        });
        res.on('end', () => {
          const data = raw ? JSON.parse(raw) : {};

          if (!res.statusCode || res.statusCode < 200 || res.statusCode >= 300) {
            reject(new Error(`Suno API request failed: HTTP ${res.statusCode} ${raw}`));
            return;
          }

          resolve(data);
        });
      }
    );

    req.on('error', reject);
    req.write(payload);
    req.end();
  });
}

function getPayload(response) {
  return response && response.data !== undefined ? response.data : response;
}

function toSongList(payload) {
  if (Array.isArray(payload)) return payload;
  if (Array.isArray(payload?.songs)) return payload.songs;
  if (Array.isArray(payload?.clips)) return payload.clips;
  return payload ? [payload] : [];
}

function collectSongIds(createResponse) {
  return toSongList(getPayload(createResponse))
    .map((song) => song.song_id || song.id)
    .filter(Boolean);
}

async function generateSunoSong({ apiKey, description, instrumental = false }) {
  const createResponse = await requestJson(`${BASE_URL}/api/music/create`, apiKey, {
    description,
    model: MODEL,
    instrumental,
    wait_completion: false,
  });

  const songIds = collectSongIds(createResponse);
  if (songIds.length === 0) {
    throw new Error(`Suno API did not return song ids: ${JSON.stringify(createResponse)}`);
  }

  for (let attempt = 0; attempt < MAX_POLL_ATTEMPTS; attempt += 1) {
    await sleep(POLL_INTERVAL_MS);

    const queryResponse = await requestJson(`${BASE_URL}/api/music/query`, apiKey, {
      song_ids: songIds,
      model: MODEL,
    });

    const songs = toSongList(getPayload(queryResponse));
    const completed = songs.find((song) => song.audio_url);

    if (completed) {
      return {
        audioUrl: completed.audio_url,
        title: completed.song_title || completed.title || 'Suno Song',
        duration: completed.duration,
      };
    }

    const allFailed = songs.length > 0 && songs.every((song) =>
      ['failed', 'error', 'rejected'].includes(String(song.status || '').toLowerCase())
    );

    if (allFailed) {
      throw new Error(`Suno generation failed: ${JSON.stringify(songs)}`);
    }
  }

  throw new Error('Suno generation timed out after 120 seconds. Please query again later.');
}

// Usage:
// generateSunoSong({
//   apiKey: process.env.SUNO_API_KEY,
//   description: 'A bright pop song about the ocean in summer',
// }).then(console.log).catch(console.error);

Dalam projek sebenar, simpan kunci API dalam pemboleh ubah persekitaran pelayan, tetapan klien desktop atau storan selamat — jangan sekali-kali dalam kod bahagian hadapan dan jangan sesekali commit ke repositori.