Batches

A batch turns a table into creatives: each row of a CSV file (or of a sheet creative) fills the variables of a template or of a creative and becomes a new creative of its own. Rows can be translated into their own language and rendered to MP4. Batches run in the background; you follow them by polling.

Creating a batch is free. Translations and renders made for the rows are billed exactly like the same calls made by hand (see Billing).

Sources and dataCopy Anchor Link

The source is exactly one of { "template_id": "<id>" } (a template with at least one variable) or { "creative_id": "<id>", "seq"?: <version> } (a creative with at least one unlocked variable; default the head). Otherwise the answer is 400 no_vars.

The data is exactly one of:

• csv — CSV text with a header row, up to 2 MB. The parser follows RFC 4180: quoted fields, "" inside quotes, line breaks inside quoted cells, CRLF / LF / CR line endings; a UTF-8 BOM is removed. The delimiter is detected from the header (,, ; or tab — a spreadsheet exported with a Romanian locale usually uses ;) or forced with delimiter. Header cells are trimmed, short rows are padded with empty cells and empty trailing rows are dropped.
• sheet — { "creative_id": "<sheet creative>", "node_id"?: "<grid id>" }: the first (or given) grid or table of a sheet, doc or deck creative. The header is the column headers when every column has one, otherwise the first row; dates become ISO dates, booleans true / false, numbers plain text and formula cells are left empty.

Limits. At most 500 data rows and 50 columns. CSV errors answer 400 with the code: empty, ragged (a row longer than the header, with its index), unterminated_quote, too_many_columns, too_many_rows.

Mapping columnsCopy Anchor Link

Each column maps to a variable, to a reserved column or to nothing. Without a mapping the columns are matched automatically: diacritics are removed, letters lowercased and every other character run becomes _, then the column name is compared with each variable key and label (Titlu principal matches the variable titlu_principal).

mapping overrides the automatic match per column: { "Headline EN": "headline", "Notes": null, "Lang": "locale" } (null ignores the column). A target that is neither a variable nor a reserved column answers 400 invalid_mapping.

Cell values. An empty cell keeps the variable's default. Numbers accept 1.5, 1,5 and 1 234,5; booleans true / false, yes / no, da / nu, 1 / 0 and x; colours #rgb, #rrggbb and #rrggbbaa; texts up to 5000 characters.

Image cells. An image variable takes one of:

• an asset id of one of your ready images;
• an asset name — the newest of your ready images whose name or file name matches (case-insensitive);
• an https URL — imported into your Studio library when the row runs (public addresses only, every redirect re-checked; PNG, JPEG, WebP or GIF up to 10 MB). The same URL is imported once per batch.

Dry runCopy Anchor Link

Send "dry_run": true to check everything without storing anything (free):

curl https://ai.codai.ro/v1/studio/batches \
  -H "Authorization: Bearer $CODAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "source": { "template_id": "<template id>" }, "csv": "headline,photo,locale\nAutumn sale,https://example.com/a.jpg,en\nReduceri de toamnă,poza-1,ro\n", "dry_run": true }'

{
  "dry_run": true,
  "columns": [{ "name": "headline", "index": 0, "maps_to": "headline", "kind": "var" }],
  "unmapped_vars": [],
  "rows": 2,
  "valid": 2,
  "errors": [],
  "preview": [{ "row": 0, "title": "Promo 9:16", "locale": "en", "format": null, "vars": { "headline": "Autumn sale" } }],
  "estimate": { "renders": 0, "localized_rows": 2 }
}

errors lists up to 100 problems as { "row", "column", "message" } (an invalid number, an unknown image, a bad language, a format the source does not have); preview shows the first three valid rows; estimate counts the renders and translations the batch would bill. Fix the mapping and try again until it looks right.

Create and follow a batchCopy Anchor Link

The same body without dry_run creates the batch and answers 201 { "batch": { … } }. Invalid rows are stored as failed with their error and the rest run; when every row is invalid the answer is 400 invalid_rows with the errors.

Each row goes through pending → created → (localized) → (rendering) → done, or ends as failed or skipped. GET /v1/studio/batches/{id} advances the batch a little on every poll and answers { "batch": { "id", "title", "status", "source", "total", "done", "failed", "pending", "skipped", "options", "columns", "cost_micro_usd", "zip", "created_at", "updated_at", "finished_at" } }; with rows=1 it adds rows (offset, limit up to 100, optional status filter), each { "idx", "status", "creative_id", "render_id", "render_url", "locale", "title", "error", "cost_micro_usd" } (render_url is a signed link once the render is ready). columns is { "header", "columns", "unmapped_vars" }: the CSV header, the same column mapping as the dry run and the variables no column fills. cost_micro_usd is a decimal string (USD micros). The batch status is queued, running, completed, failed or cancelled. A batch that is not yours answers 404 Batch not found..

Cancel and retry. POST …/cancel marks the rows not started yet as skipped and the batch cancelled (409 not_cancellable once it is finished). POST …/retry puts the failed rows back in the queue — each row is tried at most 3 times (409 nothing_to_retry when no row can be retried). Both answer with the batch.

LanguagesCopy Anchor Link

With a locale column, each row's creative is first translated into that language with the model (the same translation as Localisation, with the batch's localize.tone and localize.glossary) and then becomes a creative in that language, ready to render. Leave the cell empty to keep the source language.

Export, ZIP and limitsCopy Anchor Link

GET …/export.csv downloads the original columns plus creative_id, status, error and render_url for every row (text/csv; charset=utf-8, <title>-status.csv). Cells starting with =, +, -, @, a tab or a carriage return get a leading ', so a spreadsheet never runs them as formulas. Free.

POST …/zip builds a ZIP of every finished render (<idx>-<title>.mp4, at most 500 files) in the background and answers 202 with the batch (zip.status: "building"); poll the batch until zip.status is ready and download zip.url (signed for 1 hour) — or failed with zip.error. No finished render answers 409 no_renders. Free.

BillingCopy Anchor Link

• Creating, validating, polling, cancelling, retrying, exporting and building the ZIP are free.
• Each row with a language is translated and billed like POST …/localize (usage rows codai::localize).
• Each row render is billed like any render of the same quality, when it has succeeded.
• cost_micro_usd sums what the batch and each row cost so far.

SDKs and agent toolsCopy Anchor Link

const check = await codai.batches.dryRun({ source: { template_id: tpl.id }, csv });
if (check.valid === check.rows) {
  const { batch } = await codai.batches.create({ source: { template_id: tpl.id }, csv, render: true });
  await codai.batches.wait(batch.id); // polls every 3 s, up to 10 min
  const statusCsv = await codai.batches.exportCsv(batch.id);
  await codai.batches.zip(batch.id);
}

check = client.batches.dry_run(source={"template_id": tpl["id"]}, csv=csv_text)
batch = client.batches.create(source={"template_id": tpl["id"]}, csv=csv_text, render=True)["batch"]
client.batches.wait(batch["id"])  # polls every 3 s, up to 10 min
status_csv = client.batches.export_csv(batch["id"])

Agents on desktop, phone and VS Code use creative_batch (template_id or creative_id, csv or sheet_creative_id, mapping, render, quality, format, dry_run) and creative_batch_status (batch_id, rows).

Hub (internal)Copy Anchor Link

The hub calls the same routes under /internal/studio/batches… with a service token and a user_id; bodies and errors are identical.