Agent quickstart: Claude Code, Codex, Cursor

1. Paste this prompt into your agent

Works in Claude Code, Codex and Cursor. It sends the agent to llms.txt (the full contract in one file) and /capabilities (every mode, field, price and limit as JSON; free, no key), so it uses real field names instead of guessing.

Read https://reelsbuilder.ai/docs/api/llms.txt and https://api.reelsbuilder.ai/api/v1/capabilities first. Use only the endpoints and field names they define.

Then build a server-side module in this repo that turns a brief into a finished short-form video with the ReelsBuilder API:

1. Config: base URL https://api.reelsbuilder.ai/api/v1; read the key from the REELSBUILDER_API_KEY environment variable and send it as "Authorization: Bearer <key>". Never put the key in client-side code, logs or committed files.
2. createStockVideo(brief, brand, creativeId):
   a. POST /generate-and-post with the body plus "dry_run": true (free, no Idempotency-Key). Fail if data.valid is false or data.price.usd_cents is above a configurable budget.
   b. POST /generate-and-post with the same body (no dry_run) and the header Idempotency-Key: <client>-<creativeId> (8-256 chars, deterministic, one per creative).
   c. Read data.job_id and data.poll_url from the 202 receipt.
3. waitForJob(jobId): poll GET /jobs/{jobId} starting at 15 s, backing off x1.5 up to 60 s, giving up after 30 min. Stop on completed, failed, dead_lettered or cancelled. Return data.job.artifacts (videoUrl, videoUrls, thumbnailUrl, title, description) or throw data.job.error.
4. If the app can receive HTTP callbacks, also accept webhook_url: add a route that verifies X-ReelsBuilder-Signature (t=<unix>,v1=HMAC-SHA256(secret, "<t>.<raw body>"), secret from GET /webhook-secret, 300 s tolerance, constant-time compare), de-duplicates on job_id and confirms with GET poll_url.
5. Errors: every error is { success:false, error:{ code, message, retryable } }. Retry only when retryable is true; never auto-retry 402 INSUFFICIENT_API_CREDITS; honour Retry-After on 429. Retry a network failure with the SAME Idempotency-Key; resubmit a failed job with a NEW key.
6. Per-client branding: pass a brand object (name, website_url, logo_url, primary_color, accent_color, tone, industry, keywords) and include_branding: false.
7. Tests: unit-test the signature check and the polling backoff with mocked fetch. Do not spend money in tests: use dry_run, or a sandbox key (rb_test_...) if one is configured.

Show me the plan and the dry-run output before making any paid call.

Swap step 2 for another mode if you need it: YouTube clips (POST /clipper/youtube, $0.40 per delivered clip), AI influencer (POST /videos/ai-influencer, from $1.00 per 30 seconds) or AI video (POST /videos/text-to-video, from $4.30 per 30 seconds). Stock video is $0.60.

2. Give the agent a key, safely

Create a key in Settings → API and export it in the shell your agent runs in. Do not paste it into the chat.

export REELSBUILDER_API_KEY=rb_...   # macOS / Linux
$env:REELSBUILDER_API_KEY = "rb_..."  # Windows PowerShell

3. Optional: connect the MCP server

With MCP, the agent can call ReelsBuilder tools (dry runs, YouTube clips, job status, signals) directly while it works. The server is https://api.reelsbuilder.ai/api/v1/mcp (streamable HTTP) and authenticates with the same API key. List the current tools with tools/list or /tools. Publishing is not available over MCP; use the REST Post API.

Claude Code

claude mcp add --transport http reelsbuilder https://api.reelsbuilder.ai/api/v1/mcp --header "Authorization: Bearer $REELSBUILDER_API_KEY"

The shell expands $REELSBUILDER_API_KEY when you run the command, so the stored config contains the key. Keep the default local scope, or add --scope user; do not use the project scope, which writes a .mcp.json you might commit.

Codex

In ~/.codex/config.toml; Codex reads the token from the environment variable, so the file holds no secret:

[mcp_servers.reelsbuilder]
url = "https://api.reelsbuilder.ai/api/v1/mcp"
bearer_token_env_var = "REELSBUILDER_API_KEY"

Cursor

In ~/.cursor/mcp.json (or .cursor/mcp.json in the project; keep it out of git if you hard-code anything):

{
  "mcpServers": {
    "reelsbuilder": {
      "url": "https://api.reelsbuilder.ai/api/v1/mcp",
      "headers": {
        "Authorization": "Bearer ${env:REELSBUILDER_API_KEY}"
      }
    }
  }
}

Other MCP clients usually take the same mcpServers JSON shape with a url and an Authorization header. Config syntax changes between versions; check your client's docs if the server does not appear.

4. What the agent should do (review checklist)

• Dry run first. Every paid call is preceded by the same body with "dry_run": true; the agent shows you data.price and data.normalized_request before spending.
• Idempotency key on every paid call. Idempotency-Key header, 8–256 characters, deterministic per creative. Same key retries a network failure safely; a new video or a resubmitted failed job gets a new key.
• Poll or webhook, never fire and forget. Read data.job_id, then poll GET /jobs/{id} (15 s backoff to 60 s, stop after 30 min) or receive the signed webhook_url callback and verify X-ReelsBuilder-Signature. Finished URLs are in data.job.artifacts.
• Key stays on the server. Never in browser or mobile code, front-end env vars (NEXT_PUBLIC_*, VITE_*), logs, tests or committed config.
• Branch on error.retryable. Errors are error.code, error.message, error.retryable. 402 stops and alerts a human.
• Copy finished files to your own storage; CDN files have a retention window.
• Many videos? POST /batch takes up to 25 jobs; at most 5 stock renders run at once per account.

Next

• Workflow tools: n8n, Make, Zapier templates
• Integration guide: a video pipeline in 8 steps
• Jobs and polling · Webhooks · Errors