Generate & Post API

Why this endpoint exists

Most ReelsBuilder API customers don't actually want video files — they want published posts that drove engagement. This endpoint collapses what would otherwise be 6+ API calls (generate video → wait → fetch URL → call TikTok API → call Instagram API → call YouTube API → reconcile status) into a single POST with one webhook on completion.

Endpoint

POST /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 '{
    "topic": "OpenAI realtime voice API launch",
    "brand_id": "brn_01HKZ...",
    "platforms": ["tiktok", "instagram", "youtube_shorts"],
    "video_style": "news_broadcast",
    "duration_target_sec": 30,
    "webhook_url": "https://your-app.example.com/webhooks/rb"
  }'

Initial response (202 Accepted)

{
  "success": true,
  "data": {
    "job_id": "gpj_01HKZ...",
    "status": "queued",
    "estimated_completion_sec": 180,
    "platforms": [
      { "platform": "tiktok", "status": "queued" },
      { "platform": "instagram", "status": "queued" },
      { "platform": "youtube_shorts", "status": "queued" }
    ]
  },
  "meta": { "request_id": "req_...", "credits_used": 18, "credits_remaining": 982 }
}

Completion webhook

ReelsBuilder POSTs the final result to webhook_url when all platforms have completed (success or failure). Verify signature using the pattern in Webhooks.

POST https://your-app.example.com/webhooks/rb
X-RB-Event-Type: job.completed
X-RB-Event-Id: evt_...
X-RB-Signature: t=1715797200,v1=...

{
  "event_id": "evt_...",
  "event_type": "job.completed",
  "data": {
    "job_id": "gpj_01HKZ...",
    "status": "partial_success",
    "video_url": "https://cdn.reelsbuilder.ai/v/...",
    "duration_sec": 28.4,
    "platforms": [
      {
        "platform": "tiktok",
        "status": "posted",
        "external_id": "7234...",
        "external_url": "https://tiktok.com/@.../video/7234...",
        "posted_at": "2026-05-15T20:03:14.000Z"
      },
      {
        "platform": "instagram",
        "status": "posted",
        "external_id": "...",
        "external_url": "https://instagram.com/reel/...",
        "posted_at": "2026-05-15T20:03:42.000Z"
      },
      {
        "platform": "youtube_shorts",
        "status": "failed",
        "error_code": "PLATFORM_OAUTH_EXPIRED",
        "error_message": "YouTube access token expired. Reconnect at /dashboard/v5/social-accounts.",
        "failed_at": "2026-05-15T20:01:08.000Z"
      }
    ],
    "credits_used": 18,
    "credits_refunded": 0
  }
}

Parameters

Credit semantics

A single credit deduction at request time, with refunds only on video-generation failure:

• Video gen succeeds, all platforms post: No refund. Full credits charged at request time.
• Video gen succeeds, some platforms fail: No refund. The video was produced — that's the cost. Platform-level failures don't trigger refunds because re-posting the same video doesn't cost us anything (you can manually re-post from the dashboard).
• Video gen fails: Full refund. All credits returned to your balance. credits_refunded in the webhook payload tells you exactly how much.
• You cancel before the video starts: Full refund (use DELETE /api/v1/jobs/{job_id}).

Job lifecycle

1. queued — Accepted, waiting for a worker.
2. generating — Video gen in progress.
3. posting — Video uploaded, platform fan-out in flight.
4. completed — All platforms posted successfully.
5. partial_success — Video posted, but at least one platform failed.
6. failed — Video gen failed. Credits refunded.
7. cancelled — User cancelled before completion.

Polling alternative

If you can't accept inbound webhooks, poll GET /api/v1/jobs/{job_id}:

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

Recommended interval: 5s for the first minute, 15s after. Cost: 0 credits. Maximum poll lifetime: 1 hour.

Examples

TypeScript — trend → hook → generate & post chain

const apiKey = process.env.REELSBUILDER_API_KEY!;
const auth = { Authorization: `Bearer ${apiKey}` };

// 1. Pick a trend
const trendsRes = await fetch(
  "https://api.reelsbuilder.ai/api/v1/trends/radar?geo=US&category=tech&limit=1&min_virality=0.85",
  { headers: auth },
);
const trend = (await trendsRes.json()).data.trends[0];

// 2. Generate ranked hooks
const hooksRes = await fetch("https://api.reelsbuilder.ai/api/v1/hooks/generate", {
  method: "POST",
  headers: { ...auth, "Content-Type": "application/json", "Idempotency-Key": crypto.randomUUID() },
  body: JSON.stringify({ topic: trend.topic, count: 5, platform: "tiktok" }),
});
const bestHook = (await hooksRes.json()).data.hooks[0];

// 3. Generate + post to TikTok and Instagram
const jobRes = await fetch("https://api.reelsbuilder.ai/api/v1/generate-and-post", {
  method: "POST",
  headers: { ...auth, "Content-Type": "application/json", "Idempotency-Key": crypto.randomUUID() },
  body: JSON.stringify({
    trend_id: trend.id,
    brand_id: process.env.BRAND_ID,
    platforms: ["tiktok", "instagram"],
    video_style: "news_broadcast",
    script_opener: bestHook.text,
    webhook_url: "https://your-app.example.com/webhooks/rb",
  }),
});
const { data: job } = await jobRes.json();
console.log(`Job ${job.job_id} queued. Expected ~${job.estimated_completion_sec}s.`);

Pricing

Base cost: 15 credits for the video, plus per-platform fees:

• TikTok: +1 credit
• Instagram Reels: +1 credit
• YouTube Shorts: +1 credit
• Facebook Reels: +1 credit
• X (Twitter): +1 credit

A typical 3-platform fan-out is 18 credits total. Branded videos with brand_id are the same cost as generic.

See also

• Webhooks — signature verification + retry policy
• Idempotency — safe retry semantics
• Viral Trends API — populate trend_id
• Brand DNA API — populate brand_id
• Multi-Platform Post API — post without generating