# Music Room (/ro/docs/gateway/music-room)

Music Room din codai Studio — o echipă de agenți cu roluri scrie, cântă și mixează o piesă care sună cântată de oameni, cu trei porți de aprobare, o cotă lunară în plan și o creație audio editabilă.

**Music Room** este o echipă de agenți cu roluri care face împreună o piesă: un producător o planifică, un compozitor și un textier o scriu, un aranjor construiește forma, instrumentiștii de studio își scriu partiturile pe instrumente reale eșantionate, un producător de voce adaugă vocea, inginerii de mixaj și de mastering o finalizează, un critic o ascultă, iar o verificare de drepturi compară melodia cu un corpus de referință. Rezultatul este o [creație audio](./audio-creatives.mdx) obișnuită: fiecare notă scrisă de un agent este o operație editabilă, cu anulare, și poți prelua oricând controlul în editorul multipistă.

| Metodă | Cale | Rezultat |
| --- | --- | --- |
| `POST` | `/v1/studio/music-room` | Pornește o piesă (202, acceptă `Idempotency-Key`) |
| `GET` | `/v1/studio/music-room` | Piesele tale, cele mai noi primele (`?limit` 1–100, `?before` dată ISO) |
| `GET` | `/v1/studio/music-room/quota` | `{ plan, included, used, remaining, period_end }` |
| `GET` | `/v1/studio/music-room/{id}` | Piesa; citirea avansează fluxul |
| `POST` | `/v1/studio/music-room/{id}/choose` | Răspunde la poarta deschisă |
| `POST` | `/v1/studio/music-room/{id}/direct` | Vorbește cu un instrumentist (202, acceptă `Idempotency-Key`) |

## Cum se face o piesă [#cum-se-face-o-piesă]

```
brief ─► plan ─► [poarta 1: alegi o variantă de plan] ─► compoziție ─► versuri ─► aranjament ─► partituri
      ─► umanizare ─► randare demo ─► [poarta 2: aprobi demo-ul sau dai indicații unui instrumentist]
      ─► voce ─► mixaj ─► mastering ─► critică (cel mult 2 runde de corecturi) ─► [poarta 3: aprobi mixajul final] ─► gata
```

Agenții nu scriu niciodată direct audio. Ei scriu partituri simbolice pe o grilă de timpi; cod determinist umanizează ritmul și dinamica pentru fiecare instrumentist; `codai-studio-media` randează pistele cu instrumente eșantionate; ACE-Step cântă vocea peste o pistă-ghid randată, verificată prin recunoaștere vocală și reparată silabă cu silabă. Criticul notează groove-ul, armonia, melodia, aranjamentul, mixajul, cât de omenesc sună și potrivirea cu genul, apoi trimite corecturi țintite instrumentiștilor de cel mult două ori. `robot_score` (0 omenesc … 1 robotic) este o măsură simbolică a obișnuitelor „semne de AI”, iar `copy_risk` arată asemănarea melodiei cu melodii cunoscute.

## Pornirea unei piese [#pornirea-unei-piese]

```bash
curl https://ai.codai.ro/v1/studio/music-room \
  -H "Authorization: Bearer $CODAI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: song-42" \
  -d '{
    "brief": "o melodie veselă de nuntă despre doi prieteni care se reîntâlnesc",
    "language": "ro",
    "genre": "hora",
    "duration_seconds": 150,
    "vocals": true
  }'
```

| Câmp | Implicit | Note |
| --- | --- | --- |
| `brief` | obligatoriu | 10–2000 de caractere: ocazie, stare, poveste, public; fără nume de artiști |
| `language` | `ro` | `ro` sau `en` — limba versurilor |
| `genre` | alege producătorul | Id-ul unui pachet de gen: `pop`, `jingle`, `rock`, `indie`, `hiphop`, `trap`, `cinematic`, `lofi`, `ballad`, `hora`, `sarba`, `doina`, `colind`, `lautareasca`, `manele`, `pop_folk_ro`, `fanfara`, `cocek`, `kolo`… |
| `duration_seconds` | — | 6–240 (cel mult patru minute) |
| `vocals` | `true` | `false` pentru o piesă instrumentală |
| `timbre` | ales după gen | Id-ul unui timbru vocal |
| `voice_passport_id` | — | Cântă cu vocea ta (beta): una dintre vocile tale personalizate cu consimțământ activ pentru cântat. Vezi [Pașaport de voce](#pașaport-de-voce-beta) |
| `instruments` | — | Id-urile instrumentelor pe care trebuie să le folosească trupa (`drums.kit_rock`, `balkan.accordion`…) |
| `auto` | `false` | Sare peste cele trei porți (varianta de plan 0, demo și final aprobate) |
| `budget_micro_usd` | `10000000` | Plafonul unei piese peste cotă, cel mult `20000000` (20 $) |
| `title` | — | Până la 200 de caractere |

Răspunsul este `202` cu piesa (`object: "studio.music_room"`). Interoghează `GET /v1/studio/music-room/{id}` la fiecare 20–60 de secunde; procesul de fundal avansează piesa și dacă nu întreabă nimeni.

### Pașaport de voce (beta) [#pașaport-de-voce-beta]

Vocea ta personalizată poate cânta în piesele tale după ce dai pentru ea un **consimțământ separat și revocabil pentru cântat**: în cardul „Cântat (beta)” al vocii din hub citești cu voce tare declarația pentru cântat și înregistrezi o mostră scurtă cântată (aceeași verificare în aplicație ca la crearea vocii), ceea ce apelează `POST /v1/studio/voices/{id}/singing-consent`. `DELETE /v1/studio/voices/{id}/singing-consent` retrage doar scopul „cântat”; ștergerea vocii retrage tot. Producătorul vocal trimite mostra ta cântată la ACE-Step ca referință de timbru, deci rezultatul **aproximează timbrul tău; nu este o clonă fidelă**. Disponibil doar unde clonarea vocii este activă pentru contul tău.

`warnings` îți spune ce s-a întâmplat: `voice_passport_beta` (cântat cu vocea ta), `voice_passport_needs_singing_consent` (fără consimțământ activ pentru cântat sau retras în timpul piesei), `voice_passport_not_found` (nu este una dintre vocile tale active), `voice_passport_unavailable` (clonarea vocii nu este activă pentru contul tău sau vocea este suspendată), `voice_passport_lyrics_refused` (versurile nu au trecut verificarea de siguranță). În toate cazurile în afară de primul piesa se face tot cu `timbre`.

## Cele trei porți [#cele-trei-porți]

Când piesa ajunge la o poartă, răspunde cu `status: "waiting"` și `gate.kind` completat, iar nimic nu mai rulează până nu răspunzi:

| Poartă | Ce vezi | Răspuns |
| --- | --- | --- |
| `plan` | Până la 3 variante de plan în `gate.variants`: titlu, gen, BPM, măsură, mod, secțiuni și instrumente, fiecare cu argumentul producătorului | `{"gate": "plan", "variant": 0}` (0–2) |
| `demo` | Demo-ul aranjat în `demo_asset_id` și echipa, cu argumentul fiecărui instrumentist | `{"gate": "demo", "approve": true}` |
| `final` | Mixajul final în `final_asset_id`, pistele separate în `stems_asset_ids`, ultima recenzie a criticului | `{"gate": "final", "approve": true}` |

```bash
curl https://ai.codai.ro/v1/studio/music-room/$ID/choose \
  -H "Authorization: Bearer $CODAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"gate": "plan", "variant": 1}'
```

La poarta de demo sau la cea finală poți și să **dai indicații unui instrumentist**, ca un producător în studio. Acesta își recântă partea (o secțiune sau toată piesa), iar demo-ul se randează din nou:

```bash
curl https://ai.codai.ro/v1/studio/music-room/$ID/direct \
  -H "Authorization: Bearer $CODAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"role": "drums", "section_id": "chorus1", "direction": "mai relaxat pe refren, mai puține breakuri, mai multe ghost notes"}'
```

`role` este unul dintre `producer`, `composer`, `lyricist`, `arranger`, `drums`, `bass`, `guitar`, `keys`, `strings`, `brass`, `winds`, `balkan_lead`, `balkan_rhythm`, `percussion`, `synth`, `vocal_producer`, `sound_designer`, `mix_engineer`, `mastering_engineer`, `critic`, `rights`; `direction` are cel mult 500 de caractere. O poartă lăsată fără răspuns 7 zile face piesa să eșueze (`error: "gate_expired"`) și eliberează orice rezervare.

## Cotă și buget [#cotă-și-buget]

Piesele se numără pe lună calendaristică (UTC): fiecare piesă Music Room care a ajuns la `ready` sau încă rulează.

| Plan | Piese incluse pe lună |
| --- | --- |
| Pro | 4 |
| Builder | 12 |
| Max | 30 |
| Team | 10 pe loc |
| Free, Lite, Student, BYOK | 1 |

În cotă piesa e gratuită pentru tine (`quota.within: true`). Peste cotă fiecare pas primește o ofertă de preț, o rezervare din portofel și se decontează la costul real — `402 insufficient_funds` când portofelul nu ajunge. `budget_micro_usd` plafonează o piesă în ambele cazuri; `spent_micro_usd` arată cât a costat până acum. Pașii agenților sunt taxați pe tokeni sub modelul public `codai` (model de utilizare `codai::music-<rol>`, cache de prompt activ). Vezi ce a rămas cu `GET /v1/studio/music-room/quota`.

## Erori [#erori]

| Stare | Cod | Când |
| --- | --- | --- |
| `400` | `invalid_request` | Corpul cererii nu respectă schema |
| `402` | `insufficient_funds` | Peste cotă, iar portofelul nu acoperă pasul următor |
| `404` | `not_found` | Id necunoscut sau piesa altui cont |
| `409` | `not_at_gate` | `choose` sau `direct` cât timp piesa nu așteaptă la acea poartă |
| `429` | `too_many_music_rooms` | Ai deja două piese care rulează |
| `503` | `media_ops_unavailable` | Motorul de randare muzicală nu e configurat pe acest gateway |

## Mențiuni [#mențiuni]

`credits` conține rândurile de publicat împreună cu piesa: bibliotecile de eșantioane CC-BY folosite de instrumentiști și „Built with Llama” când a rulat un asistent simbolic. Fiecare rezultat poartă marcajul AI, ca restul codai Studio.

## SDK-uri [#sdk-uri]

```ts
const room = await codai.studio.musicRoom.create(
  { brief: 'o melodie veselă de nuntă despre doi prieteni vechi', language: 'ro', genre: 'hora' },
  { idempotencyKey: 'song-42' },
);
let r = await codai.studio.musicRoom.wait(room.id, { untilGate: true });
if (r.gate?.kind === 'plan') r = await codai.studio.musicRoom.choose(r.id, { gate: 'plan', variant: 0 });
await codai.studio.musicRoom.direct(r.id, { role: 'drums', direction: 'mai puține breakuri' });
const { remaining } = await codai.studio.musicRoom.quota();
```

```python
room = client.studio.music_room.create("o melodie veselă de nuntă despre doi prieteni vechi", language="ro", genre="hora")
r = client.studio.music_room.wait(room["id"], until_gate=True)
if r["gate"] and r["gate"]["kind"] == "plan":
    r = client.studio.music_room.choose(r["id"], "plan", variant=0)
print(client.studio.music_room.quota()["remaining"])
```

TypeScript: `studio.musicRoom.create / get / list / choose / direct / quota / wait` (`wait(id, { untilGate, intervalMs, timeoutMs, signal })`). Python: `studio.music_room.create / get / list / choose / direct / quota / wait` (`wait(id, until_gate=, interval=, timeout=)`).

## Unelte pentru agenți [#unelte-pentru-agenți]

Agenții codai de pe desktop, telefon și VS Code și [setul de unelte MCP Studio](./clients.mdx) folosesc același flux prin patru unelte: `music_room_create` (pornește o piesă; `auto` doar când ai cerut să fie făcută direct), `music_room_status` (o citește și o avansează), `music_room_choose` (răspunde la o poartă cu decizia ta) și `music_room_direct` (vorbește cu un instrumentist).