Video Generation API

Endpoints

Quickstart — Magic Video

The fastest path is Magic Video: pass a topic + your brand_id, get back a fully branded video in 2-4 minutes.

curl -X POST https://api.reelsbuilder.ai/api/v1/videos/magic \
  -H "Authorization: Bearer $REELSBUILDER_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "topic": "shipping velocity benchmarks Q1 2026",
    "brand_id": "brn_01HKZ...",
    "duration_target_sec": 30,
    "webhook_url": "https://your-app.example.com/webhooks/video"
  }'

Initial response

{
  "success": true,
  "data": {
    "job_id": "vjob_01HKZ...",
    "video_id": "vid_01HKZ...",
    "status": "queued",
    "estimated_completion_sec": 180,
    "websocket_url": "wss://api.reelsbuilder.ai/ws/progress?videoId=vid_01HKZ...&token=..."
  },
  "meta": { "request_id": "req_...", "credits_used": 15, "credits_remaining": 985 }
}

Text-to-Video

Pure AI-generated video from a prompt. No script, no voiceover by default — just video. For social-ready posts, prefer Magic Video.

curl -X POST https://api.reelsbuilder.ai/api/v1/videos/text-to-video \
  -H "Authorization: Bearer $REELSBUILDER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Cyberpunk Tokyo at dawn, neon reflections in puddles, slow drone shot",
    "model": "google/veo-3.1",
    "duration_sec": 5,
    "aspect_ratio": "9:16"
  }'

Live API keys bill prepaid USD (see AI_VIDEO_MODEL_PRICING_USD_CENTS). Approximate list prices for typical 6–10s clips:

Image-to-Video

Animate a still image into 3-10 seconds of motion. Best for product shots, character animation, and brand stills.

curl -X POST https://api.reelsbuilder.ai/api/v1/videos/image-to-video \
  -H "Authorization: Bearer $REELSBUILDER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "image_url": "https://your-cdn.example.com/product.jpg",
    "motion_prompt": "slow zoom in, gentle parallax",
    "model": "kling_2_5",
    "duration_sec": 5
  }'

News Video

Broadcast-quality news shorts with lower thirds, tickers, and real-time data overlays. Powered by server/lib/services/broadcast-graphics-service.ts.

curl -X POST https://api.reelsbuilder.ai/api/v1/videos/news \
  -H "Authorization: Bearer $REELSBUILDER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "headline": "Fed signals rate cut for September",
    "source_url": "https://reuters.com/...",
    "graphics_style": "cnn",
    "ticker_data": "stocks",
    "brand_id": "brn_01HKZ..."
  }'

Graphics styles: cnn, bloomberg, fox, bbc, minimal. Ticker data sources: stocks (Finnhub), crypto (CoinGecko), weather (OpenWeatherMap), news (NewsAPI).

Progress via WebSocket

Every video job returns a websocket_url in its initial response. Open it to receive granular progress events (0-100%) with stage labels like "generating script", "rendering captions", "uploading to CDN".

const ws = new WebSocket(job.websocket_url);
ws.onmessage = (event) => {
  const { progress, status, stage, url } = JSON.parse(event.data);
  console.log(`[${progress}%] ${stage}`);
  if (status === "completed") {
    console.log("Done:", url);
    ws.close();
  }
};

Progress history is buffered for 1 hour after completion, so brief network drops don't lose state.

Webhook callback

Alternative to WebSocket. Pass webhook_url in the request body to receive a single video.completed or video.failed event when the job ends. See webhooks.

Captions

All voiceover-bearing modes include karaoke-style captions by default (63 styles available). Disable with captions: false or choose a specific style:

{
  "topic": "...",
  "captions": "neon_outline_yellow"
}

Full caption style catalog returned by GET /api/v1/resources/caption-styles.

Pricing (subscription tokens)

Dashboard/consumer costs use the token scale from packages/config TOKEN_COSTS (not the legacy 1-credit ≈ 100-token display). M2M /api/v1 live keys use prepaid USD (e.g. $0.50 generate_video), not these token rows.

Plan pools (monthly): Starter 10,000, Pro 40,000, Business 150,000. Free tier is fixed starter videos, not a 1,000-token grant.

Performance

• Magic Video p50: 145s | p99: 280s
• Text-to-Video latency varies by current model and provider queue.
• News Video p50: 95s | p99: 200s
• Max job lifetime: 10 minutes (then PROCESS_TIMEOUT with refund)

See also

• Generate & Post API — adds multi-platform fan-out
• Transcribe API — captions for existing videos
• Brand DNA API — required input for Magic Video
• Webhooks — async completion delivery