Plan, storyboard & scene regen

Three endpoints wrap the render with an iteration loop: draft a plan from an idea, preview draft frames before paying, and fix a single scene after the render — billed only as the difference.

POST /v1/plan — idea → editable plan

Free (rate-limited). Turns a free-text idea into a structured plan you can edit and submit via POST /v1/jobs.

bash

curl -X POST https://api.clipfoundry.tech/v1/plan \
  -H "Authorization: Bearer $CLIPFOUNDRY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"idea": "Why octopuses have three hearts"}'

Returns { data: { title, script, style, voiceId, format, language, durationMs, musicMood, estimate } }. Invalid model output is retried once and then rejected with 422 — a plan never reaches the pipeline off the rails. Rate limits: 10/min per user, 30/min per IP.

POST /v1/storyboard — draft frames before you pay

Free (rate-limited). Renders 2–4 LOW-quality frames of your script so you can see roughly what the paid render will look like. Nothing is stored — frames come back as data: URLs; nothing is billed.

bash

curl -X POST https://api.clipfoundry.tech/v1/storyboard \
  -H "Authorization: Bearer $CLIPFOUNDRY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"script": "Your narration text…", "style": "cinematic", "count": 3}'

Returns { data: { frames: [{ prompt, imageDataUrl }] } }. Draft quality is deliberate — the final render is sharper, animated and beat-synced. Rate limits: 5/min and 20/day per user.

POST /v1/jobs/:id/regen — fix one scene, pay the difference

Regenerates a single scene's image on a finished job (optionally with a replacement prompt) and re-renders the video. Everything else — narration, captions, music, the other scenes — is reused from cache.

bash

curl -X POST https://api.clipfoundry.tech/v1/jobs/$JOB_ID/regen \
  -H "Authorization: Bearer $CLIPFOUNDRY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"sceneIndex": 2, "prompt": "a red lighthouse at dusk, storm clouds"}'

Returns the job back in pending; poll GET /v1/jobs/:id or subscribe to SSE as usual. Billing is the delta: you're charged only the difference between the job's new computed total and what it already charged — typically a few hundred tokens (one image + the re-render).

Errors: 409 when the job isn't finished, 422 for an out-of-range sceneIndex (the message carries the scene count) or a scene that plays stock footage (regenerating its hidden still would change nothing), 402 when the quoted delta exceeds your available tokens.