renders

Submit a render job

Enqueue a new render job on the GPU engine. The job moves through queued → processing → completed / failed asynchronously. Attach a webhook URL or register workspace-level webhooks to receive status updates. The response carries an ADVISORY ok + violations[] lint of the composition: the render is dispatched either way, and anything that actually blocks a submit is a 422 instead.

post/v1/renders

Request

  • Base URL: https://api.framelane.io
  • URL: https://api.framelane.io/v1/renders
  • Auth: HTTP bearer

Headers

Idempotency-Keystring nullable

Request body

version'v4' | 'v5' nullable

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.

schema_version'v5' nullable

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

widthinteger nullable

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

heightinteger nullable

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

durationnumber nullable

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

frame_rateinteger nullable

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

output_format'mp4' | 'webm' | 'mov' | 'gif' | 'png' | 'jpg'

Values:

  • mp4 — H.264 MP4 video — the default, widely compatible delivery format.
  • webm — VP9 WebM video — supports a transparent (alpha) background.
  • mov — QuickTime MOV — ProRes 4444 with a transparent (alpha) background; large files.
  • gif — Animated GIF — roadmap; not yet emitted by the renderer.
  • png — Single-frame PNG still — roadmap; not yet emitted by the renderer.
  • jpg — Single-frame JPEG still — roadmap; not yet emitted by the renderer.
output_filenamestring nullable

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

background_colorstring

RGBA background color in hex format (#RRGGBBAA).

background_image_urlstring uri nullable

URL of an image to use as the composition background.

alphaboolean

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

watermark_urlstring uri nullable

Watermark image overlaid on the output (§6).

metadataobject

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

webhook_urlstring uri nullable

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

ingest_externalboolean nullable

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.

Response

Idempotent replay — same Idempotency-Key reused.

idstring required

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

kind'render' | 'task' required
is_previewboolean

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

editor_urlstring nullable

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

task_type'transcribe'

The AI task types the API offers.

Values:

  • transcribe — Speech-to-text transcription (via AssemblyAI) with optional analysis. Returns the transcript inline on the task's result object — there is no file artifact, so output is null and /v1/tasks/{id}/download returns 404.
workspace_idstring required

ID of the workspace that owns this job.

status'ingesting' | 'queued' | 'processing' | 'completed' | 'failed' | 'cancelled' required

Values:

  • ingesting — External source files are being probed for duration before the render is queued.
  • queued — Accepted and waiting for a worker to pick it up.
  • processing — Actively rendering or processing.
  • completed — Finished successfully; the output artifact is available.
  • failed — Terminated with an error (see error).
  • cancelled — Cancelled by the caller before completion.
progress_percentinteger

0–100 progress indicator updated by the render engine.

progress_stage'downloading' | 'compositing' | 'encoding' | 'uploading'

Values:

  • downloading — Fetching source media.
  • compositing — Compositing the scene on the GPU.
  • encoding — Encoding the output video.
  • uploading — Uploading the finished artifact to storage.
resultobject nullable

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.

metadataobject

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

created_atstring date-time required

ISO-8601 UTC timestamp when the job was created.

updated_atstring date-time required

ISO-8601 UTC timestamp of the last status change.

completed_atstring date-time nullable

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

okboolean 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 response

{
  "id": "render_01J8QR2K5VKDGN2T4FBM3CZYX7",
  "workspace_id": "ws_01J8QR2K5VKDGN2T4FBM3CZYX8",
  "output": {
    "url": "https://cdn-user.framelane.io/render_01J.../output.mp4",
    "width": 1920,
    "height": 1080,
    "duration": 15.3,
    "size_bytes": 12582912
  },
  "result": {
    "language_code": "en",
    "text": "Welcome back to the show."
  },
  "error": {
    "message": "Source URL returned 404."
  },
  "metadata": {
    "project_id": "proj_123",
    "user_ref": "usr_abc"
  },
  "ok": true
}

Changes

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