--- title: "Criar uma imagem ou um vídeo com IA" description: "Gera uma imagem ou um vídeo curto na mídia do site, com cobrança de créditos a preço fixo." canonical: "https://atelier201.com/docs/pt/api/media/generate" updated: "2026-11-06" --- # Criar uma imagem ou um vídeo com IA Requer `media:generate`, uma permissão específica: uma credencial que pode editar sites não pode gastar créditos, a menos que também tenha recebido essa permissão. Usa os créditos do espaço de trabalho. 1. Faça a chamada com `estimate_only: true`. Ela não custa nada e retorna `estimated_credits` (o preço exato) e `balance`. 2. Faça a chamada novamente com `max_credits` definido como esse preço. Sem `max_credits`, a chamada é recusada. Se o preço for maior que esse limite, a chamada é recusada sem cobrança: `invalid_parameter` em `max_credits`, com `details.reason` `price_above_max_credits`, `details.estimated_credits` e `details.max_credits`. Os créditos são cobrados quando a geração começa. Se ela falhar, os créditos são devolvidos. Uma imagem costuma ficar pronta dentro de `wait_seconds` (50 por padrão) e é retornada com `status: succeeded` e sua `media`. Um vídeo leva de um a cinco minutos: a resposta é `status: running` com um `id`; consulte [a geração](/docs/api/media/generation) até ela terminar. O arquivo é adicionado à mídia do site como se tivesse sido enviado, com `credit` definido como o modelo que o criou. Nunca apresente uma imagem gerada como uma fotografia do negócio, de seus produtos, de seus funcionários ou de suas instalações. São permitidas no máximo 10 gerações por minuto por espaço de trabalho (`429 rate_limited` ao ultrapassar esse limite, com `details.retry_after_seconds`). Se os créditos forem insuficientes: `402 insufficient_credits` com `details.needed` e `details.balance`. Se o modelo estiver ocupado, a geração falha e os créditos são devolvidos: tente novamente em um minuto. ```http POST https://api.atelier201.com/v1/sites/{site_id}/media/generations ``` ## Authorizations - `Authorization` (bearer, in header, required) ## Path parameters - `site_id` (`string`, required): O id do site ou seu slug (o endereço antes de .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 lista cada modelo, para que ele é mais indicado e seus preços em créditos. - `prompt` (`string`, required, length: `1–4000 chars`): O que mostrar: assunto, cenário, iluminação, enquadramento, estilo. - `aspect_ratio` (`enum`, one of: `16:9, 1:1, 9:16, 4:3, 3:4, 3:2, 2:3`): Largura em relação à altura. Cada modelo aceita as proporções listadas por list_media_models. Por padrão, use a primeira (16:9 para a maioria). - `quality` (`enum`, one of: `draft, standard, high`): Imagens: rascunho, padrão (default) ou alta. - `duration` (`integer`, range: `1–10`): Vídeos: duração em segundos. - `resolution` (`enum`, one of: `480p, 720p, 768p, 1080p, 2k`): Vídeos: por padrão, a resolução do modelo (720p ou 768p para minimax e p-video). - `audio` (`boolean`): Vídeos: com áudio (somente seedance). - `filename` (`string`, length: `1–100 chars`): Um nome sem extensão. - `alt` (`string`, length: `≤ 300 chars`) - `estimate_only` (`boolean`): true: o preço exato em créditos e o saldo. É gratuito e nada é executado. - `max_credits` (`integer`, range: `≤ 9007199254740991`): Obrigatório para executar: o valor máximo que você aceita gastar. A solicitação será recusada, sem cobrança, se o preço for maior. Use o valor de uma chamada estimate_only. - `wait_seconds` (`integer`, range: `0–55`): Quanto tempo aguardar pelo resultado. O padrão é 50 para uma imagem e 0 para um vídeo. ## Response **202**: Crie uma imagem ou um vídeo com IA - `data` (`Record`, required) - `data.id` (`string`): ID da geração: faça GET até que o status seja succeeded ou 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): Quem criou o conteúdo, quando a licença exige essa informação: "Photo by Jane Doe on Pixabay", "Generated with Seedream 5 Lite (ByteDance)". Null para arquivos enviados. - `data.media.keep_original` (`boolean`, required): Armazenado exatamente como foi enviado, sem nunca ser recodificado durante uma build. Caso contrário, imagens com mais de 200 KB são comprimidas ao chegar (no máximo 2000 px, para cerca de 150 KB, qualidade 75 ou superior, metadados removidos). - `data.error` (`string,null`) - `data.credits` (`integer | null`): Quanto custou. - `data.credits_refunded` (`integer | null`): Devolvidos após uma falha. - `data.estimated_credits` (`integer`, range: `-9007199254740991–9007199254740991`): estimate_only: o preço exato que seria cobrado. - `data.balance` (`number`): estimate_only: os créditos disponíveis no espaço de trabalho no momento. - `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**: Códigos possíveis: 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**: Códigos possíveis: 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**: Códigos possíveis: 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**: Códigos possíveis: 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**: Códigos possíveis: 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**: Códigos possíveis: 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**: Códigos possíveis: 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**: Códigos possíveis: 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**: Códigos possíveis: 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**: Códigos possíveis: 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**: Códigos possíveis: 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**: Códigos possíveis: 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": "" }' ```