POST
/api/v1/image/storyboard-batch
Render a small photo batch inline (synchronous, unsupervised)
Renders frames and returns them in the response. There is no job id and no QA: use this only for batches small enough to finish inside one request. continuityMode="chain" (the default) renders one frame at a time, conditioning each frame on the previous frame's output, so its ceiling is much lower than the parallel modes. Requests above the ceiling are rejected with 413 BEFORE any credit is charged and carry the durable path in durable_alternative. For genuine mass generation, or for anything that must meet a quality standard, use the supervised path: storyboard-images/plan then storyboard-images/generate. Feature-flagged (STORYBOARD_PHOTO_BATCH_ENABLED).
Responses
| Status | Meaning |
| 200 |
status=completed when every frame rendered, status=partial when some failed. Failed frames are refunded. |
| 402 |
Insufficient credits; nothing was dispatched |
| 403 |
Insufficient scope or forbidden project |
| 413 |
Batch cannot finish synchronously. no_credits_spent=true; durable_alternative names the supervised endpoints to use instead. |
| 429 |
Rate limit exceeded; retry_after_seconds returned |
| 503 |
Storyboard photo batch not enabled |
POST
/api/v1/projects/{projectId}/film-intelligence/storyboard-images/plan
Compile the authoritative work plan for a supervised image batch
Returns the single authority for what will be generated, what it will cost, and what is missing: every required frame, the reference plates it depends on, the resolved provider, the credit ceiling, and any blocker that would stop execution. Spends no credits. Call this before generate to see the full cost and the blocker list.
Parameters
| Name | In | | Description |
| projectId |
path |
required |
|
Responses
| Status | Meaning |
| 200 |
Work plan with per-frame requirements, credit ceiling and blockers |
| 403 |
Forbidden project |
| 404 |
Project or storyboard not found |
| 409 |
Script revision conflict: the storyboard is stale against its source revision |
POST
/api/v1/projects/{projectId}/film-intelligence/storyboard-images/generate
Start a durable, supervised image batch
The supervised mass-generation entry point, and the one to build on. Persists a job before dispatching, so the batch survives client disconnects and process restarts. Execution is lease-exclusive: a duplicate delivery of the same task cannot make one job run twice. After rendering, every frame is scored against its requirements and failures enter a bounded repair loop with a per-requirement attempt limit, a per-shot credit ceiling and an escalation ladder that ends in human review rather than unbounded retries. Requires expectedExecutionManifestArtifactHash: call plan first and copy executionManifestArtifact.artifactHash from its response. Without it this returns 400 storyboard_image_execution_manifest_required — the hash pins execution to the exact plan that was priced, so a stale plan cannot be executed silently. Returns 202 with a job to poll (job.id, then GET film-intelligence/jobs/{jobId}) — unless every selected requirement was already satisfied by a prior call, in which case it returns 200 with accepted=false and no job: check accepted before assuming a job started.
Parameters
| Name | In | | Description |
| projectId |
path |
required |
|
| Idempotency-Key |
header |
optional |
Recommended. Job identity is content-addressed, so a replayed request returns the existing job instead of starting a second one. |
Responses
| Status | Meaning |
| 200 |
Idempotent no-op: every selected requirement was already satisfied by a prior call. accepted=false, no job, nothing charged. |
| 202 |
Job persisted and enqueued. The polling handle is job.id (nested), not a top-level jobId. |
| 402 |
Insufficient credits for the plan ceiling; nothing was dispatched |
| 403 |
Forbidden project |
| 404 |
Project or storyboard not found |
| 409 |
Script revision conflict, or the storyboard already has an active job |
| 422 |
Plan has blockers that must be resolved before generation |
GET
/api/v1/projects/{projectId}/film-intelligence/jobs/{jobId}
Poll a durable generation job
Authoritative job state. status is queued, running, completed, partially_completed or failed. completed means every required frame was rendered AND passed review; partially_completed reports which requirements still failed and whether the batch is resumable. Safe to poll from any client, including one that did not start the job.
Parameters
| Name | In | | Description |
| projectId |
path |
required |
|
| jobId |
path |
required |
|
Responses
| Status | Meaning |
| 200 |
Job state, per-requirement results and QA evidence |
| 403 |
Forbidden project |
| 404 |
Job not found |
GET
/api/v1/projects/{projectId}/film-intelligence/photo-sequences/{planId}
Read a photo sequence plan and its current lifecycle
The plan, its frames and where it currently stands. Spends nothing. Use it to price a repair before authorizing one, and to see the lifecycle without mutating anything.
Parameters
| Name | In | | Description |
| projectId |
path |
required |
|
| planId |
path |
required |
|
Responses
| Status | Meaning |
| 200 |
Plan, frames and lifecycle |
| 403 |
Forbidden project |
| 404 |
Plan not found |
POST
/api/v1/projects/{projectId}/film-intelligence/photo-sequences/{planId}/review
Record a human accept/repair decision per frame
This is the human authority step, NOT the automatic scorer. Automatic scoring runs inside the generation job, and its verdicts and evidence are read from film-intelligence/jobs/{jobId} — not here. This endpoint records what a person decided about each frame, so it requires a decisions array (frameIndex, accept|repair, a note, optional prompt additions) and an existing QA report for the plan. Calling it without decisions returns 400, and with no prior QA report returns 409.
Parameters
| Name | In | | Description |
| projectId |
path |
required |
|
| planId |
path |
required |
|
Responses
| Status | Meaning |
| 201 |
Decisions recorded; the plan lifecycle advances to reflect them |
| 400 |
No decisions supplied, or a decision failed validation |
| 403 |
Forbidden project |
| 404 |
Plan not found |
| 409 |
No QA report exists yet for this plan; generate and let scoring run first |
POST
/api/v1/projects/{projectId}/film-intelligence/photo-sequences/{planId}/repair
Repair only the frames that failed review
Regenerates the failing requirements and nothing else, so accepted frames are frozen rather than re-rolled. Bounded by attempts per requirement, requests per shot and a credit ceiling; each escalation tightens constraints before falling back to a frozen prompt, and exhausting the ladder returns human_review instead of spending more.
Parameters
| Name | In | | Description |
| projectId |
path |
required |
|
| planId |
path |
required |
|
Responses
| Status | Meaning |
| 202 |
Repair job accepted; poll for the new verdicts |
| 402 |
Repair would exceed the authorized credit ceiling |
| 403 |
Forbidden project |
| 404 |
Plan not found |
| 409 |
Repair budget or attempt ladder exhausted; human review required |
GET
/api/v1/production/capabilities
What this deployment can actually execute right now
Runtime capability truth, not documentation. Each capability reports configured plus the honest limitations that apply, so a client (or an agent) can check whether a workload is executable before spending anything. Unconfigured providers are reported as unavailable rather than failing at dispatch.
Responses
| Status | Meaning |
| 200 |
Capability list with configured flags and limitations |