Panduan pantas

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

Panduan ini membawa anda daripada mencipta kunci API sehingga lagu pertama dijana, menyemak kemajuan dan memuat turun audio dalam masa lebih kurang lima minit. Semua contoh boleh disalin dan dijalankan sebagaimana adanya.

Model lalai semasa ialah suno-v6. Model penjanaan daripada suno-v2 hingga suno-v5-5 telah dimatikan: ia mungkin muncul dalam tugasan lama tetapi tidak menerima permintaan baharu.

Muat turun, pasang dan konfigurasikan suno-api agent kit dari alamat ini  https://www.suno-api.io/suno-agent-kit.zip

Disyorkan: biarkan AI melengkapkan integrasi

AI membaca 00_START_HERE.md dan membantu pendaftaran, menyimpan API Key, menyemak baki, memperkenalkan semua ciri dan penjanaan pertama. Tindakan berbayar disahkan dahulu dan timeout tidak dihantar semula secara automatik.

Langkah 1: dapatkan kunci API

1. Buka https://www.suno-api.io.
2. Klik Dapatkan kunci API dan daftar. Hanya e-mel diperlukan, bukan nombor telefon.
3. Dalam konsol, buka pengurusan token dan cipta satu kunci.
4. Salin segera — kunci hanya dipaparkan sekali. Tambah nilai baki dengan kod tebus sebelum panggilan berbayar pertama.

Langkah 2: tetapkan permintaan

Semua panggilan menggunakan URL asas dan pengepala yang sama:

POST https://www.suno-api.io
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Langkah 3: hantar permintaan pertama

Contoh 1 — menjana daripada perihalan

Perihalkan muziknya, dan API akan menulis lirik, melodi serta susunan:

curl -X POST https://www.suno-api.io/api/music/create \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --max-time 300 \
  -d '{
    "description": "lagu folk ceria tentang hari pertama musim bunga",
    "model": "suno-v6"
  }'

Respons:

[
  {
    "song_id": "abc123",
    "status": "pending",
    "song_title": "Kisah Musim Bunga",
    "description": "lagu folk ceria tentang hari pertama musim bunga",
    "created_at": "2026-04-22T10:30:00Z"
  },
  {
    "song_id": "def456",
    "status": "pending",
    "song_title": "Langkah Musim Bunga",
    "description": "lagu folk ceria tentang hari pertama musim bunga",
    "created_at": "2026-04-22T10:30:00Z"
  }
]

Setiap penjanaan menghasilkan dua versi berbeza untuk anda pilih. Satu penjanaan berharga 0,6 ¥.

Contoh 2 — menyemak kemajuan

Hantar nilai song_id yang diterima ke titik akhir pertanyaan:

curl -X POST https://www.suno-api.io/api/music/query \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "song_ids": ["abc123", "def456"],
    "model": "suno-v6"
  }'

Semasa tugasan berjalan:

[
  {
    "song_id": "abc123",
    "status": "processing",
    "song_title": "Kisah Musim Bunga",
    "progress": "60%"
  }
]

Apabila selesai:

[
  {
    "song_id": "abc123",
    "status": "completed",
    "song_title": "Kisah Musim Bunga",
    "audio_url": "https://media.code-go.com/assets/abc123-mp3.mp3",
    "video_url": "https://media.code-go.com/assets/abc123-mp4.mp4",
    "cover_url": "https://media.code-go.com/assets/abc123-cover.jpg",
    "duration": 168
  }
]

status melalui pending, submitted, processing dan berakhir dengan completed. Alamat boleh kekal kosong semasa tugasan berjalan: nilai berdasarkan status, bukan kewujudan audio_url.

Langkah 4: muat turun fail

Apabila status ialah completed, minta sahaja audio_url. Muat turun MP3 dan WAV tidak terhad dan tidak menambah kos. Jika anda perlukan audio tanpa kehilangan data untuk suntingan, gunakan titik akhir WAV.

Senario biasa

Muzik latar untuk video

{
  "description": "latar lo-fi tenang untuk video produk, tanpa vokal, dinamik stabil",
  "instrumental": true,
  "model": "suno-v6"
}

Apabila instrumental ialah true, hasilnya tidak mengandungi vokal.

Lirik dan gaya sendiri

{
  "lyrics": "[Verse 1]\nLampu kota malap perlahan-lahan\n\n[Chorus]\nKami terus melangkah",
  "style": "acoustic pop, vokal wanita hangat, 92 BPM",
  "model": "suno-v6"
}

Menyoal sehingga selesai

import time
import requests

API_KEY = "sk-your-key-here"
BASE = "https://www.suno-api.io"
HEADERS = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}

created = requests.post(
    f"{BASE}/api/music/create",
    headers=HEADERS,
    json={"description": "lagu folk ceria tentang musim bunga", "model": "suno-v6"},
).json()

song_ids = [track["song_id"] for track in created]

for _ in range(60):
    time.sleep(10)
    tracks = requests.post(
        f"{BASE}/api/music/query",
        headers=HEADERS,
        json={"song_ids": song_ids, "model": "suno-v6"},
    ).json()
    if all(track.get("status") == "completed" for track in tracks):
        for track in tracks:
            print(track["song_title"], track["audio_url"])
        break

Pengendalian ralat

Kod utama

Format ralat

{
  "error": {
    "message": "Invalid API key provided",
    "type": "invalid_request_error",
    "code": "invalid_api_key"
  }
}

Masa menunggu dan timeout (penting): endpoint penjanaan adalah 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 (--max-time 300 dalam contoh); 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.

Amalan terbaik

• Simpan kunci pada pelayan, jangan sekali-kali dalam pelayar atau aplikasi yang diedarkan.
• Soal setiap 10–15 saat, bukan dalam gelung rapat.
• Simpan song_id: ia satu-satunya pengecam untuk mencari audio kemudian.
• Hantar semula pada 429 dan 500; betulkan puncanya sebelum menghantar semula pada 400 dan 401.
• Penjanaan yang gagal dikembalikan secara automatik, jadi tugasan yang gagal tidak memakan kos.
• Timeout klien: endpoint penjanaan hanya dikira diterima apabila respons tiba; tetapkan timeout 300 saat atau lebih.
• Cuba semula: cuba semula hanya pada kegagalan yang jelas (4xx/5xx). Selepas timeout atau sambungan terputus, periksa dahulu dengan GET /api/music/songs sama ada pesanan sudah diterima, supaya tidak berganda dan dicaj dua kali.

Langkah seterusnya

• Pengesahan — kunci, ralat dan had
• Model yang disokong — nama model, pemisahan stem dan model yang dimatikan