CaptionBurn - Animated Captions That Pop

Getting Started

The CaptionBurn API allows you to programmatically add animated captions to videos. Generate TikTok-style captions with word-by-word highlighting, multiple animation styles, and platform-specific safe zones.

Base URL: https://api.captionburn.com/v1

Quick Example

Here's a complete example of creating a captioned video:

bash

# 1. Upload your video
curl -X POST https://api.captionburn.com/v1/upload \
  -H "Authorization: Bearer cf_your_api_key" \
  -F "file=@video.mp4"

# Response: { "videoUrl": "https://...", "duration": 30.5 }

# 2. Create a caption job
curl -X POST https://api.captionburn.com/v1/jobs \
  -H "Authorization: Bearer cf_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "videoUrl": "https://...",
    "transcriptionMode": "auto",
    "style": {
      "fontFamily": "Inter",
      "fontSize": 48,
      "primaryColor": "#FFFFFF",
      "animation": "bounce"
    },
    "platform": "tiktok"
  }'

# 3. Poll for completion
curl https://api.captionburn.com/v1/jobs/{job_id} \
  -H "Authorization: Bearer cf_your_api_key"

Authentication

CaptionBurn supports two authentication methods: API keys (recommended for server-side) and JWT tokens (for browser-based apps using Supabase Auth).

API Key

Best for server-side integrations. Generate keys from your dashboard.

bash

Authorization: Bearer cf_your_api_key

JWT Token

For browser apps. Use the access token from Supabase Auth.

bash

Authorization: Bearer eyJhbGci...

API Key Management

Account

Get account information and usage statistics for the authenticated user.

Jobs

Jobs are the core resource for creating captioned videos. Each job goes through stages: pending → processing → rendering → completed (or failed).

Upload

Upload videos to our secure storage before creating jobs. Supported formats: MP4, MOV, WebM.

Styles & Platforms

Get available caption styles, fonts, animations, and platform-specific safe zones. These endpoints don't require authentication.

Billing

Manage your subscription and check credit balance. 1 credit = 1 minute of video processing.

Rate Limits

Rate limits vary by plan tier. Limits are applied per user/API key.

Plan	Requests/min	Concurrent Jobs	Max Video Duration
Free	10	1	2 minutes
Starter	30	2	5 minutes
Pro	60	5	10 minutes
Business	120	10	30 minutes

Rate Limit Headers

All responses include rate limit information in headers:

http

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1705312800

Errors

The API uses standard HTTP status codes. All errors return a JSON body witherror andcode fields.

json

{
  "error": "Insufficient credits",
  "code": "INSUFFICIENT_CREDITS",
  "details": {
    "required": 5,
    "available": 2
  }
}

Code	Status	Description
`UNAUTHORIZED`	401	Invalid or missing authentication
`FORBIDDEN`	403	Not allowed to access this resource
`NOT_FOUND`	404	Resource not found
`VALIDATION_ERROR`	400	Invalid request body
`INSUFFICIENT_CREDITS`	402	Not enough credits
`RATE_LIMITED`	429	Too many requests
`FILE_TOO_LARGE`	413	Upload exceeds size limit
`INVALID_FILE_TYPE`	400	Unsupported file format
`JOB_FAILED`	500	Job processing failed
`INTERNAL_ERROR`	500	Unexpected server error