Quickstart

1. Get your API key

Humans: sign up at console.framelane.io and copy your API key from Settings → API Keys. Agents (no human, no browser): provision a key over the API. POST /v1/signup returns a key immediately and emails a 6-digit code; read it from the inbox you signed up with, then confirm it with POST /v1/signup/verify to activate the key. Until you verify, the key returns 403 email_not_verified on every call. See Self-provisioning for agents.

curl -X POST https://api.framelane.io/v1/signup \
  -H "Content-Type: application/json" \
  -d '{"workspace_name": "my-agent", "email": "agent@example.com"}'
# → 201 { "api_key": { "key": "fl_..." }, "otp_delivered": true }

curl -X POST https://api.framelane.io/v1/signup/verify \
  -H "Content-Type: application/json" \
  -d '{"email": "agent@example.com", "otp_code": "123456"}'
# the fl_ key from signup works the moment this returns 200

2. Upload your input file

If your video is already hosted at a public HTTPS URL you control, skip to step 3 and use that URL as source_url. To use a file at a public URL you don’t control, pass a direct link to it as the element source_url — the render engine fetches it at render time, and video or audio is probed for its duration first so you can omit out_point. Share-page links (Drive, Dropbox, YouTube) are not direct file URLs. For a local file, request an upload slot and PUT the bytes to GCS:

curl -X POST https://api.framelane.io/v1/uploads \
  -H "Authorization: Bearer $FRAMELANE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"content_type": "video/mp4", "filename": "input.mp4"}'

# Save upload_url and source_url from the response above
curl -X PUT "$UPLOAD_URL" \
  -H "Content-Type: video/mp4" \
  --data-binary @input.mp4

You will use source_url from the upload response in the render request. For a small local file (under 256 KB — a logo, a crest, an icon) you can skip the second step entirely: pass the bytes as base64 in content_base64 on the first call and it stores them, returning "uploaded": true. That route makes no outbound request of your own, so it also works from a sandbox that blocks storage.googleapis.com. See Uploading media for that, the supported MIME types and the error codes.

3. Submit a render

Send a POST /v1/renders request with your composition. Replace source_url with your upload URL or any public HTTPS URL:

curl -X POST https://api.framelane.io/v1/renders \
  -H "Authorization: Bearer $FRAMELANE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: quickstart-render-1" \
  -d '{
    "width": 1920,
    "height": 1080,
    "duration": 5.0,
    "frame_rate": 30,
    "output_format": "mp4",
    "elements": [
      {
        "type": "video",
        "id": "clip1",
        "source_url": "https://cdn-user.framelane.io/uploads/ws_01J.../input.mp4",
        "time": 0,
        "in_point": 0,
        "out_point": 5
      }
    ]
  }'

import Framelane from "@framelane/sdk";

const client = new Framelane({ apiKey: process.env.FRAMELANE_API_KEY });

const render = await client.renders.create({
  width: 1920,
  height: 1080,
  duration: 5.0,
  frameRate: 30,
  outputFormat: "mp4",
  elements: [
    {
      type: "video",
      id: "clip1",
      sourceUrl: process.env.SOURCE_URL!,
      time: 0,
      inPoint: 0,
      outPoint: 5,
    },
  ],
});

console.log(render.id, render.status); // render_01J... queued

import os
import framelane

client = framelane.Framelane(api_key=os.environ["FRAMELANE_API_KEY"])

render = client.renders.create(
    width=1920,
    height=1080,
    duration=5.0,
    frame_rate=30,
    output_format="mp4",
    elements=[
        {
            "type": "video",
            "id": "clip1",
            "source_url": os.environ["SOURCE_URL"],
            "time": 0,
            "in_point": 0,
            "out_point": 5,
        }
    ],
)

print(render.id, render.status)  # render_01J... queued

The API returns 202 Accepted immediately with a job object:

{
  "id": "render_01J8QR2K5VKDGN2T4FBM3CZYX7",
  "kind": "render",
  "status": "queued",
  "progress_percent": 0,
  "created_at": "2026-05-21T07:00:00Z",
  "updated_at": "2026-05-21T07:00:00Z"
}

Save the id — you need it to poll status or download the result.

4. Wait for completion

Option A — Poll job status (simplest for scripts)

Call GET /v1/renders/{id} until status is terminal (completed, failed, or cancelled):

curl https://api.framelane.io/v1/renders/render_01J8QR2K5VKDGN2T4FBM3CZYX7 \
  -H "Authorization: Bearer $FRAMELANE_API_KEY"

Prefer long-polling to a poll loop. GET /v1/renders/{id}?wait=25 holds the request open until the render is terminal (completed / failed / cancelled) or ~25 seconds elapse (capped server-side), then returns the current state — one call instead of a whole loop. If it comes back still in flight, Retry-After: 0 is set: call again immediately. The same ?wait= works on GET /v1/tasks/{id} and on preview renders.

While processing, status is queued or processing and progress_percent updates over time. When status is completed, the response includes output.url:

{
  "id": "render_01J8QR2K5VKDGN2T4FBM3CZYX7",
  "status": "completed",
  "progress_percent": 100,
  "output": {
    "url": "https://cdn-user.framelane.io/render_01J.../output.mp4",
    "width": null,
    "height": null,
    "duration": null,
    "size_bytes": null
  }
}

output.url is the field to use — download the finished video from it. The width, height, duration, and size_bytes fields are reserved and currently return null; the output dimensions and duration match your render request, and the byte size is available from the download response’s Content-Length.

Or use the SDK helper, which does this for you:

const completed = await client.renders.waitForCompletion(render.id);

completed = client.renders.wait_for_completion(render.id)

The same polling pattern applies to tasks via GET /v1/tasks/{id}.

Option B — Webhooks (recommended for production)

curl -X POST https://api.framelane.io/v1/webhooks \
  -H "Authorization: Bearer $FRAMELANE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://yourapp.com/webhooks/framelane",
    "events": ["render.completed", "render.failed"]
  }'

When complete, you’ll receive:

{
  "type": "render.completed",
  "data": {
    "id": "render_01J8QR2K5VKDGN2T4FBM3CZYX7",
    "status": "completed",
    "output": {
      "url": "https://cdn-user.framelane.io/render_01J.../output.mp4",
      "width": 1920,
      "height": 1080,
      "duration": 5.0,
      "size_bytes": 8388608
    }
  }
}

5. Download the artifact

The output.url in the job response or webhook is a signed CDN URL. You can also request a fresh download redirect:

curl -L https://api.framelane.io/v1/renders/render_01J.../download \
  -H "Authorization: Bearer $FRAMELANE_API_KEY" \
  -o output.mp4

Next steps

Uploading media

Local files via signed GCS upload, or remote URLs with ingest_external.

Run an AI task

Transcribe audio or video to text with word-level timestamps.

Verify webhook signatures

Validate HMAC signatures to ensure payloads come from Framelane.

API Reference

Browse all endpoints generated from the OpenAPI spec.

Get Started

Renders

Render Examples

Recipes

Projects

Tasks

Webhooks

Guides

SDKs

1. Get your API key

2. Upload your input file

3. Submit a render

4. Wait for completion

Option A — Poll job status (simplest for scripts)

Option B — Webhooks (recommended for production)

5. Download the artifact

Next steps

Uploading media

Run an AI task

Verify webhook signatures

API Reference

​1. Get your API key

​2. Upload your input file

​3. Submit a render

​4. Wait for completion

​Option A — Poll job status (simplest for scripts)

​Option B — Webhooks (recommended for production)

​5. Download the artifact

​Next steps

Uploading media

Run an AI task

Verify webhook signatures

API Reference

1. Get your API key

2. Upload your input file

3. Submit a render

4. Wait for completion

Option A — Poll job status (simplest for scripts)

Option B — Webhooks (recommended for production)

5. Download the artifact

Next steps