Skip to main content
POST
Submit a render job

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

​
Idempotency-Key
string | null

Body

application/json

Body for POST /v1/renders.

Defines the composition to render: dimensions, output format, timeline elements, and optional transitions. The render engine produces a single video artifact.

​
width
integer | null

Output width in pixels. Must be set together with height or both omitted.

Required range: 16 <= x <= 8192
Example:

1920

​
height
integer | null

Output height in pixels. Must be set together with width or both omitted.

Required range: 16 <= x <= 8192
Example:

1080

​
duration
number | null

Total composition duration in seconds. Inferred from elements when omitted.

Required range: x > 0
Example:

15

​
frame_rate
integer | null

Frames per second. When set, the output encodes at exactly this rate. Defaults to 30 when omitted.

Required range: 1 <= x <= 240
Example:

30

​
output_format
enum<string>
default:mp4

Container and codec for the output file.

Available options:
mp4,
webm,
mov,
gif,
png,
jpg
Example:

"mp4"

​
output_filename
string | null

Custom filename for the artifact (without extension). Auto-generated when omitted.

Example:

"my-render"

​
background_color
string
default:#000000ff

RGBA background color in hex format (#RRGGBBAA).

Pattern: ^#([0-9a-fA-F]{6}|[0-9a-fA-F]{8})$
Example:

"#000000ff"

​
background_image_url
string<uri> | null

URL of an image to use as the composition background.

Required string length: 1 - 2083
Example:

"https://cdn.example.com/bg.jpg"

​
alpha
boolean
default:false

When true, produce an alpha-channel (transparent background) output. Requires output_format=webm or output_format=mov.

Example:

false

​
elements
(VideoElement · object | AudioElement · object | TextElement · object | ImageElement · object | ShapeElement · object)[]

Ordered list of timeline elements (video, image, text, audio, etc.).

​
transitions
Transition · object[]

Transition effects applied between consecutive elements.

​
groups
Group · object[]

Transform groups over member elements (compose member→group→parent; optional stack layout). §5.

​
motion_blur
MotionBlur · object | null

Shutter-based motion blur over the whole composition (§5c). Graphics motion smears; video holds its decoded frame within the shutter (as in AE). Opt-in and costly: accumulation is CPU-side, so the render falls back to software encoding — expect roughly samples× render time.

​
background_gradient

Canvas-sized gradient fill behind every layer (§6). Rendered for the full output slice. Accepts a Gradient object or a CSS linear-gradient(...) string.

Pattern: ^\s*(?:linear|radial)-gradient\s*\(
Example:

"linear-gradient(90deg, #ff0000 0%, #0000ff 100%)"

​
watermark_url
string<uri> | null

Watermark image overlaid on the output (§6).

Required string length: 1 - 2083
​
custom_animations
CustomAnimationRegistry · object | null

Inline custom-animation definitions (§3), registered with the engine before any element is built. Reference an element entry by name via motion[].custom on any video/image/shape element or group; reference a text entry via a text element's animation_preset or motion[].custom. The catalog stops being a ceiling — anything expressible as keyframes is expressible in the request.

​
metadata
Metadata · object

Arbitrary key-value pairs echoed back in all webhook payloads.

Example:
​
webhook_url
string<uri> | null

Per-request webhook URL. Overrides workspace-level webhooks for this job only. Receives render.completed, render.failed, and progress events.

Required string length: 1 - 2083
Example:

"https://app.example.com/hooks/framelane"

​
ingest_external
boolean | null

Controls handling of source URLs that are not already hosted by Framelane. When true, such public files are copied into Framelane storage before rendering: the job starts in the ingesting state and moves to queued once the copy completes (you receive an asset.ready webhook per file). When false, the URL is passed straight to the renderer (the legacy behavior; video/audio still require an explicit out_point). Defaults to the workspace setting when omitted.

Example:

true

Response

Idempotent replay — same Idempotency-Key reused.

A freshly submitted render: the job row plus the advisory lint of its composition.

Returned only by the two submit routes (POST /v1/renders, POST /v1/projects/{id}/renders). A subclass rather than two more fields on :class:JobOut, because JobOut is the shape of a job row on every read route (GET /v1/renders, all /v1/tasks routes, the MCP read tools) where a lint result does not exist and would be permanently null.

​
id
string
required

Unique job ID. Prefix indicates type: render_ or task_.

Example:

"render_01J8QR2K5VKDGN2T4FBM3CZYX7"

​
kind
enum<string>
required

Whether this is a render or a task.

Available options:
render,
task
Example:

"render"

​
workspace_id
string
required

ID of the workspace that owns this job.

Example:

"ws_01J8QR2K5VKDGN2T4FBM3CZYX8"

​
status
enum<string>
required

Current lifecycle state: queued → processing → completed / failed / cancelled.

Available options:
ingesting,
queued,
processing,
completed,
failed,
cancelled
Example:

"queued"

​
created_at
string<date-time>
required

ISO-8601 UTC timestamp when the job was created.

​
updated_at
string<date-time>
required

ISO-8601 UTC timestamp of the last status change.

​
ok
boolean
required

Advisory — the render was still accepted and dispatched. False means the composition has error-severity findings that will likely make the output wrong (a self-transition, a fully off-canvas element); it does NOT mean the submission was refused. Everything that actually blocks a render is a 422 before you ever see this field.

Example:

true

​
is_preview
boolean
default:false

True for a cheap preview render. Previews are not billed and are excluded from the renders list.

Example:

false

​
task_type
enum<string> | null

For task jobs only — the specific AI operation.

Available options:
transcribe
Example:

"transcribe"

​
progress_percent
integer
default:0

0–100 progress indicator updated by the render engine.

Required range: 0 <= x <= 100
Example:

0

​
progress_stage
enum<string> | null

Current processing phase within a job.

Available options:
downloading,
compositing,
encoding,
uploading
Example:

"compositing"

​
output
JobOutput · object | null

Populated once status == completed. Contains the signed artifact URL.

​
result
Result · object | null

Structured JSON result for tasks that return data rather than a file — transcribe returns the transcript here (text, words, utterances, and any requested analysis). Populated once status == completed; null for renders and for any job whose only artifact is the file at output.url.

Example:
​
error
JobError · object | null

Populated when status == failed. Contains a structured error code.

​
metadata
Metadata · object

Caller-supplied key-value pairs echoed back on every webhook and response.

Example:
​
completed_at
string<date-time> | null

ISO-8601 UTC timestamp when the job reached a terminal state.

​
violations
Violation · object[]

Advisory — the render was still accepted and dispatched. Cross-element and layout findings from the same linter the preview dry-run runs, attached so you can see problems on the render you just paid for instead of only in the artifact. To catch these BEFORE spending a render, call POST /v1/preview with dry_run.Truncated to the first 40 findings (errors first) on very large compositions, with a VIOLATIONS_TRUNCATED marker carrying the full count; the free dry run is never truncated.