Create a multi-scene 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.
At most 3 stories per user can be in progress at once. Another request returns 429 rate_limit_exceeded, with a Retry-After header, until one of them is completed or failed.
When the service is busy, a story can wait up to 30 minutes in “processing”, with scenes_completed 0, before it starts. If no generation slot frees up in that time, the job fails with error code service_unavailable and nothing is charged.
A client or CLI timeout does not stop the story: it is still running and will be charged when it completes. Check it with GET /v1/jobs/{id} or depicta story status <id>. Never resubmit the same story after a timeout: the second one runs and is charged too.
Authorizations
Section titled “ Authorizations ”Request Body
Section titled “ Request Body ”object
Aspect ratio for every scene image: one of the model’s aspect_ratios or fixed_sizes from GET /v1/models, up to 16 characters. Another value returns 422 validation_error before anything is charged.
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. A label: 1-60 characters of letters (any script), digits, spaces and the punctuation - _ ’ ’ . , · ・ ׳ ་, with no space at either end. Classified with the rest of the story.
Optional HTTPS URL of a reference image for visual consistency. Must be an accessible signed URL.
Not supported yet: a request that sets any state is refused with 422 validation_error before anything is charged. Describe a change of look in the scene prompt. Null or an empty object counts as not set.
object
object
The character’s look in this state.
HTTPS URL of a reference image for this state.
Size tier for all scene images, one of the model’s image_sizes from GET /v1/models (e.g. 1K, 2K), up to 8 characters. Another value returns 422 validation_error before anything is charged.
Named locations, up to 10. Before the scenes, each location’s image is generated from its description (one more image generation, which is charged) or, with reference_url, fetched. The images stay in the model’s context for every scene and are listed in the result. No scene is tied to a location (scenes[].location is not supported yet): name the place in the scene prompt.
object
Visual description of the location.
Location name. It labels the location’s image in the result (locations[].name); a scene cannot reference it, as scenes[].location is not supported yet, so name the place in the scene prompt. A label: 1-60 characters of letters (any script), digits, spaces and the punctuation - _ ’ ’ . , · ・ ׳ ་, with no space at either end. Classified with the rest of the story.
Optional HTTPS URL of a location reference image.
Model identifier or alias from GET /v1/models; must support multi-turn generation (supports_multiturn). Optional: when omitted, your default_model preference is used if it supports multi-turn, otherwise the recommended story model (gemini).
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
Not supported yet: a request that sets it is refused with 422 validation_error before anything is charged; every scene uses the story’s aspect_ratio. Null, empty or spaces only counts as not set.
Not supported yet: a request that sets any entry is refused with 422 validation_error before anything is charged. Every character is in every scene’s context; name the characters who appear in the scene prompt. Null or an empty array counts as not set.
object
Character name.
State key.
Not supported yet: a request that sets it is refused with 422 validation_error before anything is charged. Describe the place in the scene prompt. Null, empty or spaces only counts as not set.
Scene-specific image generation prompt.
Physical setting/environment for the story.
Classification strictness mode override for this request: ‘normal’ (brand-safe) or ‘liberal’. Liberal: For erotic and provocative art of fictional adults, and dark themes. Explicit sexual content is never allowed, and nothing sexual of real people or of anyone who could be a minor. Omit to use your account default.
Visual style applied to all scenes, up to 200 characters. Classified with the rest of the story.
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