Skip to main content
POST
/
v1
/
renders
Submit a render job
curl --request POST \
  --url https://api.framelane.io/v1/renders \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "width": 1920,
  "height": 1080,
  "duration": 15,
  "frame_rate": 30,
  "output_format": "mp4",
  "output_filename": "my-render",
  "background_color": "#000000ff",
  "background_image_url": "https://cdn.example.com/bg.jpg",
  "alpha": false,
  "elements": [
    {
      "source_url": "https://cdn.example.com/clip.mp4",
      "lut_url": "<string>",
      "lut_intensity": 100,
      "brightness": 0,
      "contrast": 0,
      "saturation": 0,
      "exposure": 0,
      "sharpness": 0,
      "blur": 0,
      "noise": 0,
      "vignette": 0,
      "hue_rotate": 0,
      "crop_top": 0,
      "crop_bottom": 0,
      "crop_left": 0,
      "crop_right": 0,
      "border_radius": 0,
      "border_color": "<string>",
      "border_width": 0,
      "shadow_color": "<string>",
      "shadow_blur": 0,
      "shadow_x": 0,
      "shadow_y": 0,
      "x": "50%",
      "y": "50%",
      "width": "100%",
      "height": "100%",
      "aspect_ratio": 123,
      "x_anchor": "50%",
      "y_anchor": "50%",
      "x_rotation": "0°",
      "y_rotation": "0°",
      "z_rotation": "0°",
      "x_scale": "100%",
      "y_scale": "100%",
      "flip_horizontal": false,
      "flip_vertical": false,
      "opacity": 100,
      "z_index": 123,
      "blend_mode": "none",
      "clip": false,
      "color_overlay": "<string>",
      "type": "video",
      "id": "clip_01",
      "name": "<string>",
      "track": 127,
      "time": 0,
      "visible": true,
      "in_point": 0,
      "out_point": 6,
      "speed": 1,
      "volume": 100,
      "fade_in_duration": 0,
      "fade_out_duration": 0,
      "effects": [],
      "motion": []
    }
  ],
  "transitions": [
    {
      "type": "fade",
      "duration": 0.5,
      "from_id": "video_01",
      "to_id": "video_02",
      "z_index": 1
    }
  ],
  "metadata": {
    "project_id": "proj_123"
  },
  "webhook_url": "https://app.example.com/hooks/framelane",
  "ingest_external": true
}
'
{
  "id": "render_01J8QR2K5VKDGN2T4FBM3CZYX7",
  "kind": "render",
  "workspace_id": "ws_01J8QR2K5VKDGN2T4FBM3CZYX8",
  "status": "queued",
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z",
  "task_type": "transcribe",
  "progress_percent": 0,
  "progress_stage": "compositing",
  "output": {
    "url": "https://cdn-user.framelane.io/render_01J.../output.mp4",
    "width": 1920,
    "height": 1080,
    "duration": 15.3,
    "size_bytes": 12582912
  },
  "error": {
    "code": "invalid_source",
    "message": "Source URL returned 404."
  },
  "metadata": {
    "project_id": "proj_123",
    "user_ref": "usr_abc"
  },
  "completed_at": "2023-11-07T05:31:56Z"
}

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. 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 | CompositionElement · object)[]

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

​
transitions
Transition · object[]

Transition effects applied between consecutive elements.

​
metadata
Metadata · object

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

Example:
{ "project_id": "proj_123" }
​
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 render job or AI task.

​
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.

​
task_type
enum<string> | null

For task jobs only — the specific AI operation.

Available options:
remove_background,
gaze_redirect,
super_resolution,
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

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

​
error
JobError · object

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:
{
  "project_id": "proj_123",
  "user_ref": "usr_abc"
}
​
completed_at
string<date-time> | null

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