Dokümantasyon
Müzik oluşturma
Suno V5 / V5.5 ile metinden müzik oluşturma — vokaller, şarkı sözleri ve stil denetimi. İki API biçimi vardır: parçalar hazır olana kadar bekleyen tek seferlik senkron uç nokta ve üretim kullanımı için imzalı web kancaları sunan gönderim ve yoklama tabanlı bir eşzamansız uç nokta çifti.
Uç noktalar: POST /v1/audio/music (önce ele alınan senkron) ve POST /v1/audio/music/jobs + GET /v1/audio/music/jobs/{id} (üretim için önerilen eşzamansız). Her istek iki parça oluşturur; üretim yaklaşık 1–3 dakika sürer. Fiyat: oluşturma isteği başına $0.09 (suno-v5 modeli için), $0.09 (suno-v5-5 modeli için) — iki parçanın ücreti bir kez, ön ödemeli bakiyeden alınır ve başarısız bir üretim için ücret alınmaz.
Hızlı başlangıç (senkron)
Bir prompt ve Suno modeli iletin. İstek, iki parça da hazır olana kadar açık kalır ve ardından kalıcı URL'lerini döndürür.
import requests
# Synchronous: one request blocks until the tracks are ready (1-3 min).
resp = requests.post(
"https://api.kunavo.com/v1/audio/music",
headers={"Authorization": f"Bearer {API_KEY}"},
json={
"model": "suno-v5",
"prompt": "upbeat lofi hip hop for late-night coding, mellow piano",
"instrumental": True,
},
timeout=600, # generation can take a few minutes
)
# Suno returns ~2 tracks per request.
for track in resp.json()["data"]:
print(track["url"], track.get("image_url"))Parametreler
| Parametre | Tür | Notlar |
|---|---|---|
model | dize (zorunlu) | Bir müzik modeli kısa adı — suno-v5 veya suno-v5-5. |
prompt | dize (zorunlu) | Müziğin açıklaması (veya özel modda şarkı sözleri). |
instrumental | bool | true = vokal yok. Varsayılan false. |
customMode | bool | Gelişmiş Suno modu — yapıyı / şarkı sözlerini / stili doğrudan belirleyin. |
style | string | Stil / tür ipucu; ör. "lofi, jazz, chill". |
title | string | Parça başlığı. |
webhook_url | metin (https) | Yalnızca eşzamansız — imzalı bir son durum olayını buraya gönderin. Web kancalarına bakın. |
Müzik modelleri
| Kısa ad | Sağlayıcı | Notlar |
|---|---|---|
suno-v5 | Suno | Suno V5 — vokaller, şarkı sözleri, stil harmanlama. |
suno-v5-5 | Suno | Suno V5.5 — en yeni sürüm, daha yüksek aslına uygunluk ve daha uzun üretimler. |
Canlı liste ve çağrı başına fiyatlandırma için /models adresini kontrol edin.
Eşzamansız API (gönderim + yoklama)
Uç noktalar: POST /v1/audio/music/jobs + GET /v1/audio/music/jobs/{id}. Eşzamansız video API'sini temel alır; böylece aynı yoklama / web kancası kodu farklı kiplerde çalışır.
Senkron uç nokta bir HTTP bağlantısını dakikalarca açık tutar — betikler için kullanışlıdır, ancak mobilde güvenilir değildir. Eşzamansız uç nokta çifti hemen bir msc_* kimliği döndürür; siz de status değeri completed veya failed olana kadar GET /v1/audio/music/jobs/{id} uç noktasını yoklarsınız. Modeller, fiyatlandırma ve kalıcı CDN URL'leri aynıdır.
import requests, time
# 1. Submit — returns immediately with a msc_ task id. No long-lived connection.
submit = requests.post(
"https://api.kunavo.com/v1/audio/music/jobs",
headers={
"Authorization": f"Bearer {API_KEY}",
# Optional: retrying with the same key inside ~24h returns the
# original task rather than submitting again.
"Idempotency-Key": "my-song-uuid",
},
json={
"model": "suno-v5",
"prompt": "dreamy synthwave with a driving bassline",
"title": "Midnight Drive",
},
timeout=60,
).json()
task_id = submit["id"] # "msc_abc..."
status = submit["status"] # "queued"
# 2. Poll until terminal. Recommended cadence: 5s, backing off to 30s.
while status not in ("completed", "failed"):
time.sleep(5)
r = requests.get(
f"https://api.kunavo.com/v1/audio/music/jobs/{task_id}",
headers={"Authorization": f"Bearer {API_KEY}"},
timeout=30,
).json()
status = r["status"]
if status == "failed":
raise RuntimeError(r["error"]["message"])
for track in r["output"]["tracks"]:
print(track["url"])Yanıt biçimi
| Alan | Tür | Notlar |
|---|---|---|
id | string | msc_- önekli görev kimliği. |
object | string | "music". |
status | string | queued | in_progress | completed | failed. |
model | string | Gönderdiğiniz model kısa adı. |
created_at | int | Gönderimi kabul ettiğimiz Unix saniye zamanı. |
completed_at | int | null | Son duruma ulaşılan Unix saniye zamanı — beklemedeyken null. |
expires_at | int | Unix saniyesi, gönderimden 30 gün sonrası: görev en az o zamana kadar sorgulanabilir. Sonuç URL'lerinin süresi dolmaz. |
progress | int | Son duruma ulaşana kadar 0, ardından 100. |
output | nesne | null | Tamamlandığında {tracks[], archived}. |
output. | array | Her biri: {url, stream_url, image_url}. url / image_url kalıcı CDN bağlantılarıdır. |
error | nesne | null | Başarısız olduğunda {code, message}. |
Üstbilgiler ve kurallar
Idempotency-Key(isteğe bağlı, ≤128 karakter) — aynı hesapta aynı anahtarla iki kez gönderim yapıldığında yinelenen bir görev oluşturmak yerine özgün görev döndürülür.POST /v1/audio/music/jobs, yeni bir gönderimde 202 Accepted; bir idempotency anahtarı sonucu yeniden oynattığında ise 200 OK döndürür.GET, sahip kapsamındadır: başka bir hesaba ait görev sorgulandığında 404 döndürülür.- Önerilen yoklama sıklığı: 5 s; aralığı kademeli olarak 30 s'ye çıkarın.
Web kancaları
Gönderim yaparken webhook_url'i (https) iletin; görev sonlandığı anda Kunavo imzalı bir music.completed / music.failed olayı gönderir — yeniden deneme ve artan bekleme aralıklarıyla teslim edilir. Olayın data alanı, yukarıdaki GET yanıt yüküyle birebir aynıdır.
# Pass webhook_url on submit to be pushed a signed event on terminal —
# instead of (or alongside) polling:
# {"model": "suno-v5", "prompt": "...", "webhook_url": "https://you.com/hook"}
#
# Verify the HMAC signature on your receiver (Flask shown):
import hmac, hashlib
from flask import request, abort
def verify(secret: str) -> dict:
ts = request.headers["X-Kunavo-Webhook-Timestamp"]
sig = request.headers["X-Kunavo-Webhook-Signature"] # "sha256=<hex>"
raw = request.get_data(as_text=True)
expected = "sha256=" + hmac.new(
secret.encode(), f"{ts}.{raw}".encode(), hashlib.sha256
).hexdigest()
if not hmac.compare_digest(expected, sig):
abort(401)
return request.get_json()
# Event body:
# { "id": "evt_...", "object": "event",
# "type": "music.completed" | "music.failed",
# "created_at": 1700000000,
# "data": { ...the GET /v1/audio/music/jobs/{id} payload... } }{timestamp}.{rawBody} üzerinde HMAC-SHA256 yöntemiyle hesaplanır ve X-Kunavo-Webhook-Signature: sha256=<hex> olarak gönderilir. Video web kancalarıyla aynı yöntem kullanıldığından tek bir doğrulayıcı her ikisini de işler.Hangisi ne zaman kullanılmalı?
| Senkron /v1/ | Eşzamansız /v1/ | |
|---|---|---|
| En uygun kullanım | Tek seferlik betikler, not defterleri | Üretim, mobil, web kancaları |
| Ağ | Bağlantıyı 1-3 dakika açık tutar | Saniyeler içinde gönderin; yoklayın veya itilen sonucu alın |
| Hata kurtarma | Yanıtı kaybetmek = sonucu kaybetmek | Kimlik sona ermeden önce istediğiniz zaman yeniden sorgulayın |
| Web kancaları | — | İmzalı music. |
Yanıt ve depolama
Her parçanın url (ses) ve image_url (kapak görseli) bağlantıları kalıcı files.kunavo.com bağlantılarıdır — Kunavo her sonucu kendi CDN'inde arşivler; bu nedenle, ham Suno URL'lerinin aksine bu bağlantıların süresi asla dolmaz. stream_url, Suno'nun orijinal akış bağlantısıdır (anında oynatma için kullanışlıdır). Her parça ayrıca /app/assets içinde de görünür.
output.archived değeri false olur ve URL'ler Suno'nun geçici bağlantılarına (~24 saat sonra süresi dolar) geri döner — bu durumda içeriği kendiniz yeniden barındırın.