Batch Planner API

Getting a key

The API is included with the Pro and Studio plans. Create a key on your Account page. A key is shown once, so store it somewhere safe. You can have up to 5 keys and revoke any of them at any time.

Send it on every request as Authorization: Bearer <key>. Keep it on your server; never put it in a web page or app people download.

Make a batch

POST /api/v1/batches generates a batch and returns it when it's ready, usually within a minute. Only niche is required.

curl https://batchideo.com/api/v1/batches \
  -H "Authorization: Bearer $BATCHIDEO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "niche": "personal finance for students",
    "audience": "college freshmen",
    "tone": "Practical",
    "length": "45–60 seconds"
  }'

• tone: Calm Authority, Motivational, Practical (default), Controversial or Storytelling.
• length: 30–45 seconds, 45–60 seconds (default) or 2–4 minutes. A plain hyphen works too.
• model: optional model id; your plan's default otherwise.
• channelProfileId: optional saved channel profile, so the batch matches that channel's voice.

The response (status 201):

{
  "id": "gen_…",
  "niche": "personal finance for students",
  "audience": "college freshmen",
  "tone": "Practical",
  "length": "45–60 seconds",
  "model": "…",
  "createdAt": "2026-10-18T12:00:00.000Z",
  "creditsSpent": 3,
  "ideas": [
    {
      "number": 1,
      "title": "…",
      "hook": "…",
      "altHooks": ["…", "…"],
      "script": "…",
      "thumbnailPrompt": "…",
      "whyItWorks": "…"
    }
    // 25 ideas in all
  ]
}

Each batch is also saved to your account, and it uses your channel's memory the same way the app does: recent titles are avoided and your best-performing hooks steer the new ones.

Other endpoints

• GET /api/v1/batches/{id} returns a batch you made before.
• GET /api/v1/me returns your plan and the credits you have left.

Credits and limits

A batch costs the same credits as in the app (3 with the standard model), from your monthly grant first and then packs. Failed batches are never charged. See how credits work.

Each key can make 20 requests a minute and 300 an hour.

Errors

Errors return { "error": { "code", "message" } }:

• 400 invalid_request: the body is missing or wrong.
• 401 unauthorized: the key is missing, wrong or revoked.
• 402 insufficient_credits: not enough credits for the batch.
• 403 plan_required: the account isn't on Pro or Studio.
• 404 not_found: no batch with that id on this account.
• 429 rate_limited: too many requests; see Retry-After.
• 503 unavailable: generation is paused; try again later.