Automotion docs
API

Renders

Create renders from raw movie documents and track them to completion. Poll `GET /renders/{id}` or receive a signed [webhook](/docs/api/webhooks) when the render finishes.

Create renders from raw movie documents and track them to completion. Poll GET /renders/{id} or receive a signed webhook when the render finishes.

All endpoints live under https://api.automotion.dev/v1, require Authorization: Bearer <api key>, and answer with the standard envelopes.

POST /renders

Create a render. Validate a raw movie document, apply credit/idempotency/webhook gating, and enqueue it for rendering. Poll the returned render or supply webhook_url (paid plans) to be notified.

Parameters

NameInTypeRequiredDescription
Idempotency-Keyheaderstring (non-empty, ≤ 255 chars)noOptional client-chosen key making the create retry-safe (§9): replaying the same key with the same body returns the ORIGINAL render with 200; a different body is rejected with IDEMPOTENCY_KEY_REUSED.

Request body

The movie document to render, optionally with variable values and webhook_url.

FieldTypeDefaultDescription
movie *object—The movie document to render. The preset input form ({ preset, resolution? } instead of width/height) is also accepted.
variablesobject—Values for the declared variables, keyed by variable name.
webhook_urlstring (uri)—Webhook notified on render.completed / render.failed. Paid plans only; trial requests are rejected with WEBHOOKS_NOT_ALLOWED.

Example

curl -X POST https://api.automotion.dev/v1/renders \
  -H "Authorization: Bearer $AUTOMOTION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "movie": {
      "schema": "v1",
      "preset": "9:16",
      "scenes": [
        {
          "id": "hello",
          "duration": 3,
          "background": "#0f172a",
          "elements": [
            {
              "id": "hello-text",
              "type": "text",
              "text": "Hello, Automotion!"
            }
          ]
        }
      ]
    }
  }'

Responses

  • 201 — The queued render. Returns RenderResource.
  • 200 — Idempotent replay: the same Idempotency-Key with the same body returns the original render. Returns RenderResource.

RenderResource

FieldTypeDefaultDescription
id *string (non-empty)—Render id.
status *"queued" | "preparing" | "rendering" | "done" | "failed"—Render lifecycle state (§6): queued → preparing → rendering → done | failed.
progress *integer (0–100)—Monotonic progress percent: 0–20 preparing, 20–99 rendering, 100 done.
draft *boolean—Whether this is a fast low-res draft render.
watermark *boolean—Whether the output carries the Automotion watermark (drafts and the trial plan).
outputUrl *string (uri) | null—CDN URL of the finished MP4. Null until the render is done.
expiresAt *string (date-time) | null—When the output expires per the plan's retention window (30d trial / 90d Starter+Pro / 365d Studio). Set on completion.
error *object | null—The failure, when status is failed. Always references a catalog code. Null otherwise.
durationSec *number (≥ 0) | null—Output duration in seconds, known once preparation finishes.
meteredMinutes *number (≥ 0) | null—Weighted render minutes charged against the credit balance (10 credits each), set when the render completes.
fps *integer (> 0)—Frames per second of the output.
templateId *string (non-empty) | null—Source template id when the render was created from a template.
webhookUrl *string (uri) | null—Webhook target notified on completion or failure (paid plans).
createdAt *string (date-time)—Creation time (ISO-8601).
updatedAt *string (date-time)—Last state-change time (ISO-8601).

Errors

VALIDATION_ERROR · SCHEMA_INVALID · UNSUPPORTED_SCHEMA_VERSION · ELEMENT_ID_DUPLICATE · SCENE_ID_DUPLICATE · SCENE_EMPTY · VARIABLE_MISSING · VARIABLE_TYPE_MISMATCH · VARIABLE_UNDECLARED · INSUFFICIENT_CREDITS · CONCURRENCY_LIMIT · IDEMPOTENCY_KEY_REUSED · WEBHOOKS_NOT_ALLOWED — plus the pipeline-wide UNAUTHORIZED · RATE_LIMITED · INTERNAL.

GET /renders

List renders. List the caller's renders, newest first, with status/date filtering and page pagination.

Parameters

NameInTypeRequiredDescription
statusquery"queued" | "preparing" | "rendering" | "done" | "failed"noOnly return renders in this lifecycle state.
created_afterquerystring (date-time)noOnly return renders created at or after this ISO-8601 instant.
created_beforequerystring (date-time)noOnly return renders created before this ISO-8601 instant.
pagequeryinteger (≥ 1)no1-based page number.
page_sizequeryinteger (1–100)noPage size (max 100).

Example

curl https://api.automotion.dev/v1/renders \
  -H "Authorization: Bearer $AUTOMOTION_API_KEY"

Responses

  • 200 — A page of renders. Returns RenderListResource.

RenderListResource

FieldTypeDefaultDescription
items *object[]—The page of results, newest first.
page *integer (≥ 1)—1-based page number.
pageSize *integer (≥ 1)—Number of items per page.
total *integer (≥ 0)—Total number of matching items.
hasMore *boolean—Whether further pages exist (page * pageSize < total).

Errors

VALIDATION_ERROR — plus the pipeline-wide UNAUTHORIZED · RATE_LIMITED · INTERNAL.

GET /renders/{id}

Get a render. Fetch a render's status, progress, output URL, retention deadline and error detail. The always-available polling fallback.

Parameters

NameInTypeRequiredDescription
idpathstring (non-empty)yesThe render id.

Example

curl https://api.automotion.dev/v1/renders/$RENDER_ID \
  -H "Authorization: Bearer $AUTOMOTION_API_KEY"

Responses

  • 200 — The render. Returns RenderResource.

RenderResource

FieldTypeDefaultDescription
id *string (non-empty)—Render id.
status *"queued" | "preparing" | "rendering" | "done" | "failed"—Render lifecycle state (§6): queued → preparing → rendering → done | failed.
progress *integer (0–100)—Monotonic progress percent: 0–20 preparing, 20–99 rendering, 100 done.
draft *boolean—Whether this is a fast low-res draft render.
watermark *boolean—Whether the output carries the Automotion watermark (drafts and the trial plan).
outputUrl *string (uri) | null—CDN URL of the finished MP4. Null until the render is done.
expiresAt *string (date-time) | null—When the output expires per the plan's retention window (30d trial / 90d Starter+Pro / 365d Studio). Set on completion.
error *object | null—The failure, when status is failed. Always references a catalog code. Null otherwise.
durationSec *number (≥ 0) | null—Output duration in seconds, known once preparation finishes.
meteredMinutes *number (≥ 0) | null—Weighted render minutes charged against the credit balance (10 credits each), set when the render completes.
fps *integer (> 0)—Frames per second of the output.
templateId *string (non-empty) | null—Source template id when the render was created from a template.
webhookUrl *string (uri) | null—Webhook target notified on completion or failure (paid plans).
createdAt *string (date-time)—Creation time (ISO-8601).
updatedAt *string (date-time)—Last state-change time (ISO-8601).

Errors

NOT_FOUND — plus the pipeline-wide UNAUTHORIZED · RATE_LIMITED · INTERNAL.

Previous

API overview

Next

Templates

On this page