API reference

All endpoints live under https://api.caption.sh/v1. Every request is authenticated (see Authentication), and errors share one JSON shape: { error, detail, request_id }.

Sign in with your account (Clerk hosted login) to manage keys, usage, and billing in the dashboard. For programmatic access, create a per-user API key and send it as a bearer token. Both a Clerk JWT and an API key resolve to the same account:

Authorization: Bearer sk_live_...   # an API key
Authorization: Bearer eyJraWQ...    # or a Clerk JWT (web session)

The web app uses your session JWT; scripts and pipelines use an API key. Keys are shown once at creation, hashed at rest, and revocable from the dashboard.

One call to POST /v1/videos creates the job. With the SDK, createVideo(file, options) uploads the file and enqueues the render in a single step; with raw HTTP the response hands back a presigned form to POST the file to storage. Then poll until it's done and download the MP4. Defaults give medium white captions at the bottom, active word highlighted, black outline, up to 3 words per group.

import { Caption } from "caption.sh";

const caption = new Caption(process.env.CAPTION_API_KEY);

// One call: uploads the file, creates the job, returns a job id.
const { jobId } = await caption.createVideo(file, { size: "large" });

// Or pull from a URL: the bytes never leave your storage:
// const { jobId } = await caption.createVideoFromUrl(url, { size: "large" });

// Wait for the render, then grab the captioned MP4.
await caption.pollJob(jobId);
const resultUrl = await caption.getResultUrl(jobId); // signed video/mp4 URL

# Truly one call: hand the API a URL and it pulls the video itself :
# no upload step, no presigned form, no second request.
curl -X POST https://api.caption.sh/v1/videos \
  -H "Authorization: Bearer $CAPTION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"source_url":"https://cdn.example.com/clip.mp4","options":{"size":"large"}}'
# -> 202 { "job_id": "..." }   # then poll /v1/jobs/{id} as usual

# File upload:
awaiting_upload -> queued -> running -> done   # result ready at /v1/jobs/{id}/result
# source_url pull:
queued -> running -> done
# on failure:
running -> error                               # generic message to you, detail logged server-side

All fields are optional: send only the ones you want to change, inside the job's options object. Fields that take a preset or a number let you stay high-level ("medium") or go precise (0.06): the number is always a fraction of the video's own dimension, so it scales with any input size.

Colour format: Hex strings, #RRGGBB (case-insensitive, leading # optional). Invalid colours are rejected with 422.

The presets are the numeric fractions the keywords expand to: a starting point for fine-tuning with a raw number.

Set with the font option: e.g. lobster. All 18 fonts are bundled in the image (nothing is downloaded at request time) and are open source (OFL / Apache-2.0), free to embed and burn into your video. Pass one of the keys below; an unknown key returns 422. Default: luckiest-guy.

Legibility tip: script/handwriting fonts (thin strokes) read best at a larger size and with decoration: "backdrop" or a bold text_color. Display fonts shine with the default outline.

You never have to worry about text overflowing. For every caption group the renderer works through the same four steps:

Every response carries a request_id; errors share the JSON shape { error, detail, request_id }.

MVP limits: Max video length 10 minutes. Results are stored for 24 hours and then deleted: download promptly, or re-run the job. Because the work runs async, there's no request-timeout ceiling: submit, poll, and collect the result when it's ready.