Grimoire

Generare muzică și audio asincron cu Venice

3 min read

Generare muzică și audio asincron cu Venice

Ce face

venice-audio-music este capabilitatea pentru generare asincronă de muzică și audio lung prin Venice: piese, jingles, score-uri, soundscape-uri sau narațiuni care durează prea mult pentru un apel sincron.

Fluxul canonic este:

POST /api/v1/audio/quote      → preț estimat în USD
POST /api/v1/audio/queue      → { model, queue_id }
POST /api/v1/audio/retrieve   → status JSON sau audio binar
POST /api/v1/audio/complete   → finalizează și șterge media

Pentru text-to-speech scurt, folosește capabilitatea sincronă venice-audio-speech. Acest flux este pentru joburi care pot dura peste aproximativ 20 de secunde sau care au pricing pe durată ori pe număr de caractere.

Când îmi folosește

Folosește această capabilitate când vrei:

  • o piesă muzicală completă;
  • un jingle;
  • fundal sonor sau soundscape;
  • score pentru video, joc, intro sau atmosferă;
  • narațiune lungă, unde prețul poate depinde de numărul de caractere;
  • control pe durată, limbă, voce, viteză, versuri sau mod instrumental, dacă modelul le suportă.

Înainte de jobul real, cere întotdeauna /audio/quote. Generarea poate fi taxată per job, per secundă, pe praguri de durată sau per mie de caractere. Quote-ul trebuie folosit ca poartă de buget înainte de queue, nu ca ornament administrativ.

Cum îl invoc / declanșez

Nu există un trigger conversațional public unic definit de sursă. Invocarea depinde de runtime-ul sau clientul care integrează API-ul.

La nivel API:

  1. Listezi modelele cu GET /api/v1/models?type=music.
  2. Alegi modelul și verifici model_spec.
  3. Ceri prețul cu POST /api/v1/audio/quote.
  4. Trimiți jobul cu POST /api/v1/audio/queue.
  5. Păstrezi împreună model și queue_id; ambele sunt necesare mai departe.
  6. Faci polling cu POST /api/v1/audio/retrieve.
  7. Dacă răspunsul este audio binar, îl salvezi local.
  8. Apelezi POST /api/v1/audio/complete, dacă nu ai folosit delete_media_on_completion: true la retrieve.

La queue, prompt este obligatoriu și descrie genul, atmosfera, tempo-ul și instrumentele. lyrics_prompt se trimite numai dacă modelul suportă versuri și este obligatoriu dacă lyrics_required=true. force_instrumental, lyrics_optimizer, voice, language_code și speed se folosesc doar când model_spec le permite.

Exemplu practic

Exemplu: piesă instrumentală indie-folk de 60 de secunde.

curl https://api.venice.ai/api/v1/audio/quote \
  -H "Authorization: Bearer $VENICE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "elevenlabs-music",
    "duration_seconds": 60
  }'

Răspunsul are forma:

{"quote": 0.48}

Dacă prețul este acceptabil, trimiți jobul:

curl https://api.venice.ai/api/v1/audio/queue \
  -H "Authorization: Bearer $VENICE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "elevenlabs-music",
    "prompt": "Uplifting indie-folk acoustic track, 120 BPM, major key.",
    "duration_seconds": 60,
    "force_instrumental": true
  }'

Răspunsul conține model și queue_id. La polling:

curl https://api.venice.ai/api/v1/audio/retrieve \
  -H "Authorization: Bearer $VENICE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"elevenlabs-music","queue_id":"..."}' \
  --output track.mp3

Dacă jobul încă rulează, primești JSON cu status: "PROCESSING", plus timpi orientativi precum average_execution_time și execution_duration. Dacă e gata, corpul răspunsului este audio binar, de exemplu audio/mpeg.

Vezi și All guides pentru restul capabilităților.

Output / unde aterizează

Outputul final este corp audio binar returnat de /audio/retrieve. Clientul trebuie să salveze bytes într-un fișier, de exemplu track.mp3.

Media stocată de Venice este temporară. După descărcare, finalizează cu:

curl https://api.venice.ai/api/v1/audio/complete \
  -H "Authorization: Bearer $VENICE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"elevenlabs-music","queue_id":"..."}'

Dacă ai trimis delete_media_on_completion: true la retrieve, pasul manual de cleanup nu mai este necesar.

Limite / gotchas

Verifică modelul înainte de queue. model_spec poate declara supports_lyrics, lyrics_required, supports_lyrics_optimizer, supports_force_instrumental, supports_speed, supports_language_code, voices, default_voice, limite de prompt, limite de viteză și forma de pricing.

lyrics_optimizer: true nu se combină cu un lyrics_prompt non-empty; rezultatul este 400. duration_seconds, voice, language_code și speed trebuie să respecte limitele modelului.

Erori uzuale: 400 parametri greșiți, 401 autentificare sau model Pro-only, 402 balance insuficient, 404 queue_id necunoscut sau expirat, 422 content policy, 429 rate limit, 500/503 inferență sau capacitate.

Nu face polling agresiv. 2–5 secunde sunt suficiente; poți folosi average_execution_time ca prim delay orientativ. execution_duration este timpul cumulativ de la enqueue.

Graph View