Stock Video API

What this endpoint does

POST /api/v1/generate-and-post queues one paid video render and returns a job handle. It does not post or schedule anything — the name is kept for compatibility. When the job completes, your system decides what to do with the video: a blog embed, a CMS draft, an approval queue, or a post via POST /api/v1/post.

Endpoint

POST https://api.reelsbuilder.ai/api/v1/generate-and-post

Idempotency-Key is required (see Idempotency). Requests without it return 400 IDEMPOTENCY_KEY_REQUIRED. Dry runs are the exception: add "dry_run": true to validate the request and get its price for free, without a key and without creating a job (see Dry run).

Quickstart

curl -X POST https://api.reelsbuilder.ai/api/v1/generate-and-post \
  -H "Authorization: Bearer $REELSBUILDER_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A 30 second explainer on how Acme cuts onboarding time in half.",
    "content_purpose": "education",
    "platforms": ["youtube_shorts", "tiktok", "instagram"],
    "duration_sec": 30,
    "aspect_ratio": "9:16",
    "content_style": "professional",
    "agent_run_id": "agent-run-2026-10-06-001"
  }'

Accepted response (202)

{
  "success": true,
  "data": {
    "job_id": "6a0f...",
    "generation_id": "6a0f...",
    "video_id": "6a0f...",
    "status": "queued",
    "poll_url": "/api/v1/jobs/6a0f...",
    "distribution": {
      "mode": "external_agent_distribution",
      "requested_platforms": ["youtube_shorts", "tiktok", "instagram"],
      "schedule_at": null,
      "webhook_url": null
    },
    "output_contract": {
      "video_url": "available after completion on GET /api/v1/jobs/{job_id}.data.job.artifacts.videoUrl",
      "social_metadata": { "title": "...", "description": "...", "platforms": ["..."] }
    },
    "price_usd_cents": 60
  },
  "jobId": "6a0f...",
  "videoId": "6a0f...",
  "meta": {
    "request_id": "8f0c...",
    "agent_run_id": "agent-run-2026-10-06-001",
    "key_mode": "live",
    "retryable": false,
    "estimated_completion_seconds": 180
  }
}

Treat data.job_id, data.video_id, data.status and data.poll_url as the stable contract; every Generate endpoint returns them the same way (see Jobs). The job id is also in the X-Job-Id header. The top-level jobId/videoId are deprecated aliases. Other fields are informational and may change.

Dry run (free)

curl -X POST https://api.reelsbuilder.ai/api/v1/generate-and-post   -H "Authorization: Bearer $REELSBUILDER_API_KEY"   -H "Content-Type: application/json"   -d '{ "prompt": "How Acme halves onboarding time", "duration_sec": 30, "dry_run": true }'

# -> 200
{
  "success": true,
  "data": {
    "dry_run": true,
    "valid": true,
    "mode": "stock",
    "normalized_request": { "mode": "personalized", "options": { "clipType": "business", "includeCaptions": true, "includeMusic": true, "duration": 30, "aspectRatio": "9:16", ... } },
    "price": { "usd_cents": 60, "display": "$0.60", "breakdown": [{ "item": "generate_and_post", "usd_cents": 60 }] },
    "estimated_duration_sec": 30,
    "estimated_render_seconds": { "min": 90, "max": 300 },
    "warnings": [],
    "charged": false
  },
  "meta": { "request_id": "…" }
}

A dry run runs the same validation as a real call, so invalid input gets the same 400 INPUT_INVALID. Nothing is queued or charged. normalized_request shows how your fields were resolved (for example the inferred clipType).

Footage controls

The API supports footage_keywords and exclude_keywords. Check the deployed generate_and_post schema at GET /api/v1/tools before using them; both were advertised on October 7. Each accepts up to 32 nonempty strings, at most 100 characters each, trimmed, lowercased and deduplicated.

footage_keywords guides footage search without changing the narration. exclude_keywords rejects matching clip metadata before ranking and library fallbacks; it is a literal metadata filter with normalized singular/plural matching, not a guarantee about everything visible in a clip. Plurals are matched (robots excludes robot), but words that only look plural are kept whole (news does not exclude new). Review the selected footage. These controls preserve caller-supplied assets. Send the end customer's niche and keywords explicitly rather than relying on the API account's brand. Preview first; review actual footage before publishing.

Request fields

One of prompt, topic or script is required; otherwise the request fails with 400 INPUT_INVALID. Field names are the canonical ones; the listed aliases still work, and a dry run's warnings tells you when you used one.

Customize the render

Every setting has a default, so you only send what you want to change. Request values beat brand values: caption_style > brand colors > your account brand > defaults. Invalid values return 400 INPUT_INVALID before anything is charged.

{
  "prompt": "How Acme cuts onboarding time in half for IT teams.",
  "clip_type": "tech",
  "caption_style": {
    "preset": "highlight",
    "highlight_color": "#00C2FF",
    "position": "center",
    "font_size": "medium"
  },
  "music": { "volume": 0.15 },
  "voice_gender": "female",
  "voice_speed": 1.1,
  "language": "en",
  "cta": { "text": "Book a demo at acme.com" }
}

Brand per video

By default every video uses the brand saved on your ReelsBuilder account. If you render for many end customers, send a brand object with each request instead. The script mentions the brand name and website, captions use the colors, and the logo appears as a watermark.

"brand": {
  "name": "Acme Cloud",
  "website_url": "https://acme.com",
  "logo_url": "https://acme.com/logo.png",
  "primary_color": "#0A66C2",
  "industry": "Cloud security",
  "tone": "professional"
}

Combine it with "include_branding": false on a paid plan so only your customer's logo appears. Host logos on a public https URL (IP addresses and internal hosts are rejected); a square or wide PNG with a transparent background works best.

Polling

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

A live job looks like this (fields abbreviated):

{
  "success": true,
  "data": {
    "job": {
      "id": "6a0f...",
      "status": "completed",
      "progress": [{ "stage": "...", "message": "...", "percent": 100 }],
      "artifacts": {
        "videoId": "6a0f...",
        "videoUrl": "https://...mp4",
        "videoUrls": ["https://...mp4"],
        "thumbnailUrl": "https://...jpg"
      },
      "error": null
    }
  }
}

Keep polling while status is queued, leased, running or uploading. Stop on completed, failed, cancelled or dead_lettered. On failure, read data.job.error (code, message, retryable) before retrying. Polling is free and counts toward the 60 requests/minute read limit; every 10–15 seconds is plenty.

Sandbox keys (rb_test_) return a different, simplified poll shape: data.status and data.video_url at the top level, with no data.job object. Handle both if you test in sandbox.

Cancel a job

curl -X POST https://api.reelsbuilder.ai/api/v1/jobs/6a0f.../cancel \
  -H "Authorization: Bearer $REELSBUILDER_API_KEY"

Returns the updated job. A job that is already terminal returns 409 JOBS_CANCEL_NOT_ALLOWED. Cancelled jobs do not send a webhook.

Pricing and limits

• Live keys are charged $0.60 per accepted request from your prepaid balance. The charge appears in the X-Api-Credits-Cost-Usd-Cents response header.
• If the job fails, the charge is refunded.
• Insufficient balance returns 402 INSUFFICIENT_API_CREDITS with cost_usd_cents, balance_usd_cents and topup_min_usd_cents. Top up before retrying.
• At most 5 heavy render jobs can be active per account. The sixth returns 429 RENDER_CONCURRENCY_LIMIT_EXCEEDED; it is not queued.
• Sandbox keys return a fixture with sandbox: true, create no job and charge nothing.

Agent pattern (TypeScript)

const apiKey = process.env.REELSBUILDER_API_KEY;
if (!apiKey) throw new Error("Set REELSBUILDER_API_KEY first");
const runId = crypto.randomUUID();
const apiBase = "https://api.reelsbuilder.ai";

async function readResponse(response: Response) {
  const body = await response.json();
  if (!response.ok || !body.success) {
    throw new Error(body.error?.message ?? body.error?.code ?? `HTTP ${response.status}`);
  }
  return body.data;
}

const accepted = await readResponse(await fetch(`${apiBase}/api/v1/generate-and-post`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${apiKey}`,
    "Content-Type": "application/json",
    "Idempotency-Key": runId,
  },
  body: JSON.stringify({
    prompt: "A short update about Acme's new onboarding flow.",
    content_purpose: "product_demo",
    agent_run_id: runId,
  }),
  signal: AbortSignal.timeout(30000),
}));
if (!accepted?.job_id) throw new Error("Response is missing job_id");

let videoUrl: string | undefined;
for (let attempt = 0; attempt < 80; attempt++) {
  const data = await readResponse(await fetch(`${apiBase}/api/v1/jobs/${accepted.job_id}`, {
    headers: { Authorization: `Bearer ${apiKey}` },
    signal: AbortSignal.timeout(30000),
  }));
  // Live uses data.job; sandbox fixtures expose status and video_url on data.
  const job = data?.job ?? data;
  if (!job?.status) throw new Error("Response is missing job status");
  if (job.status === "completed") {
    videoUrl = job.artifacts?.videoUrl ?? job.video_url;
    if (!videoUrl) throw new Error("Completed job has no video URL");
    break;
  }
  if (["failed", "cancelled", "dead_lettered"].includes(job.status)) {
    throw new Error(job.error?.message ?? `Job ${job.status}`);
  }
  if (!["queued", "leased", "running", "uploading"].includes(job.status)) {
    throw new Error(`Unexpected job status: ${job.status}`);
  }
  await new Promise((resolve) => setTimeout(resolve, 15000));
}
if (!videoUrl) throw new Error("Polling limit reached; resume polling the same job_id");
// Sandbox URLs are fixtures, not rendered assets.
// Your pipeline can publish a completed live video with POST /api/v1/post.

See also

• Autoblog Video API
• Webhooks — the optional terminal callback
• Multi-Platform Post API — publish the finished video
• Idempotency
• Rate Limits
• Errors