Agent Generate API

What this endpoint does

POST /api/v1/generate-and-post is intentionally narrow: it queues a paid ReelsBuilder video render and returns an asset contract that downstream systems can use for blog embeds, CMS population, and social autoposting.

ReelsBuilder does not wire your external project for you. Promotion.GG, Codex, a custom agent, or an AgenticFlow should call this endpoint, poll the returned job, then decide how to publish the completed video.

Endpoint

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

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": "Create a 30 second video about Promotion.GG automated audience growth proof.",
    "brand_id": "promotion-gg",
    "platforms": ["youtube_shorts", "tiktok", "instagram"],
    "duration_target_sec": 30,
    "aspect_ratio": "9:16",
    "content_style": "professional",
    "agent_run_id": "agent-run-2026-05-20-001"
  }'

Accepted response

{
  "success": true,
  "data": {
    "job_id": "6a0f...",
    "generation_id": "6a0f...",
    "video_id": "6a0f...",
    "status": "queued",
    "poll_url": "/api/v1/jobs/6a0f...",
    "ws_url": "wss://api.reelsbuilder.ai/ws/...",
    "distribution": {
      "mode": "external_agent_distribution",
      "requested_platforms": ["youtube_shorts", "tiktok", "instagram"],
      "schedule_at": null,
      "webhook_url": null,
      "note": "ReelsBuilder queues the paid render and returns the completed asset. Your Codex/agent/AgenticFlow handles CMS, blog, and social publishing."
    },
    "output_contract": {
      "video_url": "available after completion on GET /api/v1/jobs/{job_id}.data.job.artifacts.videoUrl",
      "captions": "available when the selected render path produces captions; consumers should tolerate an empty array",
      "blog_embed": {
        "type": "html_video_embed",
        "source": "derive from completed video_url and captions"
      },
      "social_metadata": {
        "title": "Promotion.GG automated audience growth proof",
        "description": "Create a 30 second video about Promotion.GG automated audience growth proof.",
        "platforms": ["youtube_shorts", "tiktok", "instagram"]
      }
    }
  },
  "meta": {
    "agent_run_id": "agent-run-2026-05-20-001",
    "key_mode": "live",
    "retryable": false,
    "estimated_completion_seconds": 180
  }
}

Polling

Poll the returned job_id until the job reaches completed, failed, cancelled, or dead_lettered.

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

Recommended interval: 5 seconds for the first minute, then 15 seconds. Polling costs 0 credits but is rate-limited per API key.

Request fields

Pay-per-usage behavior

• Live keys start real paid renders and consume credits according to the selected render path.
• Sandbox keys start with rb_test_ and return fixtures without charging credits or creating production jobs.
• Every paid generation request requires Idempotency-Key so agent retries do not double-charge.
• Each key is limited to 5 active heavy render jobs by default.
• Metadata and polling requests are limited to 60 requests per minute per key by default.

Codex and AgenticFlows pattern

const apiKey = process.env.REELSBUILDER_API_KEY!;
const runId = crypto.randomUUID();

const start = await fetch("https://api.reelsbuilder.ai/api/v1/generate-and-post", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${apiKey}`,
    "Content-Type": "application/json",
    "Idempotency-Key": runId,
  },
  body: JSON.stringify({
    prompt: "Create a short update about our new customer acquisition proof.",
    brand_id: "promotion-gg",
    platforms: ["youtube_shorts", "tiktok", "instagram"],
    agent_run_id: runId,
  }),
});

const accepted = await start.json();
const jobId = accepted.data.job_id;

let job;
for (;;) {
  const status = await fetch(`https://api.reelsbuilder.ai/api/v1/jobs/${jobId}`, {
    headers: { Authorization: `Bearer ${apiKey}` },
  });
  job = await status.json();
  if (["completed", "failed", "cancelled", "dead_lettered"].includes(job.data.job.status)) break;
  await new Promise((resolve) => setTimeout(resolve, 15000));
}

const videoUrl = job.data.job.artifacts.videoUrl;
// Your agent decides the next step: blog embed, CMS draft, TikTok upload, YouTube Shorts upload, etc.

Downstream contracts

Blog or CMS embed

{
  "component": "video_embed",
  "video_url": "<completed videoUrl>",
  "captions": [],
  "title": "<social_metadata.title>",
  "source": "reelsbuilder"
}

Social autopost packet

{
  "video_url": "<completed videoUrl>",
  "title": "<social_metadata.title>",
  "description": "<social_metadata.description>",
  "platforms": ["youtube_shorts", "tiktok", "instagram"],
  "binary_pointer": "<completed videoUrl>",
  "agent_run_id": "agent-run-2026-05-20-001"
}

See also

• Autoblog Video API
• Authentication
• Idempotency
• Rate Limits
• Errors
• Webhooks