--- title: "Make an image or video with AI" description: "Generate an image or a short video into the site's media, paid in credits at a fixed price." canonical: "https://atelier201.com/docs/api/media/generate" updated: "2026-11-06" --- # Make an image or video with AI Requires `media:generate`, a permission of its own: a credential that can edit sites cannot spend credits unless it was given this one too. Spends the workspace's credits. 1. Call it with `estimate_only: true`. It costs nothing and answers `estimated_credits` (the exact price) and `balance`. 2. Call it again with `max_credits` set to that price. Without `max_credits` the call is refused. A price above it is refused with nothing charged: `invalid_parameter` on `max_credits`, with `details.reason` `price_above_max_credits`, `details.estimated_credits` and `details.max_credits`. The credits are charged when the generation starts. If it fails, they are given back. An image is usually done within `wait_seconds` (50 by default) and comes back with `status: succeeded` and its `media`. A video takes one to five minutes: the answer is `status: running` with an `id`; [get the generation](/docs/api/media/generation) until it finishes. The file lands in the site's media like an upload, with `credit` set to the model that made it. Never present a generated image as a photograph of the business, its products, its people or its premises. At most 10 generations a minute per workspace (`429 rate_limited` above that, with `details.retry_after_seconds`). Not enough credits: `402 insufficient_credits` with `details.needed` and `details.balance`. A model that is busy fails the generation with its credits given back: try again in a minute. ```http POST https://api.atelier201.com/v1/sites/{site_id}/media/generations ``` ## Authorizations - `Authorization` (bearer, in header, required) ## Path parameters - `site_id` (`string`, required): The site's id, or its slug (the address before .atelier201.page). ## Body `application/json`, required - `model` (`enum`, required, one of: `gpt-image, nano-banana, flux, p-image, wan, minimax, seedance, p-video`): GET /v1/media/models lists each model, what it is best at and its prices in credits. - `prompt` (`string`, required, length: `1–4000 chars`): What to show: subject, setting, light, framing, style. - `aspect_ratio` (`enum`, one of: `16:9, 1:1, 9:16, 4:3, 3:4, 3:2, 2:3`): Width to height. Each model accepts the ratios list_media_models gives; default its first (16:9 for most). - `quality` (`enum`, one of: `draft, standard, high`): Images: draft, standard (default) or high. - `duration` (`integer`, range: `1–10`): Videos: seconds. - `resolution` (`enum`, one of: `480p, 720p, 768p, 1080p, 2k`): Videos: default the model's (720p, or 768p for minimax and p-video). - `audio` (`boolean`): Videos: with sound (seedance only). - `filename` (`string`, length: `1–100 chars`): A name without extension. - `alt` (`string`, length: `≤ 300 chars`) - `estimate_only` (`boolean`): true: the exact price in credits and the balance. Free, nothing runs. - `max_credits` (`integer`, range: `≤ 9007199254740991`): Required to run: the most you agree to spend. Refused, and nothing charged, when the price is higher. Take it from an estimate_only call. - `wait_seconds` (`integer`, range: `0–55`): How long to wait for the result. Default 50 for an image, 0 for a video. ## Response **202**: Make an image or video with AI - `data` (`Record`, required) - `data.id` (`string`): The generation's id: GET it until status is succeeded or failed. - `data.status` (`enum`, one of: `running, succeeded, failed`) - `data.media` (`object | null`) - `data.media.path` (`string`, required) - `data.media.url_path` (`string`, required) - `data.media.mime` (`string`, required) - `data.media.size` (`integer`, required, range: `-9007199254740991–9007199254740991`) - `data.media.alt` (`string,null`, required) - `data.media.credit` (`string,null`, required): Who made it, where a licence asks for it: "Photo by Jane Doe on Pixabay", "Generated with Seedream 5 Lite (ByteDance)". Null for an upload. - `data.media.keep_original` (`boolean`, required): Stored exactly as uploaded, and never re-encoded by a build. Otherwise a picture over 200 KB is compressed when it arrives (2000 px at most, towards 150 KB, quality 75 or more, metadata removed). - `data.error` (`string,null`) - `data.credits` (`integer | null`): What it cost. - `data.credits_refunded` (`integer | null`): Given back after a failure. - `data.estimated_credits` (`integer`, range: `-9007199254740991–9007199254740991`): estimate_only: the exact price it would cost. - `data.balance` (`number`): estimate_only: the workspace's credits now. - `data.next_action` (`string,null`, required) - `request_id` (`string`, required) ```json { "data": { "id": "", "status": "running", "media": { "path": "", "url_path": "", "mime": "", "size": 123, "alt": null, "credit": null, "keep_original": true }, "error": null, "credits": 123, "credits_refunded": 123, "estimated_credits": 123, "balance": 123.45, "next_action": null }, "request_id": "" } ``` **400**: Possible codes: invalid_request, unknown_field, invalid_parameter, invalid_cursor - `error` (`object`, required) - `error.type` (`string`, required) - `error.code` (`string`, required) - `error.message` (`string`, required) - `error.param` (`string`) - `error.docs_url` (`string`, required) - `error.action_url` (`string`) - `error.details` (`Record`) - `request_id` (`string`, required) ```json { "error": { "type": "", "code": "", "message": "", "param": "", "docs_url": "", "action_url": "", "details": {} }, "request_id": "" } ``` **401**: Possible codes: authentication_required, invalid_api_key, api_key_expired, api_key_revoked - `error` (`object`, required) - `error.type` (`string`, required) - `error.code` (`string`, required) - `error.message` (`string`, required) - `error.param` (`string`) - `error.docs_url` (`string`, required) - `error.action_url` (`string`) - `error.details` (`Record`) - `request_id` (`string`, required) ```json { "error": { "type": "", "code": "", "message": "", "param": "", "docs_url": "", "action_url": "", "details": {} }, "request_id": "" } ``` **402**: Possible codes: insufficient_credits - `error` (`object`, required) - `error.type` (`string`, required) - `error.code` (`string`, required) - `error.message` (`string`, required) - `error.param` (`string`) - `error.docs_url` (`string`, required) - `error.action_url` (`string`) - `error.details` (`Record`) - `request_id` (`string`, required) ```json { "error": { "type": "", "code": "", "message": "", "param": "", "docs_url": "", "action_url": "", "details": {} }, "request_id": "" } ``` **403**: Possible codes: insufficient_scope, feature_not_available, admin_required - `error` (`object`, required) - `error.type` (`string`, required) - `error.code` (`string`, required) - `error.message` (`string`, required) - `error.param` (`string`) - `error.docs_url` (`string`, required) - `error.action_url` (`string`) - `error.details` (`Record`) - `request_id` (`string`, required) ```json { "error": { "type": "", "code": "", "message": "", "param": "", "docs_url": "", "action_url": "", "details": {} }, "request_id": "" } ``` **404**: Possible codes: resource_not_found - `error` (`object`, required) - `error.type` (`string`, required) - `error.code` (`string`, required) - `error.message` (`string`, required) - `error.param` (`string`) - `error.docs_url` (`string`, required) - `error.action_url` (`string`) - `error.details` (`Record`) - `request_id` (`string`, required) ```json { "error": { "type": "", "code": "", "message": "", "param": "", "docs_url": "", "action_url": "", "details": {} }, "request_id": "" } ``` **409**: Possible codes: conflict, result_not_ready, idempotency_key_reused - `error` (`object`, required) - `error.type` (`string`, required) - `error.code` (`string`, required) - `error.message` (`string`, required) - `error.param` (`string`) - `error.docs_url` (`string`, required) - `error.action_url` (`string`) - `error.details` (`Record`) - `request_id` (`string`, required) ```json { "error": { "type": "", "code": "", "message": "", "param": "", "docs_url": "", "action_url": "", "details": {} }, "request_id": "" } ``` **410**: Possible codes: result_expired - `error` (`object`, required) - `error.type` (`string`, required) - `error.code` (`string`, required) - `error.message` (`string`, required) - `error.param` (`string`) - `error.docs_url` (`string`, required) - `error.action_url` (`string`) - `error.details` (`Record`) - `request_id` (`string`, required) ```json { "error": { "type": "", "code": "", "message": "", "param": "", "docs_url": "", "action_url": "", "details": {} }, "request_id": "" } ``` **413**: Possible codes: request_too_large - `error` (`object`, required) - `error.type` (`string`, required) - `error.code` (`string`, required) - `error.message` (`string`, required) - `error.param` (`string`) - `error.docs_url` (`string`, required) - `error.action_url` (`string`) - `error.details` (`Record`) - `request_id` (`string`, required) ```json { "error": { "type": "", "code": "", "message": "", "param": "", "docs_url": "", "action_url": "", "details": {} }, "request_id": "" } ``` **422**: Possible codes: request_too_large_for_plan - `error` (`object`, required) - `error.type` (`string`, required) - `error.code` (`string`, required) - `error.message` (`string`, required) - `error.param` (`string`) - `error.docs_url` (`string`, required) - `error.action_url` (`string`) - `error.details` (`Record`) - `request_id` (`string`, required) ```json { "error": { "type": "", "code": "", "message": "", "param": "", "docs_url": "", "action_url": "", "details": {} }, "request_id": "" } ``` **429**: Possible codes: rate_limited - `error` (`object`, required) - `error.type` (`string`, required) - `error.code` (`string`, required) - `error.message` (`string`, required) - `error.param` (`string`) - `error.docs_url` (`string`, required) - `error.action_url` (`string`) - `error.details` (`Record`) - `request_id` (`string`, required) ```json { "error": { "type": "", "code": "", "message": "", "param": "", "docs_url": "", "action_url": "", "details": {} }, "request_id": "" } ``` **500**: Possible codes: internal_error - `error` (`object`, required) - `error.type` (`string`, required) - `error.code` (`string`, required) - `error.message` (`string`, required) - `error.param` (`string`) - `error.docs_url` (`string`, required) - `error.action_url` (`string`) - `error.details` (`Record`) - `request_id` (`string`, required) ```json { "error": { "type": "", "code": "", "message": "", "param": "", "docs_url": "", "action_url": "", "details": {} }, "request_id": "" } ``` **503**: Possible codes: service_unavailable - `error` (`object`, required) - `error.type` (`string`, required) - `error.code` (`string`, required) - `error.message` (`string`, required) - `error.param` (`string`) - `error.docs_url` (`string`, required) - `error.action_url` (`string`) - `error.details` (`Record`) - `request_id` (`string`, required) ```json { "error": { "type": "", "code": "", "message": "", "param": "", "docs_url": "", "action_url": "", "details": {} }, "request_id": "" } ``` **Example request** ```bash curl --request POST \ --url 'https://api.atelier201.com/v1/sites//media/generations' \ --header 'Authorization: ' \ --header 'Content-Type: application/json' \ --data '{ "model": "gpt-image", "prompt": "" }' ```