Renders

​

How renders work

1. Provide your media (if needed) — pass a source_url you already host on a CDN, upload local files with POST /v1/uploads, or have Framelane copy a public URL or cloud share link into storage for you by setting ingest_external: true on the render. See Uploading media.
2. Submit a POST /v1/renders request with your composition — canvas and output settings, elements[], transitions[], and the composition-level extras: groups[] (transform groups with optional stack layout), custom_animations (your own keyframe definitions), motion_blur, background_gradient, watermark_url, alpha.
3. Job accepted — the API returns 202 Accepted with a render_* job ID and status: queued. When the render copies in external files (ingest_external), it starts as ingesting and transitions to queued automatically once every file is ready. The 202 also carries an advisory ok + violations[] lint of the composition — see Preview & validate; it never blocks the render, and the free dry_run is the check to gate on.
4. GPU engine processes — the Framelane Renderer runs on dedicated GPU hardware.
5. Wait for completion — poll GET /v1/renders/{id} until status is terminal, or receive a render.completed / render.failed webhook.
6. Download — use output.url from the job response, or GET /v1/renders/{id}/download for a fresh signed redirect.

​

Job lifecycle

(ingesting)  →  queued  →  processing  →  completed
                                       ↘  failed
                                       ↘  cancelled

​

Idempotency

Idempotency-Key: my-project-render-v3

• Same body → 200 OK with the existing job (no new render, no new charge)
• Different body → 409 Conflict

​

Endpoints

​

Minimal example

{
  "width": 1920,
  "height": 1080,
  "duration": 10.0,
  "frame_rate": 30,
  "output_format": "mp4",
  "elements": [
    {
      "type": "video",
      "id": "clip1",
      "source_url": "https://cdn.example.com/input.mp4",
      "time": 0,
      "in_point": 0,
      "out_point": 10
    },
    {
      "type": "text",
      "id": "title",
      "text": "Hello World",
      "time": 0,
      "duration": 5,
      "x": "50%",
      "y": "50%",
      "font_size": 72,
      "text_color": "#ffffff"
    }
  ]
}