Quickstart

Step 1 — Get a sandbox key

Sign in at reelsbuilder.ai/auth, open the API Settings tab, and click Generate API Key. Sandbox keys start with rb_test_ and never spend live credits.

For integrators (e.g. Traders.Money), an operator can mint one for any existing account by email:

# repo: AlecFurrier/reelsbuilder
cd web
vercel env pull --environment=production .env.production
MINT_API_KEY_ALLOWED=1 bun run scripts/mint-api-key.ts \
  --email=ops@your-domain.tld

The script prints the key once. Hand it off out-of-band — never paste it into chat, git, or shared docs.

Step 2 — Verify the key with get_usage

GET /api/v1/usage is free, never deducts, and returns your account state plus the live USD pricing table:

curl https://api.reelsbuilder.ai/api/v1/usage \
  -H "Authorization: Bearer $REELSBUILDER_API_KEY"

Sandbox keys return key_mode: "sandbox" and a placeholder balance. Live keys return the real api_credits_usd_cents balance, auto-refill state, and the operation-price map keyed by tool name.

Step 3 — Queue a sandbox render

With a sandbox key, paid render tools return a 202 fixture with sandbox: true — no jobs queued, no credits charged. Useful for wiring the polling and error paths before spending anything:

IDEMPOTENCY_KEY=$(uuidgen)

curl -X POST https://api.reelsbuilder.ai/api/v1/videos/magic \
  -H "Authorization: Bearer $REELSBUILDER_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -d '{
    "prompt": "Explain my product in 15 seconds, vertical, professional",
    "duration_target_sec": 15,
    "aspect_ratio": "9:16",
    "agent_run_id": "quickstart-step-3"
  }'

Reuse the same Idempotency-Key only when retrying the same logical job. A different key + same body queues a second render. The same key + different body returns 409 IDEMPOTENCY_BODY_MISMATCH.

Step 4 — Poll status

Every paid render returns a job_id and poll_url. GET /api/v1/jobs/{job_id} is free and reads the terminal state once the worker finishes:

curl https://api.reelsbuilder.ai/api/v1/jobs/$JOB_ID \
  -H "Authorization: Bearer $REELSBUILDER_API_KEY"

# Terminal states:
#   completed  -> data.job.artifacts.videoUrl + captions + transcript
#   failed     -> data.job.error  (also: credits auto-refunded)
#   leased / running / uploading -> keep polling

Recommended cadence: 2s for the first 30s, then 5s. Webhooks are not stable in the public-beta surface yet — polling is the only contract you should depend on.

Step 5 — Switch to a live key

Mint a live key (rb_, no _test_), fund the balance with at least $10 either through the UI or the topup API, and replay the same request body with a new idempotency key:

# Operator-side
MINT_API_KEY_ALLOWED=1 bun run scripts/mint-api-key.ts \
  --email=ops@your-domain.tld --live

# Fund via dashboard:
#   https://reelsbuilder.ai/dashboard/settings/api  ->  "Top up $10"

# Or programmatically (session-auth, not API-key):
curl -X POST https://reelsbuilder.ai/api/api-credits/topup \
  -H "Cookie: <session_cookie>" \
  -H "Content-Type: application/json" \
  -d '{"usdCents": 1000}'   # returns checkout_url

Successful checkout writes an ApiCreditEvent of kind topup and saves the card with setup_future_usage: "off_session" so auto-refill can charge it later without user interaction.

Step 6 — Handle 402 / 409 / 429 / job failure

Every error response shares one envelope: { success: false, error: { code, message, retryable, ... }, meta }

The four codes that matter:

• 402 INSUFFICIENT_API_CREDITS — body includes cost_usd_cents, balance_usd_cents, and topup_min_usd_cents. Surface the top-up URL to the human operator; never retry blindly.
• 409 IDEMPOTENCY_BODY_MISMATCH — you reused a key with a different body. Generate a new key for a new logical job.
• 429 RATE_LIMIT_EXCEEDED or RENDER_CONCURRENCY_LIMIT_EXCEEDED — read Retry-After or poll an existing job before queueing a new one.
• Job status: failed — credits are auto-refunded via an ApiCreditEvent of kind refund. Inspect data.job.error.code before retrying; do not blindly requeue.

The middleware also gates every paid call on Idempotency-Key being present — so even if a route handler forgets to require one, you cannot accidentally double-spend.

Step 7 — MCP from Claude Desktop or Codex

The same key works against the JSON-RPC MCP endpoint at POST https://api.reelsbuilder.ai/api/v1/mcp (protocol 2025-06-18). MCP tools/list returns only the executable tools (get_usage, generate_and_post, blog_to_video, generate_article, get_job_status, get_x_hooks); paid calls require idempotency_key in the tool arguments because MCP clients cannot reliably pass arbitrary HTTP headers.

Claude Desktop config snippet (claude_desktop_config.json):

{
  "mcpServers": {
    "reelsbuilder": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-fetch",
        "https://api.reelsbuilder.ai/api/v1/mcp"
      ],
      "env": {
        "FETCH_AUTH_HEADER": "Bearer rb_test_REPLACE_ME"
      }
    }
  }
}

Codex / CLI agents call the JSON-RPC directly:

curl -X POST https://api.reelsbuilder.ai/api/v1/mcp \
  -H "Authorization: Bearer $REELSBUILDER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "generate_and_post",
      "arguments": {
        "prompt": "Explain my product in 15 seconds",
        "idempotency_key": "quickstart-mcp-1"
      }
    }
  }'

Where to go next

• Agent Generate API — full schema for the main paid render path.
• Autoblog Video API — article → companion video.
• Idempotency rules — the full request → replay → conflict matrix.
• Error catalog — every code, its retryability, and the recommended agent behavior.
• Prepaid business model — top-up minimum, USD-cent pricing, auto-refill, and the ledger semantics.