Creații audio

O creație audio (kind: "audio") este o creație al cărei document este o cronologie audio multipistă: o melodie sau un episod de podcast. Folosește același API ca orice altă creație — creare, citire, editare prin operații, versiuni, revenire, ramificare, verificare, partajare — și același document, cu cronologia în doc.audio. Crearea, citirea și editarea sunt gratuite; fișierele pe care le pui pe ea vin din operațiile media, din generarea de muzică și voce sau din propriile încărcări.

curl https://ai.codai.ro/v1/studio/creatives \
  -H "Authorization: Bearer $CODAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "kind": "audio", "title": "Episodul 12" }'

Modelul documentuluiCopiază linkul secțiunii

Un document audio are un singur format, stereo (mixaj la 48 kHz; pânza de 1920×1080 se folosește doar pentru o scenă opțională de copertă / vizualizare), cel mult o scenă (doar subtitrări) și un fps opțional. Tot ce contează stă în doc.audio (schema CreativeAudio):

Milisecundele sunt sursa de adevăr; măsurile și timpii se deduc din meta.bpm și meta.timeSignature.

Piste. role este unul dintre voice, music, sfx, drums, bass, keys, guitar, vocal, lead, pad, fx, bus, podcast_host, podcast_guest. kind este audio (implicit), midi (conține doar midiClips) sau bus (fără clipuri; celelalte piste ajung la ea prin sends). fx este un lanț de cel mult 16 efecte (eq, compressor, reverb, delay, limiter, gate, deesser, pitch, chorus, saturation) cu params numerici și bypass; anvelopele din automation țintesc gainDb, pan sau fx.<fxId>.<param>.

Clipuri. { id, assetId, startMs, inMs?, outMs?, gainDb?, pan?, fadeInMs?, fadeOutMs?, fadeCurve?, stretch?, pitchSemitones?, loop?, duck?, color?, generation?, locked? }. inMs / outMs sunt decalaje în asset-ul sursă: un clip se termină pe cronologie la startMs + (outMs − inMs) × stretch. fadeCurve este linear, exp sau s; stretch (0,25–4) păstrează tonalitatea; generation reține cum a fost generat un clip (furnizorul și modelul public codai, promptul, seed-ul, clipul părinte, operația).

Atenuare automată. Pistele de muzică ale unei creații audio își coboară automat volumul sub clipurile voice, vocal, podcast_host și podcast_guest (atac 150 ms, eliberare 400 ms, 12 dB); orice clip poate activa sau dezactiva asta prin duck.

Editarea prin operațiiCopiază linkul secțiunii

Creațiile audio acceptă toate operațiile comune (setMeta, setAsset, setAudioClip, removeAudioClip, setLocale…) plus 16 operații audio, trimise la POST /v1/studio/creatives/{id}/ops ca orice altă editare:

setMeta acceptă și audio (un patch al lui meta), iar setAudioClip un trackId. În orice patch, null șterge un câmp opțional, așa că fiecare editare are un invers exact și poate fi anulată.

{
  "base_seq": 4,
  "ops": [
    { "op": "addSection", "section": { "id": "chorus1", "kind": "chorus", "startMs": 32000, "durationMs": 16000 } },
    { "op": "setFades", "clipId": "c7", "fadeInMs": 500, "fadeCurve": "s" },
    { "op": "setMaster", "master": { "targetLufs": -14, "truePeakDb": -1, "limiter": true } }
  ]
}

Ținte de masteringCopiază linkul secțiunii

meta.loudnessTarget primește un preset sau un număr de LUFS integrați (−40…−5):

master.targetLufs are prioritate față de preset; vârful real implicit este −1 dBTP. Pentru masteringul unui fișier de mixaj rulează audio.master cu target_lufs −14, −16 sau −23.

VerificareCopiază linkul secțiunii

Verificarea adaugă cinci reguli audio: clipping_risk (câștigul însumat al clipurilor peste 0 dB), missing_lyrics (o strofă / pre-refren / refren / punte fără versuri când melodia are o pistă vocală), missing_loudness_target, audio_overlap (clipuri suprapuse pe aceeași pistă) și audio_out_of_range (un clip sau o notă în afara sursei ori a cronologiei).

Operații media pentru audioCopiază linkul secțiunii

Piesele de bază ale unei melodii sau ale unui episod vin din operațiile media: music.generate_ace, music.repaint, music.extend și music.cover pentru melodii, sfx.generate pentru efecte, audio.separate_stems ca să împarți un mix în piste de voce / tobe / bas / restul, audio.denoise ca să cureți o voce, audio.to_midi ca să transformi o melodie într-un clip MIDI, audio.analyze ca să citești BPM-ul, tonalitatea și loudness-ul în meta, și audio.master pentru loudness-ul final. Fiecare rezultat este un asset nou pe care îl pui pe o pistă cu setAudioClip; proveniența lui (parent_asset_id, op) rămâne pe asset.

Randare și exporturiCopiază linkul secțiunii

POST /v1/studio/creatives/{id}/render pe o creație audio randează mixajul: fiecare pistă, clip, notă MIDI, efect, send și automatizare se mixează cu ffmpeg, se masterizează la ținta de loudness (loudnorm în două treceri + limitator de vârf real) și se exportă. Răspunsul e 202 cu id-ul randării; interoghezi GET /v1/studio/renders/{id} ca la orice randare.

curl https://ai.codai.ro/v1/studio/creatives/$ID/render \
  -H "Authorization: Bearer $CODAI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: mix-12" \
  -d '{ "formats": ["wav", "mp3"], "stems": true, "loudness": "podcast" }'

Răspunsul 202 listează ieșirile planificate (outputs: kind mix / stem / lrc, format, track_id), target_lufs și true_peak_db rezolvate, duration_seconds și quote_micro_usd. După succeeded, data[] conține câte un asset pe ieșire (url semnat valabil o oră, output, format, track_id), iar qa valorile măsurate lufs, true_peak_db și clipping. Fiecare fișier poartă marcajul IA în interior (WAV RIFF ICMT, MP3 ID3v2.4, FLAC comentariu Vorbis), iar proveniența lui indică randarea.

Preț: 0,001 USD pe secundă de ieșire (0,06 USD pe minut), minimum 0,01 USD; stems: true adaugă 50 %. Oferta se rezervă în portofel înainte de pornire (402 insufficient_funds dacă nu ajunge), iar durata măsurată se facturează o singură dată. Cel mult 20 de minute pe randare (400 too_long); un document fără nimic audibil dă 400 empty_audio; fiecare asset referit trebuie să fie al tău și gata (400 asset_not_found).

Versurile melodiei vin din scriitorul de versuri, iar sincronizarea karaoke din alinierea versurilor.

SDK-uriCopiază linkul secțiunii

TypeScript: creatives.create({ kind: 'audio' }), creatives.edit(id, { baseSeq, ops }) (tipurile CreativeAudio, CreativeOp), creatives.renderAudio(id, { formats, stems, lrc, loudness }) (tipurile CreativeAudioRenderRequest, CreativeAudioRenderAccepted, StudioAudioRender), plus mediaOps și lyrics. Python: client.creatives.create(...), client.creatives.edit(...), client.creatives.render_audio(id, formats=, stems=, lrc=, loudness=), client.media_ops și client.lyrics.