Create a multi-scene story
POST /v1/generate/story
Generate a multi-scene visual story. This runs asynchronously — the response is HTTP 202 with a job ID, not the finished images.
Define characters (with appearance descriptions and optional reference images), scenes (with per-scene prompts), and optionally a global style and setting. The model generates a reference portrait for each character first, then produces each scene maintaining visual consistency.
Poll GET /v1/jobs/{id} for progress. The scenes_completed field tells you how many scenes are done. When status is “completed”, the result contains signed URLs for all scene images.
The model must support multi-turn generation — check supports_multiturn in GET /v1/models. If it doesn’t, you’ll get a 422 with error code model_not_capable.
Authorizations
Section titled “Authorizations ”Request Body
Section titled “Request Body ”object
Desired aspect ratio for all scene images (default). Scenes can override.
1 to 10 named characters appearing in the story.
object
Detailed physical description used to generate a consistent character portrait.
Character name used consistently across all story scenes.
Optional HTTPS URL of a reference image for visual consistency. Must be an accessible signed URL.
Optional appearance variants (costumes, disguises). Max 5 per character.
object
object
Description of the character’s appearance in this state.
Optional HTTPS URL of a reference image for this state.
Desired image size for all scene images.
Named locations with optional reference images. Scenes reference by name.
object
Visual description of the location.
Location name, referenced by scenes.
Optional HTTPS URL of a location reference image.
Model identifier from the /v1/models endpoint. Must support multi-turn generation (check supports_multiturn in /v1/models).
Optional overall story prompt providing context for all scenes.
When true, scene prompts are sent as-is without template wrapping. Default false.
Shared reference images for general visual anchoring. Max 5.
object
What this image shows. The model uses this to understand what to reference.
HTTPS URL of the reference image. Must be publicly accessible.
2 to 10 scenes describing the story sequence.
object
Per-scene aspect ratio override.
Which characters appear in this scene and in which state.
object
Character name. Must match a character from the top-level characters array.
Optional state key from the character’s states map. Omit for base appearance.
Location name from the locations array for this scene.
Scene-specific image generation prompt.
Physical setting/environment for the story.
Classification strictness mode override for this request. ‘normal’ (brand-safe) or ‘liberal’ (legal limits only). Omit to use your account default.
Visual style applied to all scenes.
Responses
Section titled “ Responses ”Accepted
object
Unique async job identifier. Use this to poll for status.
Absolute URL to poll for job status (GET /v1/jobs/{job_id}).
Always ‘pending’ for a freshly accepted job.
Bad Request
object
Unauthorized
object
Payment Required
object
Forbidden
object
Not Found
object
Conflict
object
Unprocessable Entity
object
Too Many Requests
object
Unavailable For Legal Reasons
object
Internal Server Error
object
Bad Gateway
object
Service Unavailable