API de generare în modul simplu

Actualizat pe 2026-09-18 · echipa Suno-API

Descrierea endpoint-ului

Generarea în modul simplu transformă o descriere de o propoziție într-o piesă completă. Serviciul scrie versurile, melodia, aranjamentul și vocea pe baza descrierii tale.

Endpoint: POST /api/music/create

Facturare: Cu plată, momentan implicit 0,6 ¥ per apel. Un apel returnează de obicei 2 piese; suma efectiv debitată urmează configurația actuală de prețuri din back-office.

Max Mode / Variety: acest endpoint acceptă parametrii opționali max_mode și variety (0-4). Cu max_mode activat, acest apel este facturat la dublu (0,6 ¥ → 1,2 ¥ per apel); variety nu costă nimic în plus. Ce înseamnă și cum se trimit este în secțiunea „Parametri avansați” din Prezentarea noului API.

Model recomandat: suno-v6

Timpii de așteptare și timeout-urile (important): este un endpoint sincron — comanda este acceptată și transmisă spre generare doar când sosește răspunsul. Din măsurători, majoritatea cererilor răspund în 1-3 secunde, circa 10% depășesc 30 de secunde, iar cea mai lungă este de aproximativ 230 de secunde. Setează timeout-ul clientului la 300 de secunde sau mai mult; lipsa unui răspuns nu înseamnă că nu s-a generat nimic, iar reîncercarea imediat după un timeout dublează comanda și debitează din nou. Dacă conexiunea s-a întrerupt, verifică mai târziu cu GET /api/music/songs. Vezi „Timpii de așteptare și setarea timeout-ului” în Prezentarea noului API.

Parametrii cererii

Headers

Parametri din body

Exemple de cerere

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": "o piesă pop mandarină vioaie despre vara la mare",
    "instrumental": false,
    "wait_completion": false
  }'

Material de referință references (opțional)

references este un array care atașează „material de referință” acestei generări. Este complet opțional (omis se comportă exact ca înainte) și poți atașa un singur tip sau orice combinație.

Tipuri de element

Reguli

• Ordinea pieselor de referință este ordinea lor semantică: trimite-le în ordinea dorită (de exemplu „melodia din prima, vocea din a doua”).
• style_prompt / lyrics / duration_s pot fi omise; platforma le completează din informațiile piesei, iar ce trimiți tu are prioritate.
• La piesele pur instrumentale, lyrics poate fi "" sau "[Instrumental]".
• Imaginile de referință acceptă jpeg / png / webp, până la 10MB fiecare, trimise împreună cu body-ul ca base64.
• Când atașezi mai multe piese de referință, folosește și accept_mode=async (vezi „Modul chitanță de acceptare” mai sus): serviciul trebuie să pregătească mai întâi materialul, așa că o așteptare sincronă poate fi lungă.

Exemplu: două piese de referință

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": "combină aceste idei într-o singură piesă",
    "references": [
      { "type": "song", "song_id": "43eb711d-81f8-4e72-a68e-b2498bac88f9" },
      { "type": "song", "song_id": "a90438d2-35fc-4443-88f4-56531e6e5d24" }
    ]
  }'

Exemplu: piesă de referință + voce veche

{
  "model": "suno-v6",
  "description": "cântă aceste idei cu această voce",
  "references": [
    { "type": "song",  "song_id": "43eb711d-81f8-4e72-a68e-b2498bac88f9" },
    { "type": "voice", "voice_id": "5813cbe1-36f1-414a-a9a8-4d399dfeb292" }
  ]
}

Exemplu: piesă de referință + imagine de referință

{
  "model": "suno-v6",
  "description": "surprinde atmosfera acestei imagini",
  "references": [
    { "type": "song",  "song_id": "43eb711d-81f8-4e72-a68e-b2498bac88f9" },
    { "type": "image", "base64": "data:image/jpeg;base64,/9j/4AAQ..." }
  ]
}

Erori de parametri

Aceste cazuri returnează HTTP 400, blocate înainte de orice facturare, deci nu costă nimic:

Numărul din references[0] este indexul acelui element în array, așa că elementul problematic este ușor de găsit.

Răspuns

Un array de piese, de obicei cu 2 sarcini sau piese.

[
  {
    "song_id": "clip_id",
    "song_title": "Briza de mare de vară",
    "status": "pending",
    "description": "o piesă pop mandarină vioaie despre vara la mare",
    "audio_url": "",
    "cover_url": "",
    "video_url": "",
    "model_version": "suno-v6",
    "generation_type": "generate",
    "created_at": "2026-05-21T10:00:00Z"
  }
]

Modul chitanță de acceptare (opțional, recomandat clienților care nu trebuie să țină conexiuni lungi)

Implicit, acest endpoint este sincron: sosirea răspunsului înseamnă că comanda a fost acceptată, iar așteptările măsurate pot ajunge la circa 230 de secunde. Dacă clientul tău nu trebuie să țină o conexiune lungă, activează modul chitanță de acceptare — oricare dintre variante funcționează:

• adaugă "accept_mode": "async" în body-ul cererii
• adaugă headerul X-Accept-Mode: async

Cu el activ, endpoint-ul returnează imediat HTTP 202, ceea ce înseamnă doar „acceptat și pus în coada de generare”, în timp ce generarea continuă în fundal:

{
  "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" }
    ]
  }
}

Faza de acceptare nu returnează un song_id. Nu există încă un ID real de piesă, iar nici request_id, nici tasks[].index nu sunt ID-uri de piesă — nu le salva ca song_id. song_id-ul real apare în interogarea de progres de mai jos.

Interogarea progresului acceptării

Endpoint: GET /api/music/requests/{request_id} (gratuit, autentificare cu aceeași cheie API)

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" }
    ]
  }
}

Ce înseamnă fiecare valoare status:

Fiecare sarcină are și propriul tasks[].status, cu aceleași valori ca în API-ul de interogare a pieselor: pending (transmisă, în generare), processing, completed, failed. Elementele de sarcină pot conține și title, duration și un audio_url deja înregistrat; ce lipsește pur și simplu nu e generat încă.

Când ai song_id-ul real, continuă cu API-ul de interogare a pieselor sau cu endpoint-urile de descărcare.

Exemplu în Python

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": "o piesă pop vioaie", "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

Compatibilitate și observații

• Fără accept_mode, comportamentul este exact ca înainte: așteptare sincronă, răspuns 200 și array de piese. Integrările existente nu trebuie să schimbe nimic.
• Acest comutator funcționează momentan doar pe POST /api/music/create și POST /api/music/create/custom; celelalte endpoint-uri de generare nu îl acceptă încă.
• Trimite și un Idempotency-Key (propriul tău șir unic, ≤128 de caractere): aceeași cheie este acceptată o singură dată, o repetare returnează aceeași chitanță și nu se debitează de două ori. În modul asincron acest lucru contează și mai mult.
• Cu accept_mode=async, wait_completion este ignorat (chitanța se întoarce imediat, fără să aștepte piesele).
• Suma este totuși consumată în avans la acceptarea comenzii; o generare eșuată este returnată automat integral.
• Limita câmpului de text: description are cel mult 3000 de caractere (numărate în caractere Unicode, un caracter han contează ca 1). Un text mai lung returnează direct HTTP 400, nu intră în generare și nu se facturează, iar mesajul de eroare indică lungimea măsurată, de exemplu description must not exceed 3000 characters; received 4120. Acest endpoint nu are câmpuri de versuri/stil; pentru ele vezi „Limita câmpului de text” în API-ul de generare în modul personalizat. Regulile generale sunt în „Limitele câmpurilor de text” din Prezentarea noului API.
• Fără references, comportamentul, prețul și răspunsul sunt exact ca înainte: integrările existente nu trebuie să schimbe nimic.
• Când este atașat material de referință (mai ales mai multe piese), preferă modul chitanță accept_mode=async în locul unei așteptări sincrone lungi; timpul de pregătire depinde de cantitatea și sursa materialului.

Pașii următori

Dacă piesele nu sunt gata când sosește răspunsul, ia rezultatul final prin API-ul de interogare a pieselor.

Exemplu de integrare Node/Electron

Dacă integrezi generarea standard în procesul principal Electron, într-un server Node.js sau într-un client desktop, fluxul recomandat este:

1. Apelează POST /api/music/create pentru a crea sarcina de generare.
2. Citește song_id sau id din răspuns.
3. Apelează POST /api/music/query la fiecare 2 secunde pentru a verifica starea.
4. Consideră generarea încheiată imediat ce audio_url apare în rezultat.

Nu mai folosi căile vechi POST /api/generate sau GET /api/clip?id=...; nu fac parte din suprafața publică de integrare recomandată în prezent.

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);

În proiectele reale ține cheia API într-o variabilă de mediu a serverului, în setările clientului desktop sau într-un depozit sigur — niciodată în codul de front-end și niciodată comisă într-un depozit.