Ses klonlama ve belirtilen sesle üretim API'si (önerilmez)

2026-09-18 tarihinde güncellendi · Suno-API ekibi

⛔ Eski yol, yeni entegrasyonlar için önerilmez. Bu sayfa ilk dönem persona yolunu (voice_task_id / generate-with-voice) anlatır. Hâlâ çalışır, ancak müşterilere artık önerilmez; soldaki menüde "önerilmez" olarak işaretlenmiştir.

Yeni entegrasyonlar için 【Önerilir】 Ses profili API'sini kullanın: tek bir vokal örneğinden ses profili oluşturun (POST /api/music/voice-profile/create) ve bu profille seçtiğiniz şarkıyı cover'layın ya da yeni bir şarkı söyletin. Ses profili birinci sınıf bir kaynaktır: listelenebilir, sorgulanabilir ve silinebilir; kaynak ses kalıcı olarak saklanır.

Ürününüzün "ses oluştur → uzun süre yeniden kullan → cover'la" döngüsünün tamamına ihtiyacı varsa yeni yolu tercih edin.

Önemli: klonlanan ses süresi dolabilir.

Ses klonlamanın ürettiği voice_id / voice_task_id kalıcı olarak kullanılabilen bir kaynak değildir; geçerlilik süresi, hesap durumu veya ses durumundaki değişiklikler nedeniyle çalışmayı bırakabilir. Entegrasyon yapan taraf, bir kez klonlayıp yerel önbellekteki ses kimliğini sonsuza kadar yeniden kullanmamalıdır.

Önerilen yaklaşım:

• voice_task_id, voice_id, is_available, updated_at ve son başarılı üretim zamanını saklayın.
• Klonlanmış sesle üretim yapmadan önce her seferinde GET /api/voice/clone/tasks/{voice_task_id} veya POST /api/voice/clone/tasks/{voice_task_id}/check çağırıp is_available=true olduğunu doğrulayın.
• Uç nokta sesin kullanılamadığını, görevin bulunmadığını veya selected voice is not ready döndürürse kullanıcıdan yeniden klonlamasını ya da başka bir kullanılabilir ses seçmesini isteyin.
• Son kullanıcıya klonlanan sesin "kalıcı bir varlık" olduğunu vaat etmeyin; ürün arayüzünde "ses süresi dolabilir, yeniden doğrulama veya yeniden klonlama gerekebilir" bilgisini gösterin.

Uç nokta açıklaması

Bu uç nokta grubu yeniden kullanılabilir bir ses oluşturur ve o sesle şarkı üretir. Çağıran taraf yalnızca platformun verdiği API anahtarını kullanır; görev gönderimi, durum eşitleme, faturalama ve indirme sunucu tarafında yürütülür.

Kimlik doğrulama: Authorization: Bearer YOUR_API_KEY

Faturalama:

• Ses doğrulama, ses klonlama, durum sorgulama, silme ve indirme: ücretsiz.
• Çalışma alanındaki tek adımda klonlama girişi: çağrı başına sabit 5 ¥; kaynak sesin doğrulamasını ve ikinci doğrulama sesini otomatik tamamlar, hata olursa iade edilir.
• Normal klonlamadan sonra otomatik olarak doğrulama sesine geçme: çağrı başına sabit 5 ¥; hata durumunda mevcut akışa göre iade edilir.
• Klonlanmış sesle şarkı üretme: ücretli, çağrı başına sabit 1,2 ¥; her çağrı genelde 2 yer tutucu görev döndürür.
• Max Mode açıkken (POST /api/music/generate-with-voice içinde max_mode: true) bu çağrı başına 1,2 ¥ 2 katı olarak, yani çağrı başına 2,4 ¥ olarak faturalanır; ses üretimi de variety destekler (0-4, ek ücret yok); değer kuralları yeni API'ye genel bakış sayfasının "Gelişmiş parametreler" bölümündedir.

Çağrı akışı

1. POST /api/voice/clone/validate çağırıp kaynak sesi yükleyin ve voice_task_id alın.
2. GET /api/voice/clone/tasks/{voice_task_id} çağrısını bekleyin veya yoklayın, validate_info bilgisini alın.
3. Kullanıcı bu metni yüksek sesle okur ve doğrulama sesini kaydeder.
4. POST /api/voice/clone/tasks/{voice_task_id}/generate çağırıp doğrulama sesini gönderin.
5. POST /api/voice/clone/tasks/{voice_task_id}/check çağırın veya görevi sorgulamaya devam edip is_available=true olana kadar bekleyin.
6. POST /api/music/generate-with-voice çağırıp bu sesle şarkı üretin.
7. Üretim uç noktası önce yer tutucu görevleri döndürür; üretim tamamlanıp gerçek song_id alındığında indirme uç noktalarıyla tek dosya veya paket indirebilirsiniz.
8. (İsteğe bağlı) Ses artık gerekmediğinde DELETE /api/voice/clone/voices/{voice_task_id} çağırıp silin; anlamı 6. bölümde.

Ayrıca tek adımda klonlama vardır: çalışma alanındaki ilk kayıt/kaynak ses yükleme sayfasında tek seferde tamamlamayı seçebilirsiniz; sistem doğrulama ile ses oluşturmayı birlikte yapar, böylece ikinci bir doğrulama sesi kaydetmeniz gerekmez; çağrı başına 5 ¥ olup hata durumunda iade edilir.

Ses görevi alanları

1. Kaynak sesi doğrulamaya gönderin

Uç nokta: POST /api/voice/clone/validate

Gövde parametreleri

vocal_end_s - vocal_start_s en kısa vokal parçası koşulunu sağlamalıdır. Belirgin eşlik ve gürültü içermeyen temiz bir vokal kaydı yükleyin.

İstek örneği

curl -X POST https://www.suno-api.io/api/voice/clone/validate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "voice_url": "https://example.com/source-voice.wav",
    "voice_name": "Çince kadın sesim",
    "description": "Net ve doğal Çince kadın sesi",
    "style": "Mandopop",
    "singer_skill_level": "intermediate",
    "language": "zh",
    "vocal_start_s": 1.2,
    "vocal_end_s": 18.5,
    "source_duration_seconds": 20
  }'

Yanıt örneği

{
  "success": true,
  "message": "",
  "data": {
    "voice": {
      "voice_task_id": 123,
      "voice_name": "Çince kadın sesim",
      "language": "zh",
      "validate_status": "submitted",
      "is_available": false,
      "status": "validate_submitted",
      "stage": "validate_submitted",
      "created_at": 1780480000,
      "updated_at": 1780480000
    }
  }
}

2. Ses görevini sorgulayın

Uç nokta: GET /api/voice/clone/tasks/{voice_task_id}

İstek örneği

curl https://www.suno-api.io/api/voice/clone/tasks/123 \
  -H "Authorization: Bearer YOUR_API_KEY"

Yanıt örneği

{
  "success": true,
  "message": "",
  "data": {
    "voice": {
      "voice_task_id": 123,
      "voice_name": "Çince kadın sesim",
      "validate_info": "Burada dönen doğrulama metnini yüksek sesle okuyun",
      "validate_status": "success",
      "is_available": false,
      "status": "validate_ready",
      "stage": "validate_callback"
    }
  }
}

3. Doğrulama metnini yeniden oluşturun

Uç nokta: POST /api/voice/clone/tasks/{voice_task_id}/regenerate

Doğrulama metni yüksek sesle okumaya uygun değilse veya doğrulamanın yeniden yapılması gerekiyorsa çağırın.

curl -X POST https://www.suno-api.io/api/voice/clone/tasks/123/regenerate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

4. Doğrulama sesini gönderin ve sesi oluşturun

Uç nokta: POST /api/voice/clone/tasks/{voice_task_id}/generate

Gövde parametreleri

İstek örneği

curl -X POST https://www.suno-api.io/api/voice/clone/tasks/123/generate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "verify_url": "https://example.com/verify-voice.wav",
    "voice_name": "Çince kadın sesim"
  }'

5. Sesin kullanılabilir olup olmadığını kontrol edin

Uç nokta: POST /api/voice/clone/tasks/{voice_task_id}/check

curl -X POST https://www.suno-api.io/api/voice/clone/tasks/123/check \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Görev kullanılabilir olduğunda yanıttaki is_available değeri true olur ve bir voice_id döner.

6. Sesi silin

Uç nokta: DELETE /api/voice/clone/voices/{voice_task_id}

Faturalama: ücretsiz.

curl -X DELETE https://www.suno-api.io/api/voice/clone/voices/123 \
  -H "Authorization: Bearer YOUR_API_KEY"

Yanıt örneği

{
  "success": true,
  "message": "",
  "data": {
    "voice_task_id": 123,
    "deleted": true
  }
}

Silme sonrasında ne olur

• Yeni şarkı üretmek için kullanılamaz: bu voice_task_id (veya voice_id) ile POST /api/music/generate-with-voice çağrısı reddedilir, hata mesajı selected voice is not ready olur ve ücret alınmaz.
• Onunla üretilmiş şarkılar hiç etkilenmez: oynatma, indirme, devam ettirme, değiştirme ve track ayırma eskisi gibi çalışır.
• Bu ses görevi sorgulardan kaybolur: GET /api/voice/clone/tasks/{voice_task_id} çağrısı record not found döndürür.
• Kaynak ses, platformun kalıcı saklama politikasına göre saklanır (2026-09-23'ten itibaren silme işlemi yüklediğiniz vokal örneğini artık temizlemez), ancak bu, geri getirilebileceği anlamına gelmez: bu eski görev sona ermiştir ve aynı sesi kullanmaya devam etmek için klonlama akışını baştan yürütmeniz gerekir; yeni bir voice_task_id alırsınız.
• İkinci kez silme: aynı görevi tekrar silmek record not found döndürür (artık silinmiş durumdadır ve bulunamaz).

7. Klonlanmış sesle şarkı üretin

Uç nokta: POST /api/music/generate-with-voice

Faturalama: çağrı başına 1,2 ¥.

Gövde parametreleri

suno-v6, suno-v6-wild ve suno-v6-mini desteklenir; model boşsa suno-v6 olarak işlenir. Eski V5/V5.5 modelleri kaldırıldı, ancak eski görevlerde hâlâ eski model adları görünebilir.

Paylaşılan istek yapısı ayrıca task, soundType, soundLoop, soundBpm, soundKey, voiceTaskId, voiceId gibi Create UI uyumluluk alanlarını da çözümler, ancak bunlar bu uç noktanın geçerli müşteri parametreleri değildir: ses görevi voice_task_id olarak gönderilmelidir, isteğe bağlı ses doğrulaması voice_id olarak gönderilmelidir ve sesle müzik üretimi sound alanlarını hiçbir zaman okumaz.

Üretim parametrelerini doldurma

• customMode=false iken prompt şarkı açıklamasını, customMode=true iken prompt tam şarkı sözlerini taşır ve style ile title de doldurulmalıdır. Şarkı sözlerini ilham modunun açıklama alanına göndermeyin veya şarkı açıklamasını gelişmiş mod şarkı sözü olarak değerlendirmeyin.
• weirdnessConstraint ve styleWeight 0.0 ile 1.0 arasında ondalık oranlardır; 50 veya %50 gönderilemez. Dengeli bir değer olarak 0.5 kullanılabilir; atlamak "belirtilmedi" anlamına gelir, 0 ise geçerli bir açık değerdir.
• vocalGender yalnızca m, male, f veya female kabul eder. instrumental bu uç noktada yalnızca bir uyumluluk alanıdır: klonlanmış sesle üretim her zaman vokalli şarkı olarak işlenir.
• waitAudio burada davranışı değiştirmez; uç nokta her zaman yer tutucu görevleri eşzamanlı olmayan biçimde döndürür. İlk sonuçtaki boş audio_url normaldir: client_request_id ile sorgulayın ve ses adresini ancak sonuç tamamlandıktan sonra okuyun.

Başlık parametreleri

Idempotency-Key davranışı:

• İlk istek, faturalamadan önce kalıcı bir tekilleştirme kaydı yazar;
• Aynı anahtar ve aynı istek daha önce tamamlanmışsa ilk kabul yanıtı tekrarlanır; ikinci bir ücret alınmaz ve görev oluşturulmaz;
• Aynı anahtarın farklı istek gövdesiyle kullanımı reddedilir;
• Aynı anahtar hâlâ işleniyorsa kararlı bir "işleniyor" hatası döner ve güvenli client_request_id yalnızca üretildiğinde döner;
• Bir anahtarla ilk istek başarısız olursa başarısızlık durumu korunur; yeniden denemek için yeni anahtar gerekir.

sourceClipId ile cover koşulları

Müşteri API'sinde kaynaktan cover tamamen sunucu tarafında yürütülür: kaynak şarkıya erişimi sunucu çözer ve müşteri hiçbir hesap bilgisi göndermez. Mümkün olup olmadığını uç noktanın gerçek yanıtı belirler.

Kaynak, geçerli API kullanıcısına ait olmalı, tamamlanmış ve pending: olmayan bir çalışma alanı şarkısı olmalı ve kullanılabilir sesi bulunmalıdır. Normal üretim, normal yükleme kaynakları ve güçlendirilmiş yüklemenin son şarkısı desteklenir; güçlendirilmiş yüklemenin ara kayıtları faturalamadan önce reddedilir. Sunucu yalnızca müşterinin gönderdiği kaynak şarkı kimliğini kabul eder, hesap kimliğini asla; kaynak kullanılamıyor veya tamamlanmamışsa faturalamadan önce hata döner.

İstek örneği

curl -X POST https://www.suno-api.io/api/music/generate-with-voice \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "voice_task_id": 123,
    "customMode": true,
    "prompt": "Yaz gecesi deniz kıyısını anlatan bir Çince pop şarkısı yaz",
    "style": "Mandopop, warm piano, emotional",
    "title": "Yaz gecesinde deniz meltemi",
    "negativeTags": "noise, low quality",
    "instrumental": false,
    "model": "suno-v6"
  }'

Yanıt örneği

{
  "success": true,
  "message": "",
  "data": {
    "client_request_id": "cu_1780480000_abcd1234",
    "items": [
      {
        "placeholder_id": "pending:cu_1780480000_abcd1234:0",
        "client_request_id": "cu_1780480000_abcd1234",
        "client_request_index": 0,
        "status": "submitted",
        "type": "voice_generate",
        "title": "Yaz gecesinde deniz meltemi",
        "prompt": "Yaz gecesi deniz kıyısını anlatan bir Çince pop şarkısı yaz"
      },
      {
        "placeholder_id": "pending:cu_1780480000_abcd1234:1",
        "client_request_id": "cu_1780480000_abcd1234",
        "client_request_index": 1,
        "status": "submitted",
        "type": "voice_generate",
        "title": "Yaz gecesinde deniz meltemi",
        "prompt": "Yaz gecesi deniz kıyısını anlatan bir Çince pop şarkısı yaz"
      }
    ],
    "pre_consumed_quota": 600000,
    "billing_source": "wallet"
  }
}

Yer tutucu görevler ve nihai song_id

generate-with-voice eşzamanlı olmayan bir üretim uç noktasıdır. Başarılı yanıt yalnızca üretim görevinin gönderildiğini gösterir, şarkının tamamlandığını göstermez.

Yanıttaki başlıca alanların anlamı:

Dikkat: pending: ile başlayan bir placeholder_id nihai song_id olarak kullanılamaz ve /api/music/query ya da indirme uç noktalarına doğrudan verilemez. Yalnızca pending:* değerleriyle /api/music/query çağırmak boş bir dizi [] döndürebilir; bunun nedeni gerçek şarkının henüz tamamlanmamış olması veya yer tutucu görevin nihai şarkı kimliğiyle değiştirilmemiş olmasıdır.

Yanlış örnek:

{
  "song_ids": "pending:cu_1780480000_abcd1234:0"
}

Doğru akış:

1. POST /api/music/generate-with-voice çağırıp sesle müzik üretim görevini gönderin.
2. Yanıttaki client_request_id, items[].placeholder_id ve items[].client_request_index değerlerini saklayın.
3. GET /api/music/generate-with-voice/results?client_request_id=cu_xxx adresini yoklayın.
4. Dönen items[].song_id bir değer taşıyıp pending: ile başlamıyorsa /api/music/query, /api/music/download-file veya /api/music/download-all çağırın.

Mevcut sürüm bir herkese açık sorgu uç noktası ekler:

GET /api/music/generate-with-voice/results?client_request_id=cu_xxx

Geçerli kullanıcı altındaki aynı client_request_id için görev sonuçlarını döndürür; böylece müşteri nihai song_id değerini kendi sorgulayabilir. Dönen listede:

• song_id gerçek şarkı kimliğidir;
• placeholder_id yalnızca görev hâlâ yer tutucu durumundayken görünür;
• pending: ile başlayan bir değer /api/music/query veya indirme uç noktalarıyla kullanılamaz.

Yalnızca client_request_id ya da pending:* yer tutucu kimliğini sakladıysanız önce bu sonuç uç noktasını çağırın; gerçek song_id hâlâ bulunamıyorsa client_request_id değerini teknik desteğe göndererek konumlandırma isteyin.

Sesle üretim sonuçlarını sorgulama

Uç nokta: GET /api/music/generate-with-voice/results

Faturalama: ücretsiz.

Sorgu parametreleri

İstek örneği

curl -X GET "https://www.suno-api.io/api/music/generate-with-voice/results?client_request_id=cu_1780480000_abcd1234" \
  -H "Authorization: Bearer YOUR_API_KEY"

Üretim sürerken yanıt örneği

{
  "success": true,
  "message": "",
  "data": {
    "client_request_id": "cu_1780480000_abcd1234",
    "status": "processing",
    "items": [
      {
        "song_id": "",
        "placeholder_id": "pending:cu_1780480000_abcd1234:0",
        "client_request_id": "cu_1780480000_abcd1234",
        "client_request_index": 0,
        "status": "processing",
        "type": "voice_generate",
        "title": "Yaz gecesinde deniz meltemi"
      }
    ]
  }
}

Üretim tamamlandığında yanıt örneği

{
  "success": true,
  "message": "",
  "data": {
    "client_request_id": "cu_1780480000_abcd1234",
    "status": "completed",
    "items": [
      {
        "song_id": "song_abc123",
        "client_request_id": "cu_1780480000_abcd1234",
        "client_request_index": 0,
        "status": "completed",
        "type": "voice_generate",
        "title": "Yaz gecesinde deniz meltemi",
        "audio_url": "https://...",
        "image_url": "https://...",
        "duration": 180.5
      }
    ]
  }
}

En üst düzey status değerleri

8. Tek dosya indirin

Uç nokta: POST /api/music/download-file

Gövde parametreleri

İstek örneği

curl -X POST https://www.suno-api.io/api/music/download-file \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "song_id": "song_abc123",
    "kind": "audio"
  }' \
  --output song.mp3

Yanıt bir dosya akışıdır; Content-Type ve dosya adı arka ucun döndürdüğü değerlere göre belirlenir.

9. Şarkı kaynaklarını paket olarak indirin

Uç nokta: POST /api/music/download-all

Gövde parametreleri

İstek örneği

curl -X POST https://www.suno-api.io/api/music/download-all \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "song_id": "song_abc123"
  }' \
  --output song.zip

Paket genelde sesi, kapağı ve metadata.json dosyasını içerir; henüz üretilmemiş bir kaynak türü arşive girmez.

Sık karşılaşılan hatalar

Bu grubun hataları her zaman HTTP 200 döner: başarıyı gövdedeki success alanına göre değerlendirin (false başarısızlıktır, neden message içindedir) ve yalnızca HTTP durum koduna bakmayın. Ses silmenin tam anlamı (silindikten sonra kullanılabilir mi, geri getirilebilir mi) 6. bölümdedir.