Create Render
create_renderQueue an MP4 render of a project's composition (in a compose session, the session's scratch). Returns { id (renderId), status, warnings? } — warnings[] carries non-fatal advisories (omitted when none). The render themes from the project's brand kit (bind one via create_project / update_project with brandKitId — or PATCH /projects/:id over REST; without one the output is unbranded). Then call wait_job(kind="render", id=renderId, projectId=...) to block until the file is ready and get the download URL, or register a webhook (create_webhook on render.completed — status rides the payload).
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"projectId": "<projectId>",
"body": "<body>"
},
"name": "create_render"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| body | Yes | POST /projects/:id/renders body. | |
| commandId | No | Retry identity. A call repeated with the same commandId returns the first result instead of acting twice. | |
| projectId | Yes | projectId (path). |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| id | No | ||
| error | No | Human-readable failure message. Pair with `errorCode` for a stable, machine-readable code an agent runner can branch on. | |
| engine | No | The render engine the row was minted for. Null on rows minted before the engine was recorded. | |
| format | No | The resolved output format the render was encoded at (aspectRatio, fps, resolution): the frozen composition's, after any create-time scale override. Null on legacy rows. | |
| status | No | ||
| listUsd | No | A2 money stamp: the metered event's LIST price (USD), stamped at the success terminal (exports for deliverable renders, compose_capture for A8 previews). A plan allowance may zero the actual invoice line — this is the list price, never a Stripe charge. Absent while running, on failure, and for x402 orgs (on-chain receipts). Mirrors the get_usage ledger. | |
| preview | No | The scoped preview window when this is a preview_clip render; null for a full deliverable. | |
| category | No | Failure taxonomy when status is `error`; null otherwise. `authoring` = deterministic defect in YOUR composition/request — fix it, retrying is futile; `transient` = temporary pipeline/infra failure — safe to retry_render; `internal` = unexpected server fault — retry once then escalate. Mirrors the render.failed webhook's `category`. | |
| progress | No | Non-terminal render progress; phase is one of the worker's emitted stages. | |
| warnings | No | Non-fatal advisories surfaced at render-CREATE (omitted when none, and on GET — create-time only). | |
| createdAt | No | ||
| errorCode | No | Stable, machine-readable error code (e.g. `render_pipeline_unavailable`, `render_route_missing`, `render_pipeline_failed`). Null when status is not `error` or unavailable for an older render. | |
| outputUrl | No | ||
| retryable | No | Whether re-attempting the SAME render can succeed (status `error`); null otherwise. true → call retry_render. false → deterministic (category authoring/internal); fix the composition first — retry_render alone reproduces it. Mirrors the render.failed webhook's `retryable`. | |
| updatedAt | No | ISO-8601 timestamp of the render's most recent progress update. Compute staleness = now − updatedAt to distinguish a wedged render from a slow one and decide whether to wait, cancel, or retry. | |
| completedAt | No | ISO-8601 instant the render reached its terminal status (complete, error or cancelled); null while it runs. Pair with createdAt for the wall time. | |
| errorDetails | No | Structured failure context — `{ targetUrl?, upstreamStatus?, upstreamCode?, attemptedAt? }`. Surfaced so agent runners can distinguish operator-config issues from upstream-down vs route-missing without parsing `error`. | |
| compositionId | No | The composition this render froze at create time (the project's active one, or the compositionId the request named). Null on renders minted before this was recorded. | |
| outputExpiresAt | No | ||
| outputDurationSec | No | The output's length in seconds (the composition timeline's, or the preview window's), as billed. Null on legacy rows. |