Medya kılavuzları
Müzik oluşturma
Şarkı veya sözler oluşturun ve tamamlanan ses dosyasını bekleyin
Müzik oluşturma işlemi asenkrondur. POST /v1/music/generations bir görev kimliği (task ID), durum ve genellikle poll_url döndürür. Görev completed (tamamlandı) veya failed (başarısız) durumuna gelene kadar bu kimlikle GET /v1/tasks/{id} sorgusu yapın.
Ne oluşturacağınızı seçin
| Ne oluşturulacak | Ana alanlar | Notlar |
|---|---|---|
| Tam şarkı veya enstrümantal | model, mv, prompt, isteğe bağlı title, tags, action: "MUSIC" | Kullanıcı nihai ses dosyasını beklediğinde kullanın |
| Sadece sözler | model, prompt, action: "LYRICS" | Yalnızca söz oluşturmayı destekleyen modellerle kullanın |
| Mevcut bir klibi devam ettirme | model, mv, prompt, continue_clip_id, isteğe bağlı continue_at | Önceki klip kimliğini koruyun |
| Kendi sesinizi kaplama veya uzatma | model, mv, prompt, audio_url, isteğe bağlı audio_operation | audio_url herkese açık bir URL olmalıdır. audio_operation varsayılan olarak upload-cover değerindedir; upload-extend ayrıca continue_at gerektirir |
| Enstrümantal ekleme, bölüm değiştirme veya kanalları ayırma | audio_operation: add-instrumental, replace-section, vocal-separate, multi-stem-separation veya advanced-split | Her işlemin kendi gerekli alanları vardır; bkz. Müzik Oluşturma |
Güncel müzik modeli listesini şuradan alın:
curl "https://api.tokenlab.sh/v1/models?recommended_for=music" \
-H "Authorization: Bearer sk-your-api-key"Aşağıdaki örnekte mv: "chirp-v6" ile suno-music kullanılmaktadır. stable-audio-3 gibi diğer müzik modelleri, duration ve output_format gibi farklı alanlar kullanır; önce modelin detaylarını okuyun. Sadece sözler için, söz oluşturmayı belgeleyen bir model seçin, action: "LYRICS" gönderin ve mv alanını boş bırakın.
Bir müzik görevi oluşturun
curl https://api.tokenlab.sh/v1/music/generations \
-H "Authorization: Bearer sk-your-api-key" \
-H "Content-Type: application/json" \
-d '{
"model": "suno-music",
"mv": "chirp-v6",
"prompt": "An upbeat synth-pop track with warm vocals and a clean chorus",
"title": "Morning Static",
"tags": "synth-pop, upbeat",
"action": "MUSIC"
}'İstemler (prompt), başlıklar ve etiketler ürün geçmişinizde görünebilir. Bunların içine asla API anahtarları, özel URL'ler veya tanılama verileri yerleştirmeyin.
Tamamlanan ses dosyasını alın
Döndürülen id veya task_id ile GET /v1/tasks/{id} çağrısı yapın.
curl "https://api.tokenlab.sh/v1/tasks/$TASK_ID" \
-H "Authorization: Bearer sk-your-api-key"Yanıt Yapısı
Oluşturma yanıtı bir görev kaydıdır, nihai ses dosyası değildir:
{
"id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"task_id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"poll_url": "/v1/tasks/ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"status": "pending",
"created": 1706000000,
"model": "suno-music"
}Tamamlanmış bir sorgu yanıtı, nihai medya alanlarını içerebilir:
{
"id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"task_id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"poll_url": "/v1/tasks/ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"status": "completed",
"audio_url": "https://api.tokenlab.sh/v1/media-results/2d7e9a41-8c3b-4b6f-a1e5-7f0c3d9b8e26.mp3?token=…",
"video_url": "https://api.tokenlab.sh/v1/media-results/9a3f5c17-2e8d-4b0a-b6c4-1d7e8f2a5b39.mp4?token=…",
"image_url": "https://api.tokenlab.sh/v1/media-results/c4e8b2d6-7a1f-4e3c-9d5b-3f6a0e8c1b72.jpg?token=…",
"title": "Morning Static",
"lyrics": "[Verse 1]\n...",
"media_retention": {
"days": 30,
"items": [
{
"url": "https://api.tokenlab.sh/v1/media-results/2d7e9a41-8c3b-4b6f-a1e5-7f0c3d9b8e26.mp3?token=…",
"kind": "audio",
"status": "saving",
"expires_at": "2024-02-22T08:54:20.000Z"
},
{
"url": "https://api.tokenlab.sh/v1/media-results/9a3f5c17-2e8d-4b0a-b6c4-1d7e8f2a5b39.mp4?token=…",
"kind": "video",
"status": "saving",
"expires_at": "2024-02-22T08:54:20.000Z"
},
{
"url": "https://api.tokenlab.sh/v1/media-results/c4e8b2d6-7a1f-4e3c-9d5b-3f6a0e8c1b72.jpg?token=…",
"kind": "image",
"status": "saving",
"expires_at": "2024-02-22T08:54:20.000Z"
}
]
}
}Nihai medya alanları status değeri completed olana kadar mevcut değildir. Başarısız görevler error ile birlikte status: "failed" döndürür.
Durumlar pending, processing, completed ve failed şeklindedir. Tamamlanmış bir görev audio_url, video_url, title, lyrics ve diğer meta verileri içerebilir. Medya URL'leri 30 gün boyunca geçerli kalan TokenLab URL'leridir; daha uzun süre ihtiyacınız olan sonuçları indirin veya kaydedin.
Doğru durumu gösterin
- Görev oluşturulduktan hemen sonra bekleyen (pending) durumu gösterin.
- Uzun görevler için her
5-10 saniyede birsorgulama yapın, ardındancompletedveyafaileddurumunda durun. - Görev
completedolana ve biraudio_urlmevcut olana kadar nihai oynatıcıyı görüntülemeyin. - Sadece söz içeren görevler için, kullanıcıların ne satın aldıklarını anlamaları adına metin çıktısını ses görevlerinden ayrı olarak işleyin.
- Yenileme durumunda, yeni bir görev oluşturmak yerine depolanan
task_idüzerinden devam edin.
Faturalandırma kayıtları
Müzik görevleri oluşturulduklarında tahmini bir tutarı rezerve edebilir. Nihai tutar, tamamlanma veya başarısızlık sonrasında kaydedilir. request_id, task_id, model, uç nokta ve göründüğünde billing_transaction_id değerlerini kaydedin; nihai ücretlendirme için Management API kullanım kayıtlarını kullanın.
Yaygın Hatalar
| Belirti | Olası neden | Çözüm |
|---|---|---|
| Görev oluşturuldu ancak oynatıcı yok | Görev hala beklemede veya audio_url olmadan tamamlandı | Sonuca ulaşana kadar sorgulamaya devam edin, ardından eksik çıktıyı başarısız bir kullanıcı işi olarak ele alın |
| Yenilemeden sonra mükerrer şarkılar | Arayüz görevi devam ettirmek yerine yeniden oluşturdu | task_id değerini kalıcı hale getirin ve yeniden kullanın |
| Söz görevi ses döndürmüyor | action: "LYRICS" sadece metin içindir | Söz ve müzik arayüz yollarını ayırın |
| Desteklenmeyen parametre | Seçilen model alanı kabul etmiyor | Alanı kaldırın veya bunu belgeleyen bir model seçin |
API Referansı
| Konu | Referans |
|---|---|
| Müzik Oluşturma | Müzik Oluşturma |
| Müzik Durumunu Alma | Müzik Durumunu Alma |
| Görev Durumunu Alma | Görev Durumunu Alma |
| Modelleri Listeleme | Modelleri Listeleme |
| Faturalandırma ve Fiyatlandırma | Faturalandırma ve Fiyatlandırma |