Nesta página
GPT Image 2 API
Gere uma imagem do GPT Image 2 por prompt e referências opcionais em uma API assíncrona previsível. A Imya gerencia o estado, o preço do plano e os arquivos gerados.
REST API · v1 · Tarefas assíncronas
Envie sua primeira solicitação
Crie uma tarefa, salve o task ID e consulte até o resultado ficar pronto.
- 1
Criar uma API Key
Gere uma chave nas configurações da conta Imya.
- 2
Criar uma tarefa
Envie o model ID, o prompt e as opções de saída.
- 3
Obter o resultado
Consulte a tarefa até concluir ou falhar.
Autenticação e idempotência
Envie a API Key como Bearer token. Todo POST de geração exige uma Idempotency-Key única para repetir sem duplicar tarefas ou cobranças.
Authorization: Bearer YOUR_IMYA_API_KEY
Content-Type: application/json
Idempotency-Key: YOUR_UNIQUE_REQUEST_KEYCriar uma geração de imagem
Cria uma tarefa assíncrona do GPT Image 2 e desconta atomicamente os créditos exatos retornados em credits_reserved.
/v1/images/generationscurl https://imya.ai/v1/images/generations \
-H "Authorization: Bearer YOUR_IMYA_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: gpt-image-order-001" \
-d '{
"model": "gpt-image-2",
"prompt": "A luxury perfume product photo on warm marble, soft studio light",
"aspect_ratio": "1:1",
"resolution": "1K",
"n": 1
}'Consultar uma tarefa
Retorna status, custo final, arquivos ou erro estruturado. Consulte com intervalo mínimo de 5 segundos; mais rápido consome o limite sem atualizar o provedor.
/v1/tasks/{id}curl https://imya.ai/v1/tasks/task_0123456789abcdef0123456789abcdef \
-H "Authorization: Bearer YOUR_IMYA_API_KEY"Parâmetros da solicitação
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| model | string | Sim | Use gpt-image-2. |
| prompt | string | Sim | Prompt de texto da imagem, de 1 a 20.000 caracteres. |
| aspect_ratio | string | Não | auto, 1:1, 3:2, 2:3, 4:3, 3:4, 5:4, 4:5, 16:9, 9:16, 2:1, 1:2, 3:1, 1:3, 21:9 ou 9:21. |
| resolution | string | Não | 1K, 2K ou 4K. Algumas proporções aceitam apenas 1K. |
| n | number | Não | Deve ser 1. Exatamente uma imagem é gerada. |
| image_urls | string[] | Não | De 1 a 16 imagens HTTPS públicas de referência. |
Respostas
{
"id": "task_0123456789abcdef0123456789abcdef",
"status": "pending",
"model": "gpt-image-2",
"created_at": "2026-07-15T08:00:00.000Z",
"updated_at": "2026-07-15T08:00:00.000Z",
"credits_reserved": 13
}{
"id": "task_0123456789abcdef0123456789abcdef",
"status": "succeeded",
"model": "gpt-image-2",
"created_at": "2026-07-15T08:00:00.000Z",
"updated_at": "2026-07-15T08:00:42.000Z",
"credits_reserved": 13,
"credits_used": 13,
"data": [
{
"url": "https://cdn.imya.ai/generated/example.png"
}
]
}Cobrança em créditos
O custo base é 10 créditos em 1K, 15 em 2K e 24 em 4K. O servidor aplica o coeficiente do plano e retorna a cobrança em credits_reserved. O exemplo cobra 13 créditos de uma conta comum em 1K. Use sempre o valor retornado; n é 1.
Status da tarefa
pendingA tarefa foi aceita e aguarda início.
processingO modelo está gerando o resultado.
succeededA geração terminou e data contém os arquivos.
failedA geração falhou. Leia o objeto error estruturado.
Erros
400Idempotency-Key ausente ou JSON inválido.
401API Key ausente ou inválida.
402A conta não tem créditos suficientes.
403A conta de API está desativada.
404A tarefa não existe ou não pertence à conta.
409A chave de idempotência foi reutilizada com outro corpo.
413O corpo excede 64 KiB.
415Content-Type deve ser application/json.
422Modelo, prompt, proporção, resolução, n ou referência inválida.
429O limite de velocidade ou concorrência foi atingido.
5xxA solicitação não pôde ser concluída ou enviada.
Contrato comum da API pública da Imya
Estas regras valem para todos os endpoints públicos de geração. Campos e preços específicos ficam na tabela do modelo.
Cobrança e repetição segura
Ao aceitar uma nova tarefa, os créditos exatos de credits_reserved são descontados atomicamente. Repetir a mesma Idempotency-Key e corpo retorna a tarefa original sem nova cobrança.
Prazo e reembolsos
Uma tarefa que não conclui em 30 minutos falha. Créditos elegíveis são devolvidos uma vez e mantêm a validade original.
Limites de velocidade e concorrência
Cada API Key aceita 120 solicitações por 60 segundos; uma conta executa até cinco tarefas de imagem ou três de vídeo. Respeite Retry-After no 429.
Consulta e propriedade
Consulte GET /v1/tasks/{id} com o id retornado e intervalo mínimo de 5 segundos. Só a conta criadora pode ler a tarefa; webhooks, SDK e envio batch não estão disponíveis.
Erros e segurança
Erros públicos removem credenciais, URLs internas e detalhes de infraestrutura. Um prompt inseguro pode ser rejeitado com prompt_blocked.
Retenção de imagens
Contas grátis mantêm imagens por 7 dias e contas pagas ativas ou Lifetime por até 30. Depois, status é failed e error.code é media_deleted.
Guia de integração em produção da GPT Image 2 API
Projete a integração do GPT Image 2 como um sistema de tarefas assíncronas recuperável, não como uma solicitação HTTP longa. Salve sempre o id da Imya e torne as repetições determinísticas.
Escolher parâmetros do contrato
Valide cada solicitação com a tabela desta página. Comece com a configuração mínima e aumente qualidade, tamanho, duração ou referências somente quando necessário.
Preserve a ordem das referências e confirme os direitos de uso.
Projetar um fluxo assíncrono recuperável
Envie a tarefa de imagem, salve id e consulte GET /v1/tasks/{id} com intervalo mínimo de 5 segundos. Os status públicos são pending, processing, succeeded e failed e o limite é 30 minutos. Não há webhooks, SDK ou batch.
- 01Salve id, status, credits_reserved e identidade da solicitação antes de atualizar a UI.
- 02Use backoff, respeite Retry-After no 429 e não transforme erro de transporte em outra tarefa paga.
- 03Limite a cinco tarefas de imagem por conta e 120 solicitações por 60 segundos e API Key.
Cobrança e repetição determinísticas
Na aceitação, credits_reserved é descontado. Salve uma Idempotency-Key por criação; repeti-la com o mesmo corpo retorna a tarefa original.
Falhas elegíveis são reembolsadas uma vez com a validade original. refund_pending indica liquidação e credits_refunded confirma.
Proteger credenciais, propriedade e mídia
Mantenha API Keys no servidor e associe id ao usuário autenticado. Registre identificadores de suporte sem expor prompts, URLs privadas ou credenciais.
Imagens duram 7 dias no grátis e até 30 no pago ativo ou Lifetime. Depois status é failed e error.code media_deleted.
Checklist de produção
- Valide campos do modelo.
- Salve Idempotency-Key e corpo.
- Persista status e consulte a cada 5 segundos ou mais.
- Aplique concorrência e velocidade.
- Trate os quatro status e códigos de liquidação.
- Mantenha credenciais no servidor e defina retenção.
Perguntas frequentes
Com que frequência consultar?
Espere pelo menos 5 segundos e use backoff.
Quando os créditos são cobrados?
Na aceitação, credits_reserved é descontado.
Uma repetição cobra duas vezes?
Não com a mesma Idempotency-Key e corpo.
Como tratar falha final?
Mostre erro seguro, preserve id e verifique credits_refunded.
Quer testar o modelo antes de integrar?
Abra o gerador do GPT Image 2 e compare prompts e opções sem escrever código.
Testar GPT Image 2 online