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.

​
version
enum<string> | null

Wire version of this request. Omit it: the render task is v5 exactly when the request carries a v5 block, and v4 otherwise. v5 accepts the v5 blocks (a shape's geometry, frame and instance elements, operations, components); v4 refuses them.

Available options:
v4,
v5
Example:

"v5"

​
schema_version
string | null

The document format an editor wrote this request in. Not sent to the renderer; version is the wire's.

Allowed value: "v5"
Example:

"v5"

​
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 | FrameElement · object | InstanceElement · 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), the alias of frames (§5). A request with frame or instance elements carries none.

​
design_size
DesignSize · object | null

The logical root in design px: frames and instances at the root are placed in this box, and the render scales it uniformly to width x height, whose aspect it must have. Canvas percent at the root is unchanged.

​
operations
OperationsBlock · object | null

Element properties driven over time (GVR §4.3): groups of operations, each counting from an anchor. Schema: blocks.operations in GET /v1/capabilities.

​
components
Component · object[]

Component definitions, which instance elements place. Schema of one: blocks.components in GET /v1/capabilities.

​
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 video/audio source URLs that are not hosted by Framelane. When true (the default), each such file is probed for its duration before rendering: the job starts in the ingesting state and moves to queued once the probe answers, so elements may omit out_point. The file itself is fetched by the renderer at render time, so the URL must be a direct, public https link to the media (not a share page) that supports range requests. When false, the URL is passed straight through and video/audio require an explicit out_point.

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

​
editor_url
string | null

Open the project this job was submitted from in the authenticated console. Absent for a job with no project.

​
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 36 findings (errors first) on very large compositions, with a VIOLATIONS_TRUNCATED marker carrying the full count; the free dry run is never truncated.