renders

Render a scoped motion preview of the composition

A cheap, watchable MP4 of ONLY [fromSec, toSec) of the composition at preview quality (capped resolution, lighter encode). The way to judge motion — a cut, a transition, a component's animation — with real fidelity BEFORE paying for a full render. Async: returns a render job; wait_job(kind='render') or webhook render.completed for the URL. Meters the capture feature, never an exports credit.

post/v1/projects/{id}/preview-clip

Request

  • Base URL: https://api.cueframe.ai
  • URL: https://api.cueframe.ai/v1/projects/{id}/preview-clip
  • Auth: one of:
    • HTTP bearer
    • OAuth 2 (authorization code, authorization URL https://api.cueframe.ai/api/auth/mcp/authorize, token URL https://api.cueframe.ai/api/auth/mcp/token, scopes: renders:write)
    • API key in header PAYMENT-SIGNATURE

Path parameters

idstring required

Request body

fromSecnumber required

Window start, seconds into the composition.

toSecnumber required

Window end (exclusive), seconds.

compositionIdstring

Target a specific composition; defaults to the project's active composition.

Response

Preview render queued.

idstring required
status'queued' | 'pending' | 'rendering' | 'complete' | 'error' | 'cancelled' required
outputUrlstring nullable required
outputExpiresAtstring nullable required
errorstring nullable required

Human-readable failure message. Pair with errorCode for a stable, machine-readable code an agent runner can branch on.

errorCodestring nullable required

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.

errorDetailsobject nullable required

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.

category'authoring' | 'transient' | 'internal' nullable required

authoring = deterministic defect in YOUR composition/request — fix it, retrying is futile; transient = temporary pipeline/infra failure — safe to retry; internal = unexpected server fault — retry once then escalate.

retryableboolean nullable required

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.

createdAtstring required
updatedAtstring required

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.

compositionIdstring nullable required

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.

engine'hyperframes' | 'remotion' nullable required

The render engine the row was minted for. Null on rows minted before the engine was recorded.

completedAtstring nullable required

ISO-8601 instant the render reached its terminal status (complete, error or cancelled); null while it runs. Pair with createdAt for the wall time.

outputDurationSecnumber nullable required

The output's length in seconds (the composition timeline's, or the preview window's), as billed. Null on legacy rows.

listUsdnumber

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.

warningsstring[]

Non-fatal advisories surfaced at render-CREATE (omitted when none, and on GET — create-time only).

Changes

No recorded changes to this operation across all 1 revision of this API.