Media operations

Media operations turn one Studio asset into new ones: cut out a subject, upscale a still, repaint a masked area, split a song into stems, clean up a voice, master a mix, convert a melody to MIDI or generate a song or a sound effect. Every op takes asset ids and strict per-op parameters, and every output is stored as a new asset in your library. The public model id is codai-studio-media.

{op} is the dotted op id, for example image.remove_background or audio.separate_stems.

The opsCopy Anchor Link

Image ops accept image, upload and frame assets (PNG, JPEG or WebP); audio ops accept music, speech, sfx and upload assets. For image.inpaint and image.erase the second asset is a black-and-white PNG mask of the first: white is edited, black is kept. The mask is sent to the model as a reference image, so edits follow it closely but not pixel-exactly (the catalogue entry carries a note saying so).

ParametersCopy Anchor Link

Parameters are validated strictly per op — an unknown key is a 400.

Running an opCopy Anchor Link

curl https://ai.codai.ro/v1/studio/media-ops/image.remove_background \
  -H "Authorization: Bearer $CODAI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: cutout-42" \
  -d '{ "asset_ids": ["3f2b8c1e-0000-4000-8000-000000000001"], "params": { "format": "png" } }'

A sync op answers 200:

{
  "object": "media_op.result",
  "op": "image.remove_background",
  "status": "ready",
  "outputs": [{ "asset_id": "…", "kind": "image", "mime_type": "image/png", "url": "https://…" }],
  "analysis": null,
  "cost_micro_usd": 2640
}

audio.analyze stores nothing and returns analysis: { duration_seconds, bpm, key, key_confidence, integrated_lufs, sample_peak_dbfs }.

Async jobsCopy Anchor Link

Stems, denoise, MIDI, mastering and every music or sound-effect op run as jobs. The run answers 202 with { "object": "media_op.job", "id", "status": "pending", … }. Poll GET /v1/studio/media-ops/jobs/{id} until status is ready (with outputs, one asset per stem for separation) or failed (with error: timeout, input_refused, dispatch_failed, store_failed or an engine message). A job that has not produced a result after 20 minutes fails with timeout. Reading a finished job stores its outputs and bills it once; the background sweeper does the same when nobody polls. At most 3 async jobs run per account at once — a fourth answers 429 with Retry-After.

PricingCopy Anchor Link

Every op has a quote — the price ceiling — that is held on your wallet before anything runs; when the wallet cannot cover it the answer is 402 insufficient_funds and nothing starts. After the op the measured cost is billed once and the rest of the hold is released; a failed op releases the whole hold.

• GPU / CPU ops (everything except the Gemini image edits) are priced by instance time on the codai Studio media service: $0.95 per hour, at least 5 seconds per op, estimated from the input length (for example audio.separate_stems ≈ 15 s + 0.5 s per input second). You pay the seconds the engine reports, never more than the quote.
• image.inpaint / erase / outpaint are billed like an image edit of the chosen model and image_size.

GET /v1/studio/media-ops lists a reference quote per op (default params, 60 s of audio or a 1024×1024 image) as quote_micro_usd and the wallet amount as quote_micro_eur; POST …/{op}/quote prices your real request with the same validation as the run.

ErrorsCopy Anchor Link

AI marking and lineageCopy Anchor Link

Every output is marked as AI-generated before it is stored: C2PA / XMP on images, RIFF INFO or ID3 tags on audio, plus the ai-generated object metadata. Each output also records where it came from — parent_asset_id (the first input), op and op_inputs (asset_ids + the validated params) — so you can always trace a stem, a master or a cut-out back to its source. Generate covers only from music you own or have the rights to.

SDKsCopy Anchor Link

const job = await codai.mediaOps.run('audio.separate_stems', { assetIds: [songId], params: { stems: 4 } });
const done = await codai.mediaOps.wait(job.id); // or mediaOps.runAndWait(...)

done = client.media_ops.run_and_wait("audio.master", [mix_id], {"target_lufs": -14})

TypeScript: mediaOps.list / quote / run / job / wait / runAndWait. Python: media_ops.list / quote / run / job / wait / run_and_wait. Songs and podcasts built from these outputs are edited as audio creatives and rendered to a mastered mix with creatives.renderAudio; lyrics come from the lyrics writer.