Quickstart

Step 1 — Create your API key

Sign in, then open Settings → API and generate an API key. This creates a live key. Copy it when shown and store it in your backend's secret manager as REELSBUILDER_API_KEY. The full key is shown only once.

Keep the key on your server. Anyone with it can make requests as your account, including paid requests. See authentication for rotation and language examples. The cURL examples below use Bash syntax and environment variables.

Step 2 — Verify access for free

GET /api/v1/usage checks your key and returns your account, balance, current API prices, and limits. It does not create a video or spend credits, including when called with a live key.

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

On a successful response, check:

• meta.key_mode — live or sandbox.
• data.balance.api_credits_usd_cents — your account's prepaid API balance.
• data.pricing — operation prices in USD cents.
• data.limits — request and render concurrency limits.

Optional — Check an integration with a sandbox key

Sandbox keys start with rb_test_. To request one, contact admin@reelsbuilder.ai or your ReelsBuilder contact. The dashboard's key button currently creates live keys.

With a sandbox key, the video request below returns a fixture marked data.sandbox: true. It does not queue a render or charge credits. Fixtures do not validate the full live request or demonstrate video quality. Sandbox polling uses the canonical data.job shape, including data.job.artifacts. Flat sandbox fields are legacy aliases. Use a live job to verify your complete polling integration.

Step 3 — Submit a video request

This step is paid when you use a live key. Review the prices from step 2 and add funds in Settings → API before submitting. Automatic charging is currently unavailable; use a manual top-up when needed.

First send the same Generate body with dry_run: true. This validates the input and returns data.price and data.normalized_request without a job, charge or required idempotency key. Remove dry_run only after approving the quoted cost. See Dry runs.

Create and save a unique ID for this job in your application. Set IDEMPOTENCY_KEY to that value before running the request; keep the same value and body if you need to retry it.

curl -X POST https://api.reelsbuilder.ai/api/v1/generate-and-post \
  -H "Authorization: Bearer $REELSBUILDER_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -d '{
    "prompt": "Explain how two-factor authentication helps protect a small business. Use a professional tone.",
    "content_purpose": "education",
    "clip_type": "tech",
    "duration_target_sec": 30,
    "aspect_ratio": "9:16"
  }'

This endpoint creates a stock-footage video; despite its name, it does not publish to social accounts. Your application handles distribution. A live 202 response provides data.job_id and data.poll_url. Save both with your application's job ID.

This example uses the account's existing brand context. If you generate for multiple customer brands or need private media delivery, send the customer's brand explicitly and check your account's delivery support. See the input map at GET /api/v1/capabilities and confirm private delivery before distributing customer content.

Step 4 — Retrieve the completed video

For a live job, set JOB_ID to the returned data.job_id and poll with the same account's API key. Status requests are free.

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

• data.job.status: "completed" — read the video link from data.job.artifacts.videoUrl. Clipping jobs can also provide multiple links in data.job.artifacts.videoUrls.
• queued, leased, running, or uploading — wait a few seconds before checking again.
• failed, cancelled, or dead_lettered — stop polling and inspect data.job.error before deciding whether to submit a new job.

Available artifacts depend on the generation mode; separate caption and transcript files are not guaranteed. Use authenticated polling to confirm completion. If a failed job's charge needs investigation, include its job ID and request ID when contacting support.

Step 5 — Handle errors and retries

Save meta.request_id from responses for troubleshooting. Inspect the error code before retrying:

• 401 AUTH_REQUIRED or AUTH_INVALID_API_KEY — check the key and Authorization header.
• 400 IDEMPOTENCY_KEY_REQUIRED — supply your saved job ID in the Idempotency-Key header.
• 402 INSUFFICIENT_API_CREDITS — review the requested cost and fund the account before submitting another job.
• 409 RESOURCE_ALREADY_EXISTS — this idempotency key was already used with different request content. Restore the original content for a retry; use a new key only for an intentional new job.
• 429 RATE_LIMIT_EXCEEDED or RENDER_CONCURRENCY_LIMIT_EXCEEDED — respect the Retry-After header and wait for capacity.

Send one request at a time for a given job ID. After acceptance, poll that job instead of submitting it again. A new idempotency key means a new request and can incur another charge.

Use the same account through MCP

The JSON-RPC endpoint is POST https://api.reelsbuilder.ai/api/v1/mcp. Authenticate with the same Bearer key. Discover the available tools and their input schemas with tools/list:

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/list","params":{}}'

Then make a free account check with get_usage:

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": 2,
    "method": "tools/call",
    "params": { "name": "get_usage", "arguments": {} }
  }'

For paid video creation, use generate_video_asset; for YouTube clips, use clip_youtube with either youtube_url or channel_url. Provide idempotency_key where the discovered tool schema supports it. Use clip_youtube with dry_run: true for free previews, and add idempotency_key for paid clipping. If you host your own MCP server, keep the ReelsBuilder key on that server and call the REST API from it.

This connection works with clients that can attach a server-side API key. Hosted ChatGPT and Claude account authorization is still being prepared; a copied prompt does not install a connector or authorize API access. Publishing remains a separate REST operation.

Where to go next

• Video generation reference — input fields and the render receipt.
• YouTube clipping — create clips from a video or a channel's next eligible upload.
• Authentication — key storage, rotation, and examples for your backend.