Basit mod üretim API'si

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

Uç nokta açıklaması

Basit mod üretimi, tek cümlelik bir açıklamayı eksiksiz bir şarkıya dönüştürür. Servis; sözleri, melodiyi, düzenlemeyi ve vokali açıklamanızdan yola çıkarak kendisi yazar.

Uç nokta: POST /api/music/create

Faturalama: Ücretli, şu anda varsayılan olarak çağrı başına 0,6 ¥. Her çağrı genellikle 2 şarkı döndürür; gerçekte tahsil edilen tutar güncel arka ofis fiyat yapılandırmasına göre belirlenir.

Max Mode / Variety: bu uç nokta isteğe bağlı max_mode ve variety (0-4) parametrelerini destekler. max_mode açıkken bu çağrı 2 kat fiyattan faturalanır (0,6 ¥ → 1,2 ¥ / çağrı); variety için ek ücret alınmaz. Anlamları ve nasıl gönderilecekleri Yeni API genel bakışı sayfasındaki "Gelişmiş parametreler" bölümündedir.

Önerilen model: suno-v6

Bekleme süreleri ve zaman aşımları (önemli): bu uç nokta senkrondur — sipariş ancak yanıt geldiğinde kabul edilir ve üretime verilir. Ölçümlere göre isteklerin çoğu 1-3 saniyede yanıtlanır, yaklaşık %10'u 30 saniyeyi aşar ve en uzunu yaklaşık 230 saniyedir. İstemci zaman aşımını 300 saniye veya üzerine ayarlayın; yanıt gelmemesi hiçbir şey üretilmediği anlamına gelmez ve zaman aşımından hemen sonra yeniden denemeyin (siparişi çoğaltır ve tekrar ücret alır). Bağlantı koptuysa daha sonra GET /api/music/songs ile kontrol edin. Yeni API genel bakışı sayfasındaki "Bekleme süreleri ve zaman aşımı ayarları" bölümüne bakın.

İstek parametreleri

Headers

Gövde parametreleri

İstek örnekleri

curl -X POST https://www.suno-api.io/api/music/create \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "suno-v6",
    "description": "deniz kenarında yaz hakkında neşeli bir Mandarin pop şarkısı",
    "instrumental": false,
    "wait_completion": false
  }'

Referans materyal references (isteğe bağlı)

references, bu üretime "referans materyal" ekleyen bir dizidir. Tamamen isteğe bağlıdır (atlanırsa davranış aynen eskisi gibidir) ve tek bir tür ya da herhangi bir kombinasyon eklenebilir.

Öğe türleri

Kurallar

• Referans şarkıların sırası anlamsal sırasıdır: istediğiniz sırayla gönderin (örneğin "melodi birinciden, vokal ikinciden").
• style_prompt / lyrics / duration_s atlanabilir; platform onları şarkı bilgisinden tamamlar ve gönderdiğiniz değer geçerli olur.
• Yalnızca enstrümantal şarkılarda lyrics değeri "" veya "[Instrumental]" olabilir.
• Referans görseller jpeg / png / webp destekler, her biri en fazla 10MB, istek gövdesiyle birlikte base64 olarak gönderilir.
• Birden fazla referans şarkı eklerken ayrıca accept_mode=async kullanın (yukarıdaki "Kabul makbuzu modu"): servis önce materyali hazırlamalı, bu yüzden senkron bekleme uzun olabilir.

Örnek: iki referans şarkı

curl -X POST https://www.suno-api.io/api/music/create \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "suno-v6",
    "description": "bu fikirleri tek bir şarkıda birleştir",
    "references": [
      { "type": "song", "song_id": "43eb711d-81f8-4e72-a68e-b2498bac88f9" },
      { "type": "song", "song_id": "a90438d2-35fc-4443-88f4-56531e6e5d24" }
    ]
  }'

Örnek: referans şarkı + eski ses

{
  "model": "suno-v6",
  "description": "bu fikirleri bu sesle söyle",
  "references": [
    { "type": "song",  "song_id": "43eb711d-81f8-4e72-a68e-b2498bac88f9" },
    { "type": "voice", "voice_id": "5813cbe1-36f1-414a-a9a8-4d399dfeb292" }
  ]
}

Örnek: referans şarkı + referans görsel

{
  "model": "suno-v6",
  "description": "bu görselin havasını yakala",
  "references": [
    { "type": "song",  "song_id": "43eb711d-81f8-4e72-a68e-b2498bac88f9" },
    { "type": "image", "base64": "data:image/jpeg;base64,/9j/4AAQ..." }
  ]
}

Parametre hataları

Bu durumlar HTTP 400 döndürür, herhangi bir ücret alınmadan önce engellenir, yani hiçbir maliyeti yoktur:

references[0] içindeki sayı, o öğenin dizideki indeksidir; böylece hatalı öğeyi bulmak kolaydır.

Yanıt

Genellikle 2 görev veya şarkı içeren bir şarkı dizisi.

[
  {
    "song_id": "clip_id",
    "song_title": "Yaz Deniz Esintisi",
    "status": "pending",
    "description": "deniz kenarında yaz hakkında neşeli bir Mandarin pop şarkısı",
    "audio_url": "",
    "cover_url": "",
    "video_url": "",
    "model_version": "suno-v6",
    "generation_type": "generate",
    "created_at": "2026-05-21T10:00:00Z"
  }
]

Kabul makbuzu modu (isteğe bağlı, uzun bağlantı tutmaması gereken istemciler için önerilir)

Varsayılan olarak bu uç nokta senkrondur: yanıtın gelmesi siparişin kabul edildiği anlamına gelir ve ölçülen bekleme süreleri yaklaşık 230 saniyeye çıkabilir. İstemciniz uzun bağlantı tutmamalıysa kabul makbuzu modunu açın — ikisinden biri yeterlidir:

• istek gövdesine "accept_mode": "async" ekleyin
• X-Accept-Mode: async başlığını ekleyin

Açıkken uç nokta hemen HTTP 202 döndürür; bu yalnızca "kabul edildi ve üretim kuyruğuna alındı" anlamına gelir, üretim arka planda devam eder:

{
  "success": true,
  "data": {
    "request_id": "ac_20260920092714315816800d76fv3nq",
    "status": "queued",
    "accepted_at": 1789896434,
    "pre_consumed_quota": 300000,
    "tasks": [
      { "index": 0, "status": "queued" },
      { "index": 1, "status": "queued" }
    ]
  }
}

Kabul aşamasında song_id dönmez. Henüz gerçek bir şarkı ID'si yoktur ve ne request_id ne de tasks[].index bir şarkı ID'sidir — bunları song_id olarak kaydetmeyin. Gerçek song_id aşağıdaki ilerleme sorgusunda görünür.

Kabul ilerlemesini sorgulama

Uç nokta: GET /api/music/requests/{request_id} (ücretsiz, aynı API anahtarıyla kimlik doğrular)

curl "https://www.suno-api.io/api/music/requests/ac_20260920092714315816800d76fv3nq" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "success": true,
  "data": {
    "request_id": "ac_20260920092714315816800d76fv3nq",
    "status": "processing",
    "tasks": [
      { "index": 0, "status": "processing", "song_id": "f3fa09f5-3d55-4953-826c-0d23f043ec57" },
      { "index": 1, "status": "processing", "song_id": "5fcafe3e-3fae-4d64-8f66-c01bc027b0c3" }
    ]
  }
}

status değerlerinin anlamı:

Her görevin ayrıca kendi tasks[].status değeri vardır ve değerler şarkı sorgulama API'si ile aynıdır: pending (gönderildi, üretiliyor), processing, completed, failed. Görev öğelerinde title, duration ve kayıtlı bir audio_url de olabilir; olmayan şey henüz üretilmemiş demektir.

Gerçek song_id'yi aldıktan sonra şarkı sorgulama API'si veya indirme uç noktalarıyla devam edin.

Python örneği

import time
import requests

BASE = "https://www.suno-api.io"
HEADERS = {"Authorization": "Bearer YOUR_API_KEY", "Content-Type": "application/json"}

accepted = requests.post(
    f"{BASE}/api/music/create",
    headers={**HEADERS, "Idempotency-Key": "your-own-unique-key"},
    json={"description": "neşeli bir pop şarkısı", "model": "suno-v6", "accept_mode": "async"},
    timeout=300,
).json()["data"]

request_id = accepted["request_id"]
while True:
    time.sleep(5)
    progress = requests.get(
        f"{BASE}/api/music/requests/{request_id}", headers=HEADERS, timeout=60
    ).json()["data"]
    if progress["status"] in ("completed", "failed"):
        print(progress)
        break

Uyumluluk ve notlar

• accept_mode olmadan davranış tam olarak eskisi gibidir: senkron bekleme, 200 ve şarkı dizisi döner. Mevcut entegrasyonların kod değiştirmesi gerekmez.
• Bu anahtar şu anda yalnızca POST /api/music/create ve POST /api/music/create/custom üzerinde çalışır; diğer üretim uç noktaları henüz desteklemez.
• Ayrıca bir Idempotency-Key gönderin (kendi benzersiz dizeniz, ≤128 karakter): aynı anahtar yalnızca bir kez kabul edilir, tekrar aynı makbuzu döndürür ve iki kez ücret alınmaz. Asenkron modda bu özellikle önemlidir.
• accept_mode=async ile wait_completion yok sayılır (makbuz şarkıları beklemeden hemen döner).
• Tutar yine sipariş kabul edilirken önceden tahsil edilir; başarısız üretim otomatik olarak tamamen iade edilir.
• Metin alanı sınırı: description en fazla 3000 karakter alır (Unicode karakterle sayılır, bir Han karakteri 1 sayılır). Daha uzun metin doğrudan HTTP 400 döner, üretime girmez ve ücret alınmaz; hata mesajı ölçülen uzunluğu verir, örneğin description must not exceed 3000 characters; received 4120. Bu uç noktada söz/stil alanları yoktur; onlar için özel mod üretim API'sindeki "Metin alanı sınırı" bölümüne bakın. Genel kurallar Yeni API genel bakışının "Metin alanı sınırları" bölümündedir.
• references olmadan davranış, fiyat ve yanıt tam olarak eskisi gibidir: mevcut entegrasyonların kod değiştirmesi gerekmez.
• Referans materyal eklendiğinde (özellikle birkaç şarkı), uzun senkron beklemek yerine accept_mode=async makbuz modunu tercih edin; materyalin hazırlanma süresi miktarına ve kaynağına bağlıdır.

Sonraki adımlar

Yanıt geldiğinde şarkılar bitmemişse, nihai sonucu şarkı sorgulama API'si ile alın.

Node/Electron entegrasyon örneği

Standart üretimi Electron ana sürecine, bir Node.js sunucusuna veya masaüstü istemcisine entegre ediyorsanız önerilen akış şudur:

1. Üretim görevini oluşturmak için POST /api/music/create çağırın.
2. Yanıttan song_id veya id okuyun.
3. Durumu kontrol etmek için her 2 saniyede POST /api/music/query çağırın.
4. Sorgu sonucunda audio_url göründüğünde üretimi tamamlanmış sayın.

Eski POST /api/generate veya GET /api/clip?id=... yollarını kullanmayı bırakın; bunlar şu anda önerilen genel entegrasyon yüzeyinin parçası değildir.

const http = require('http');
const https = require('https');

const BASE_URL = 'https://www.suno-api.io';
const MODEL = 'suno-v6';
const POLL_INTERVAL_MS = 2000;
const MAX_POLL_ATTEMPTS = 60;

function sleep(ms) {
  return new Promise((resolve) => setTimeout(resolve, ms));
}

function requestJson(urlString, apiKey, body) {
  const url = new URL(urlString);
  const transport = url.protocol === 'https:' ? https : http;
  const payload = JSON.stringify(body);

  return new Promise((resolve, reject) => {
    const req = transport.request(
      {
        method: 'POST',
        hostname: url.hostname,
        port: url.port || undefined,
        path: `${url.pathname}${url.search}`,
        headers: {
          Authorization: `Bearer ${apiKey}`,
          'Content-Type': 'application/json',
          'Content-Length': Buffer.byteLength(payload),
        },
      },
      (res) => {
        let raw = '';

        res.setEncoding('utf8');
        res.on('data', (chunk) => {
          raw += chunk;
        });
        res.on('end', () => {
          const data = raw ? JSON.parse(raw) : {};

          if (!res.statusCode || res.statusCode < 200 || res.statusCode >= 300) {
            reject(new Error(`Suno API request failed: HTTP ${res.statusCode} ${raw}`));
            return;
          }

          resolve(data);
        });
      }
    );

    req.on('error', reject);
    req.write(payload);
    req.end();
  });
}

function getPayload(response) {
  return response && response.data !== undefined ? response.data : response;
}

function toSongList(payload) {
  if (Array.isArray(payload)) return payload;
  if (Array.isArray(payload?.songs)) return payload.songs;
  if (Array.isArray(payload?.clips)) return payload.clips;
  return payload ? [payload] : [];
}

function collectSongIds(createResponse) {
  return toSongList(getPayload(createResponse))
    .map((song) => song.song_id || song.id)
    .filter(Boolean);
}

async function generateSunoSong({ apiKey, description, instrumental = false }) {
  const createResponse = await requestJson(`${BASE_URL}/api/music/create`, apiKey, {
    description,
    model: MODEL,
    instrumental,
    wait_completion: false,
  });

  const songIds = collectSongIds(createResponse);
  if (songIds.length === 0) {
    throw new Error(`Suno API did not return song ids: ${JSON.stringify(createResponse)}`);
  }

  for (let attempt = 0; attempt < MAX_POLL_ATTEMPTS; attempt += 1) {
    await sleep(POLL_INTERVAL_MS);

    const queryResponse = await requestJson(`${BASE_URL}/api/music/query`, apiKey, {
      song_ids: songIds,
      model: MODEL,
    });

    const songs = toSongList(getPayload(queryResponse));
    const completed = songs.find((song) => song.audio_url);

    if (completed) {
      return {
        audioUrl: completed.audio_url,
        title: completed.song_title || completed.title || 'Suno Song',
        duration: completed.duration,
      };
    }

    const allFailed = songs.length > 0 && songs.every((song) =>
      ['failed', 'error', 'rejected'].includes(String(song.status || '').toLowerCase())
    );

    if (allFailed) {
      throw new Error(`Suno generation failed: ${JSON.stringify(songs)}`);
    }
  }

  throw new Error('Suno generation timed out after 120 seconds. Please query again later.');
}

// Usage:
// generateSunoSong({
//   apiKey: process.env.SUNO_API_KEY,
//   description: 'A bright pop song about the ocean in summer',
// }).then(console.log).catch(console.error);

Gerçek projelerde API anahtarını sunucu ortam değişkeninde, masaüstü istemci ayarlarında veya güvenli bir depoda tutun — asla ön yüz kodunda ve asla depoya işlenmiş olarak.