Dokümantasyon

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"))
Suno oluşturma işlemleri 1–3 dakika sürer. Senkron uç nokta, parçalar hazır olana kadar bağlantıyı sunucu tarafında, yaklaşık 6 dakikalık yoklama sınırına kadar açık tutar; bu nedenle HTTP istemcinize buna uygun bir zaman aşımı (≥600s) verin. Daha uzun süren işlemler, üretim trafiği veya mobil/güvenilir olmayan ağlar için eşzamansız API'yi tercih edin — gönderim saniyeler içinde yanıt verir.

Parametreler

ParametreTürNotlar
modeldize (zorunlu)Bir müzik modeli kısa adı — suno-v5 veya suno-v5-5.
promptdize (zorunlu)Müziğin açıklaması (veya özel modda şarkı sözleri).
instrumentalbooltrue = vokal yok. Varsayılan false.
customModeboolGelişmiş Suno modu — yapıyı / şarkı sözlerini / stili doğrudan belirleyin.
stylestringStil / tür ipucu; ör. "lofi, jazz, chill".
titlestringParça başlığı.
webhook_urlmetin (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 adSağlayıcıNotlar
suno-v5SunoSuno V5 — vokaller, şarkı sözleri, stil harmanlama.
suno-v5-5SunoSuno 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

AlanTürNotlar
idstringmsc_- önekli görev kimliği.
objectstring"music".
statusstringqueued | in_progress | completed | failed.
modelstringGönderdiğiniz model kısa adı.
created_atintGönderimi kabul ettiğimiz Unix saniye zamanı.
completed_atint | nullSon duruma ulaşılan Unix saniye zamanı — beklemedeyken null.
expires_atintUnix saniyesi, gönderimden 30 gün sonrası: görev en az o zamana kadar sorgulanabilir. Sonuç URL'lerinin süresi dolmaz.
progressintSon duruma ulaşana kadar 0, ardından 100.
outputnesne | nullTamamlandığında {tracks[], archived}.
output.tracksarrayHer biri: {url, stream_url, image_url}. url / image_url kalıcı CDN bağlantılarıdır.
errornesne | nullBaş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... } }
İmza, {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/audio/musicEşzamansız /v1/audio/music/jobs
En uygun kullanımTek seferlik betikler, not defterleriÜretim, mobil, web kancaları
AğBağlantıyı 1-3 dakika açık tutarSaniyeler içinde gönderin; yoklayın veya itilen sonucu alın
Hata kurtarmaYanıtı kaybetmek = sonucu kaybetmekKimlik sona ermeden önce istediğiniz zaman yeniden sorgulayın
Web kancaları—İmzalı music.completed / music.failed

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.

Arşivleme başarısız olursa 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.

Sonraki adımlar