# Zaption

> Burned-in, word-by-word captions for short videos, through a REST API. Send a video, get back an MP4 with animated captions plus SRT, VTT, and word timings. $0.04 a minute, or $0.01 a minute for subtitle files only. No watermark.

Base URL: https://zaption.com/v1
Auth: `Authorization: Bearer zap_live_...` (spends credits) or `zap_test_...` (free, fixed test words, real render). Keys come from https://zaption.com/keys.

## Docs

- [OpenAPI 3.1 spec](https://zaption.com/v1/openapi.json): every endpoint, field, and error.
- [Styles](https://zaption.com/v1/styles): the caption styles and the fields `style_overrides` can change.
- [Pricing](https://zaption.com/v1/pricing): plans and API prices.

## The flow

1. `POST /v1/captions` with `{"video_url": "https://...", "style": "bolt"}` and an `Idempotency-Key` header. Or first `POST /v1/uploads` with `filename`, `content_type`, `size_bytes`, PUT the bytes to `upload_url` with the returned `headers`, then pass `upload_id`.
2. The answer is `202` with a caption object: `id`, `status`, `progress`.
3. Poll `GET /v1/captions/{id}` every few seconds until `status` is `done` or `failed`, or pass `webhook_url` and wait for `caption.completed` or `caption.failed`. A failed caption has `error.code` and is not charged.
4. Download from `files.mp4.url`, `files.srt.url`, `files.vtt.url`, `files.json.url`. Links last 1 hour. GET the caption again for fresh ones.

To fix words: `GET /v1/captions/{id}?include=transcript`, change `transcript.words`, `PATCH /v1/captions/{id}` with `{"transcript": ...}`, then `POST /v1/captions/{id}/render` (with a new `Idempotency-Key`). Each render with `mp4` costs the render price again: $0.03 a minute, 2x above 1080p. Wait for `done` or `failed`, or `caption.completed` / `caption.failed` on the webhook.

## Rules that matter

- `Idempotency-Key` is required on `POST /v1/captions` and `POST /v1/captions/{id}/render` with an API key. Retrying with the same key and body returns the first answer and never charges twice.
- `outputs` defaults to `["mp4", "srt", "vtt", "json"]`. Leave out `mp4` for subtitles only at $0.01 a minute.
- `max_resolution` is 720, 1080 (default), 1440, or 2160. Above 1080 the render part costs 2x.
- Videos up to 30 minutes and 2 GB: mp4, mov, webm, mkv, m4v. `video_url` must be public https.
- `POST /v1/estimate` with `{"duration_s": 60}` gives the price first. `GET /v1/balance` gives the credits left.
- Errors are `{"error": {"code", "message", "request_id", ...}}`. `402 INSUFFICIENT_CREDITS` means add credits at https://zaption.com/billing. `429 RATE_LIMITED` has `retry_after`.
- Webhooks are signed: header `Zaption-Signature: t=<unix>,v1=<hex HMAC-SHA256 of "<t>.<body>">` with the secret from `GET /v1/webhook-secret`.
- Live files are deleted after 7 days, test files after 24 hours. Zaption doesn't train on your videos.

## Example

```bash
curl -s https://zaption.com/v1/captions \
  -H "Authorization: Bearer $ZAPTION_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"video_url": "https://example.com/clip.mp4", "style": "bolt"}'
```

Styles: bolt, arc, flash, clean, outline, boxed, storm, pop-art.
Contact: help@zaption.com