# ZapCap

> ZapCap is a REST API for programmatically adding high-quality animated
> subtitles to videos. Process videos in 48 languages with up to 99.9%
> transcription accuracy and transform them using 20+ designer templates.
> Base price: $0.10 per minute of processed video.

This document is the long-form context bundle for LLM assistants. Sources:
public docs at https://platform.zapcap.ai/docs/ and the OpenAPI spec at
https://api.zapcap.ai/api-json (JSON) / https://api.zapcap.ai/api-yaml.

## Overview

ZapCap is a REST API that adds animated subtitles to videos. Send a video,
pick a template, and the default flow returns a rendered MP4 with burned-in
styled captions plus a structured transcript. Transparent overlay and
green-screen export modes are also documented for editor/browser overlay
workflows. Delivery is via webhook or by polling the task endpoint.

Core capabilities documented in the public docs:

- Transcription in 48 languages with up to 99.9% accuracy, automatic punctuation, and custom vocabulary handling.
- 20+ designer templates with programmatic per-task overrides for fonts, colors, animation, emoji, keyword emphasis, and render/export settings.
- Asynchronous processing with webhook notifications, regional edge processing, and CDN delivery of outputs.
- Translation of captions into another target language as part of task creation.
- Custom font upload (TTF / OTF / WOFF / WOFF2, ≤50 MB).
- Transparent caption-only overlays with ProRes 4444 or VP9 alpha, including audio-only source uploads for overlay workflows.

## Authentication

Every request requires an `x-api-key: <KEY>` HTTP header. Generate API
keys at https://platform.zapcap.ai/dashboard/api-key. Never embed keys in
client-side code; route requests through your own backend.

API access requires an active Pro subscription or higher; the web-app
restrictions (video limits, file-size caps, template restrictions) do not
apply to API usage. The API operates on a separate credit-based billing
system.

Check remaining credit balance:

```bash
curl -X GET "https://api.zapcap.ai/user-billing" \
  -H "x-api-key: YOUR_API_KEY"
# → {"balance": "12.34"}   ← remaining USD as a string; parse before arithmetic
```

## Quickstart — five steps from API key to rendered MP4

```bash
# 1. Upload a video (direct upload, multipart upload, or /videos/url)
VIDEO_ID=$(curl -s -X POST "https://api.zapcap.ai/videos" \
  -H "x-api-key: YOUR_API_KEY" \
  -F "file=@video.mp4" | jq -r .id)

# 2. List templates and pick one
curl -X GET "https://api.zapcap.ai/templates" \
  -H "x-api-key: YOUR_API_KEY"
# → array of templates with id, name, preview

# 3. Create a captioning task
TASK_ID=$(curl -s -X POST "https://api.zapcap.ai/videos/$VIDEO_ID/task" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "templateId": "TEMPLATE_ID",
    "autoApprove": true,
    "language": "en"
  }' | jq -r .taskId)

# 4. Poll status (or subscribe via webhook)
curl -X GET "https://api.zapcap.ai/videos/$VIDEO_ID/task/$TASK_ID" \
  -H "x-api-key: YOUR_API_KEY"
# → {"status": "completed", "downloadUrl": "...", "transcript": "..."}
# (The render-completed webhook POST delivers the same asset as "renderUrl",
#  a presigned URL with a 60-minute TTL. The presigned URL carries its own
#  signature in the query string; the x-signature header instead authenticates
#  the webhook POST payload itself — verify it before trusting the callback.)

# 5. Download the rendered MP4
curl -o output.mp4 "DOWNLOAD_URL_FROM_STATUS"
```

When `autoApprove: false` (the default), the pipeline pauses after
transcription so you can edit the transcript via
`PUT /videos/{videoId}/task/{id}/transcript` before triggering the render
with `POST .../approve-transcript`. The approve endpoint takes no body — it
renders whatever transcript is currently saved.

Full Node.js, Python, and curl examples:
https://platform.zapcap.ai/docs/examples/caption-a-video

## Endpoint reference (high level)

Authoritative source: https://platform.zapcap.ai/docs/api or the OpenAPI
spec at https://api.zapcap.ai/api-json.

Videos:
- `POST /videos` — multipart upload. Operation: `uploadVideo`.
- `POST /videos/url` — upload by URL. Operation: `uploadVideoByUrl`.
- `POST /videos/upload` → `POST /videos/upload/complete` — multipart session for large files.
- `GET /videos` — paginated list with metadata.

Tasks (the captioning pipeline):
- `POST /videos/{videoId}/task` — create a captioning task.
- `GET /videos/{videoId}/task/{id}` — get task status and result URLs.
- `POST /videos/{videoId}/task/{id}/approve-transcript` — approve and render (no body).

Transcripts:
- `GET /videos/{videoId}/task/{id}/transcript` — get the transcript as word entries.
- `PUT /videos/{videoId}/task/{id}/transcript` — replace the transcript before rendering.

Fonts:
- `POST /fonts` — upload a custom font (TTF/OTF/WOFF/WOFF2, ≤50 MB).
- `GET /fonts` — list fonts on the account.
- `GET /fonts/{id}` — font detail.
- `DELETE /fonts/{id}` — remove.

Templates:
- `GET /templates` — list available templates with previews.

Billing:
- `GET /user-billing` — remaining credit balance.

## Pricing

Base cost: $0.10 per minute of processed video at default settings, split
as $0.03 transcription + $0.07 rendering. The rendering side is multiplied
by export-setting multipliers, which stack:

| Setting | Option | Multiplier |
| --- | --- | --- |
| FPS | ≤30 fps | 1× |
| FPS | 60 fps | 1.5× |
| FPS | 90 fps | 2× |
| FPS | 120 fps | 2.5× |
| Quality (composited / greenScreen) | 1080p | 1× |
| Quality | 1440p (QHD) | 2× |
| Quality | 4K | 4× |
| Resolution (transparent) | ≤1080p (~2.07 MP) | 1× |
| Resolution | ≤QHD (~3.69 MP) | 2× |
| Resolution | ≤4K (~8.29 MP) | 4× |
| Speed | Standard | 1× |
| Speed | Fast | 1.2× |
| Speed | Ultra Fast | 1.5× |
| Codec | h264 | 1× |
| Codec | ProRes 4444 (transparent .mov) | 1.5× |
| Codec | VP9 with alpha (transparent .webm) | 2× |

Worked examples from the docs:

- 60 fps, 4K, Ultra Fast composited render: $0.03 + $0.07 × 1.5 × 4 × 1.5 × 1 = **$0.66/minute**.
- 1080p, 30 fps, Standard, ProRes 4444 transparent overlay: $0.03 + $0.07 × 1 × 1 × 1 × 1.5 = **$0.135/minute**.
- 1920×1080, 23.976 fps, Standard, VP9 alpha: $0.03 + $0.07 × 1 × 1 × 1 × 2 = **$0.17/minute**.

Default settings (30 fps, 1080p, Standard speed, h264) keep cost at the base
$0.10/minute. For NLE-plugin overlays, ProRes 4444 at 1080p / 30 fps is the
cheapest transparent option.

Storage: $0.015/GB/month, prorated. Files have a configurable TTL — pass
`?ttl=30d` on upload/task requests to set a 30-day retention window. If no
TTL is specified, uploaded videos and generated artifacts are kept
indefinitely and billed using the documented 12-month storage calculation.

Pricing page: https://zapcap.ai/pricing
API billing detail: https://platform.zapcap.ai/docs/billing
Top up credits: https://platform.zapcap.ai/dashboard/billing

## Templates and styling

Each template defines fonts, colors, animation, positioning, and emoji
behavior. Override per task via `renderOptions.subsOptions` and
`renderOptions.styleOptions`:

```json
{
  "renderOptions": {
    "subsOptions": {
      "emoji": true,
      "animation": true,
      "emphasizeKeywords": true
    },
    "styleOptions": {
      "fontSize": 46,
      "fontColor": "#ffffff"
    }
  }
}
```

To use a custom font, upload it via `POST /fonts` (TTF/OTF/WOFF/WOFF2,
≤50 MB) and reference the returned ID in `styleOptions`. Browse templates
in the dashboard at https://platform.zapcap.ai/dashboard/templates.

Configuration reference:
https://platform.zapcap.ai/docs/guides/captions-configuration

## Advanced options

Use `exportSettings` to control `fps`, `quality`, `speed`,
`outputMode`, `outputCodec`, `width`, and `height`. The documented
output modes are:

- `composited` — captions burned onto the source video, output MP4.
- `greenScreen` — captions on a green canvas, output MP4.
- `transparent` — caption-only alpha-channel overlay, output ProRes 4444
  MOV by default or VP9 WebM when `outputCodec: "vp9"`. Transparent renders
  require explicit `width` and `height`; matching the source/timeline
  `fps` is recommended.

Advanced task inputs include `translateTo`, `dictionary`,
`referenceTranscript`, `transcript` for bring-your-own word-level timing,
`autoCutSettings`, and `transcribeSettings.broll`.

Guide: https://platform.zapcap.ai/docs/guides/advanced

## Webhooks

Subscribe to task lifecycle events instead of polling. Webhooks include
signed delivery, retry semantics on non-2xx responses, and transcript,
render, and render-progress notification types for captioning tasks.
Configure the endpoint URL on the task; ZapCap signs each delivery so you
can verify origin.

Guide: https://platform.zapcap.ai/docs/guides/webhooks

## Editing transcripts

Default flow: `autoApprove: true` renders immediately after transcription.
For human review:

1. Create the task with `autoApprove: false` (the default).
2. Poll until status is `transcriptionCompleted`.
3. `GET /videos/{videoId}/task/{id}/transcript` to retrieve word entries (text + timing per word).
4. Modify in place and `PUT` the edited transcript back.
5. `POST /videos/{videoId}/task/{id}/approve-transcript` to render with the saved transcript. The approve call takes no body.

## Limitations

- Maximum video length: **30 minutes** by default. Email hi@zapcap.ai for higher limits.
- Standard video uploads: MP4, QuickTime (MOV). Audio-only uploads such as MP3/WAV are documented for transparent overlay renders.
- Custom fonts: ≤50 MB, TTF / OTF / WOFF / WOFF2.
- For files larger than 100 MB, use the multipart upload endpoint pair (`POST /videos/upload` → `POST /videos/upload/complete`).

## Resources

Docs:
- Introduction: https://platform.zapcap.ai/docs/
- Quickstart: https://platform.zapcap.ai/docs/quickstart
- API reference: https://platform.zapcap.ai/docs/api
- Examples: https://platform.zapcap.ai/docs/examples/caption-a-video
- Guides:
  - Uploading videos: https://platform.zapcap.ai/docs/guides/uploading-videos
  - Captioning tasks: https://platform.zapcap.ai/docs/guides/tasks
  - Captions configuration: https://platform.zapcap.ai/docs/guides/captions-configuration
  - Editing transcripts: https://platform.zapcap.ai/docs/guides/editing-transcripts
  - Custom fonts: https://platform.zapcap.ai/docs/guides/custom-fonts
  - Advanced options: https://platform.zapcap.ai/docs/guides/advanced
  - Webhooks: https://platform.zapcap.ai/docs/guides/webhooks
  - TTL: https://platform.zapcap.ai/docs/guides/ttl
- Billing: https://platform.zapcap.ai/docs/billing
- Limitations: https://platform.zapcap.ai/docs/limitations
- Changelog: https://platform.zapcap.ai/docs/changelog
- Playground: https://platform.zapcap.ai/docs/playground

OpenAPI:
- JSON: https://api.zapcap.ai/api-json
- YAML: https://api.zapcap.ai/api-yaml

Dashboard and account:
- API key: https://platform.zapcap.ai/dashboard/api-key
- Billing: https://platform.zapcap.ai/dashboard/billing
- Templates: https://platform.zapcap.ai/dashboard/templates

Web properties:
- Pricing: https://zapcap.ai/pricing
- Web app (consumer): https://app.zapcap.ai
- Contact: https://zapcap.ai/contact-us
- Email: hi@zapcap.ai