Getting started

reelsdk docs

reelsdk turns one HTTP request into a finished MP4. Its 4 endpoints make photo slideshows, burn in word-by-word captions, write and render faceless shorts and run raw ffmpeg, and a create call waits up to 60 seconds for the result, so most videos come back in the same response.

This page takes you from an API key to your first video in about 2 minutes.

Quickstart#

Get an API key
Sign up with Google and create a key in the dashboard. You get an rk_live_ API key, shown once, and a whsec_ secret for verifying webhooks. Your first $1 of renders is free. Put the key in an environment variable.
```
export REELSDK_KEY="rk_live_..."
```

Send your first request

This turns three photos into a 7 second narrated clip with karaoke captions. It needs nothing but your key, and it took 13 seconds in our test.

curl -sS "https://api.reelsdk.com/v1/slideshow" \
  -H "Authorization: Bearer $REELSDK_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "images": [
      "https://picsum.photos/id/1015/1920/1080",
      "https://picsum.photos/id/1018/1920/1080",
      "https://picsum.photos/id/1036/1920/1080"
    ],
    "size": "16:9",
    "voiceover": {
      "text": "Three days by the water. Mountains at sunrise, forests by noon, and a lake that held the whole sky.",
      "voice": "luna"
    },
    "captions": "karaoke"
  }'

Run the JavaScript as an .mjs file on Node 18 or newer. The Python example uses the requests package.

Download the video

The call holds the connection open until the job finishes and answers 200 with the job. job.outputs.video is your MP4, next to the transcript and subtitle files.

200 OK

{
  "job": {
    "id": "job_2q9jwcnzk4c85tuil3p1",
    "op": "slideshow",
    "status": "succeeded",
    "stage": null,
    "created_at": "2026-10-26T01:15:30.646Z",
    "finished_at": "2026-10-26T01:15:43.336Z",
    "outputs": {
      "video": "https://api.reelsdk.com/f/out/job_2q9jwcnzk4c85tuil3p1/video.mp4",
      "transcript": "https://api.reelsdk.com/f/out/job_2q9jwcnzk4c85tuil3p1/transcript.json",
      "srt": "https://api.reelsdk.com/f/out/job_2q9jwcnzk4c85tuil3p1/captions.srt",
      "vtt": "https://api.reelsdk.com/f/out/job_2q9jwcnzk4c85tuil3p1/captions.vtt",
      "ass": "https://api.reelsdk.com/f/out/job_2q9jwcnzk4c85tuil3p1/captions.ass"
    },
    "result": null,
    "duration_s": 7.2,
    "error": null,
    "usage": {
      "output_seconds": 7.2,
      "audio_seconds": 6.696,
      "tts_characters": 99,
      "images": 0
    },
    "poll_url": "https://api.reelsdk.com/v1/jobs/job_2q9jwcnzk4c85tuil3p1"
  }
}

Output URLs need no key, so you can hand them straight to a player or your users. They stay up for 7 days.

Authentication#

Every endpoint lives under https://api.reelsdk.com and takes and returns JSON, except uploads, which take the raw file. Send your key in the Authorization header on every /v1 request.

Authorization: Bearer rk_live_...

A missing, malformed or unknown key returns 401 UNAUTHORIZED. File URLs under /f/ need no key.

Getting results#

Every create call returns a job that ends as succeeded or failed. There are three ways to get the finished result.

Wait

Create calls wait up to 60 seconds for the job by default. Set ?wait= up to 300 to wait longer, or 0 to return at once.

Waiting

Poll

A job still running when the wait ends returns 202 with a Location header. Call GET /v1/jobs/{id}?wait=60 until it's done.

Polling

Webhook

Add a webhook_url and we POST the signed job to your server when it finishes. Ideal for shorts, which take about 100 seconds.

Webhooks

Slideshows, captions and most ffmpeg commands finish within the default wait. Shorts take longer, so create them with Prefer: respond-async and poll or use a webhook.

Endpoints#

POST /v1/slideshowSlideshow1 to 100 photos into an MP4 with voiceover, music, captions and transitions.POST /v1/captionsCaptionsWord-by-word captions burned into any video of up to 15 minutes.POST /v1/shortsShortsA topic or script into a finished 15 to 90 second faceless short.POST /v1/ffmpegFFmpegYour own ffmpeg 8.1 command on up to 50 input files.GET /v1/jobs/{id}JobsStatus, outputs and usage of any job, with long polling.POST /v1/uploadsUploadsStore a local file of up to 100 MB and get a URL to use as an input.

Errors#

Errors are JSON with a stable error.code to branch on and an error.message you can show. Validation errors also list every bad field in issues.

400 Bad Request

{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "video_url: must be an http(s) URL; style: style must be a preset name or a style object",
    "issues": [
      { "path": "video_url", "message": "must be an http(s) URL" },
      {
        "path": "style",
        "message": "style must be a preset name or a style object"
      }
    ]
  }
}

A job that fails answers 422 when the inputs are the problem and 500 when we are, with the job next to the error. Errors lists every code and how to fix it.

For coding agents#

The open-source reelsdk MCP server gives Claude Code, Cursor, Windsurf and VS Code six tools: add_captions, make_slideshow, make_short, run_ffmpeg, get_job and upload_file. It uploads local files for you and saves the results in ./reelsdk-output. It runs with Node 20 or newer and needs git to install.

claude mcp add reelsdk --env REELSDK_KEY=rk_live_... -- npx -y github:bitgate/reelapi-mcp

Two machine-readable files describe the whole API. Point your coding agent or SDK generator at them.

/llms.txt is the full API on one plain-text page, sized for an LLM's context window.
/openapi.json is an OpenAPI 3.1 spec with every request and response schema.

Shorts Studio is an open-source starter app on Cloudflare Workers: type a topic and get a finished short. Clone it, or deploy it to your own Cloudflare account in one click.

Last updated 26 October 2026