Generate an image from a text prompt
Generate an image from a text prompt. This is the general-purpose endpoint — use it for photos, illustrations, art, or anything that isn’t specifically an icon/graphic, diagram, or story.
The prompt goes through content moderation first. If it passes, the image is generated using the specified model, watermarked with C2PA metadata (EU AI Act compliance), and uploaded to temporary storage.
The response includes signed URLs in multiple formats (PNG, JPEG, WebP) valid for 1 hour — download what you need before they expire. You also get the cost charged and your remaining balance.
Use GET /v1/models to see which models are available and what they cost.
Recovery: Every generation is tracked as a job. The response includes an X-Depicta-Job-Id header with the job UUID. If the response is lost (network error, timeout), use GET /v1/jobs to find your recent generations — the result will be there once the generation completes.
Authorizations
Section titled “ Authorizations ”Request Body
Section titled “ Request Body ”object
Desired aspect ratio of the output 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.
Size tier, one of the model’s image_sizes from GET /v1/models (e.g. 1K, 2K, 4K), up to 8 characters. Omit for the model’s default size. Another value returns 422 validation_error before anything is charged.
Model identifier or alias from GET /v1/models. Optional: when omitted, your default_model preference is used if it supports the operation, otherwise the recommended model for the operation (create: mai-fast; graphic and diagram: mai; edit and combine: gemini). The response’s model field names the model used.
Text prompt describing the image to generate.
Optional reference images for visual style/context 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.
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.
Responses
Section titled “ Responses ”OK
object
Always true. Indicates AI-generated content per EU AI Act Art. 50.
Remaining balance after this generation, in credits (EUR, excluding VAT).
Character reference images produced during story generation. Omitted for non-story operations.
object
ISO 8601 expiry time of the reference URL. Null for client-provided refs.
Character name as provided in the story request.
Signed URL of the character reference image. Expires in 1 hour.
Actual cost charged, in credits (EUR, excluding VAT).
Per-format variants (png, jpeg, webp) with individual URLs and hashes. Omitted when not available.
object
object
ISO 8601 expiry time of the signed URL.
Image format identifier.
SHA-256 hash of the image in this format for provenance verification.
File size in bytes of the image in this format.
Signed URL for this format variant. Expires in 1 hour.
Unique generation identifier.
SHA-256 hash of the generated image (PNG) for provenance verification.
SHA-256 hashes for multi-image operations (stories). Omitted for single-image operations.
Signed URL of the generated image (PNG). Expires in 1 hour. Omitted for story operations.
Signed URLs for multi-image operations (e.g. combine). Each URL expires in 1 hour.
Location reference images used during story generation (auto-generated or client-provided). Reusable for standalone scene regeneration. Omitted for non-story operations.
object
ISO 8601 expiry time of the reference URL. Null for client-provided refs.
Location name as provided in the story request.
Signed URL of the location reference image. Expires in 1 hour.
Resolved model identifier used for this generation.
Scene images for story operations. Each entry includes image URL, title, and expiry. Omitted otherwise.
object
ISO 8601 expiry time of the signed URL.
Per-format variants (png, jpeg, webp) with individual URLs and hashes. Omitted when not available.
object
object
ISO 8601 expiry time of the signed URL.
Image format identifier.
SHA-256 hash of the image in this format for provenance verification.
File size in bytes of the image in this format.
Signed URL for this format variant. Expires in 1 hour.
SHA-256 hash of the scene image (PNG) for provenance verification.
Signed URL of the scene image (PNG). Expires in 1 hour.
1-based scene index within the story.
Short generated title for this scene.
Generated story title. Present only for story operations.
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