Get startedQuickstart

Get started

Quickstart

Create an API key, add funds, upload a video and photos, and make your first Siren video.

This guide takes you from a new API key to a finished video.

Prerequisites

  • A Sera Studio account with the owner or admin role in the workspace. Only owners and admins can create API keys; only the owner can add funds.
  • A source video of 1 to 15 seconds (video/mp4 or video/quicktime) and at least one photo (image/jpeg or image/png).
  • curl
Requests made with an API key act for your whole workspace and spend its balance. Use the key only in server-side code and never commit it to source control.

1. Create an API key

Open API keys in the console and select Create API key. Name the key, then select Create key. Copy the key from the next dialog. It is shown only once.

export SERA_API_KEY="sera_sk_..."

2. Add funds

Open Billing and select Add funds. Any amount from $5 becomes your balance one to one. A 9.4-second source at 720p holds $3.50; see Pricing.

3. Upload the source video and a photo

Ask for an upload address, then put the file bytes to it. Do the same for each photo with its content_type.

curl https://serastudio.app/api/v1/uploads \
  -H "Authorization: Bearer $SERA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"content_type": "video/mp4"}'

# then put the bytes to upload_url with the returned headers (no Authorization header)
curl -X PUT "<upload_url>" -H "content-type: video/mp4" -H "x-upsert: false" --data-binary @source.mp4

The first call returns the upload id and the address:

{
  "id": "vid_3f2c7a9e-5d1b-4c8e-9f20-7a6b5c4d3e21",
  "object": "upload",
  "kind": "video",
  "content_type": "video/mp4",
  "upload_url": "https://rvzzbovxmjgldcnlbwyx.supabase.co/storage/v1/object/upload/sign/episodes/7d9e2f10-4b3a-4c5d-8e6f-0a1b2c3d4e5f/episodes/refs/3f2c7a9e-5d1b-4c8e-9f20-7a6b5c4d3e21.mp4?token=<signed>",
  "upload_method": "PUT",
  "upload_headers": {
    "content-type": "video/mp4",
    "x-upsert": "false"
  },
  "upload_url_expires_at": "2026-11-09T07:08:00.000Z",
  "max_bytes": 52428800,
  "created_at": "2026-11-09T05:08:00.000Z"
}

4. Create the generation

Pass the video id as source and the photo ids as images. The Idempotency-Key header makes a retry safe.

curl https://serastudio.app/api/v1/siren/generations \
  -H "Authorization: Bearer $SERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1182" \
  -d '{"source": {"upload_id": "vid_…"}, "images": [{"upload_id": "img_…"}], "resolution": "720p", "source_duration_s": 9.4}'

The API returns 202 with the generation. billing.held_usd ($3.50 here) is held from your balance.

{
  "id": "0b6e2c1a-7c1a-4f5e-9a51-2b3c4d5e6f70",
  "object": "generation",
  "model": "siren",
  "status": "queued",
  "created_at": "2026-11-09T05:11:02.000Z",
  "finished_at": null,
  "input": {
    "source": {
      "upload_id": "vid_3f2c7a9e-5d1b-4c8e-9f20-7a6b5c4d3e21"
    },
    "images": [
      {
        "upload_id": "img_9a0b8c7d-6e5f-4a3b-8c2d-1e0f9a8b7c6d"
      }
    ],
    "prompt": "Keep the motion.",
    "resolution": "720p",
    "source_duration_s": 9.4,
    "webhook_url": null
  },
  "progress": {
    "stage": "queued",
    "percent": 0
  },
  "output": null,
  "output_deleted": false,
  "error": null,
  "billing": {
    "currency": "usd",
    "resolution": "720p",
    "usd_per_second": 0.175,
    "discount_pct": 0,
    "held_usd": 3.5,
    "charged_usd": null,
    "restored_usd": 0,
    "settled": false
  },
  "idempotency_key": "order-1182"
}

5. Wait for the result

Get the generation with wait_s=20; the server waits up to that long for it to finish before answering. Repeat while the status is queued or in_progress.

curl "https://serastudio.app/api/v1/generations/0b6e2c1a-7c1a-4f5e-9a51-2b3c4d5e6f70?wait_s=20" \
  -H "Authorization: Bearer $SERA_API_KEY"

When it is done the status is succeeded, output.url is the MP4 and billing.charged_usd is the final charge:

{
  "id": "0b6e2c1a-7c1a-4f5e-9a51-2b3c4d5e6f70",
  "object": "generation",
  "model": "siren",
  "status": "succeeded",
  "created_at": "2026-11-09T05:11:02.000Z",
  "finished_at": "2026-11-09T05:14:40.000Z",
  "input": {
    "source": {
      "upload_id": "vid_3f2c7a9e-5d1b-4c8e-9f20-7a6b5c4d3e21"
    },
    "images": [
      {
        "upload_id": "img_9a0b8c7d-6e5f-4a3b-8c2d-1e0f9a8b7c6d"
      }
    ],
    "prompt": "Keep the motion.",
    "resolution": "720p",
    "source_duration_s": 9.4,
    "webhook_url": null
  },
  "progress": null,
  "output": {
    "url": "https://rvzzbovxmjgldcnlbwyx.supabase.co/storage/v1/object/sign/episodes/7d9e2f10-4b3a-4c5d-8e6f-0a1b2c3d4e5f/episodes/0b6e2c1a-7c1a-4f5e-9a51-2b3c4d5e6f70/a1/master.mp4?token=<signed>",
    "thumbnail_url": "https://rvzzbovxmjgldcnlbwyx.supabase.co/storage/v1/object/sign/episodes/7d9e2f10-4b3a-4c5d-8e6f-0a1b2c3d4e5f/episodes/0b6e2c1a-7c1a-4f5e-9a51-2b3c4d5e6f70/a1/thumb.jpg?token=<signed>",
    "duration_s": 9.4,
    "url_expires_at": "2026-11-09T06:15:00.000Z",
    "retained_until": "2026-11-16T05:14:40.000Z"
  },
  "output_deleted": false,
  "error": null,
  "billing": {
    "currency": "usd",
    "resolution": "720p",
    "usd_per_second": 0.175,
    "discount_pct": 0,
    "held_usd": 3.5,
    "charged_usd": 3.5,
    "restored_usd": 0,
    "settled": true
  },
  "idempotency_key": "order-1182"
}
output.url is a signed address that expires; get the generation again for a fresh one. The file itself is kept for 7 days after it finished, then deleted.

Next steps