Geração de imagens GPT-Image-2

Documentation Index

Fetch the complete documentation index at: https://docs.apimart.ai/llms.txt

Use this file to discover all available pages before exploring further.

curl --request POST \
  --url https://api.apimart.ai/v1/images/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "gpt-image-2",
    "prompt": "A ginger cat sitting on a windowsill watching the sunset, watercolor style",
    "n": 1,
    "size": "16:9",
    "resolution": "2k"
  }'

{
  "code": 200,
  "data": [
    {
      "status": "submitted",
      "task_id": "task_01KPQ7J7DWB7QZ3WCEK3YVPBRA"
    }
  ]
}

​

Autorizações

Authorization: Bearer YOUR_API_KEY

​

Body

​

Exemplos de uso

{
  "model": "gpt-image-2",
  "prompt": "A ginger cat sitting on a windowsill watching the sunset, watercolor style"
}

{
  "model": "gpt-image-2",
  "prompt": "a corgi astronaut on the moon, cinematic, 8k",
  "size": "16:9",
  "resolution": "2k"
}

{
  "model": "gpt-image-2",
  "prompt": "An ancient castle under a starry sky",
  "size": "16:9",
  "resolution": "4k"
}

{
  "model": "gpt-image-2",
  "prompt": "Turn this photo into a watercolor painting",
  "image_urls": [
    "https://example.com/photo.jpg"
  ]
}

{
  "model": "gpt-image-2",
  "prompt": "Turn this photo into a watercolor painting",
  "image_urls": [
    "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..."
  ]
}

{
  "model": "gpt-image-2",
  "prompt": "Fuse these two photos into a single poster",
  "size": "4:3",
  "resolution": "2k",
  "image_urls": [
    "https://example.com/photo-a.jpg",
    "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..."
  ]
}

​

Response

​

Consulta de resultados da tarefa

​

Exemplo de resposta de sucesso

{
  "code": 200,
  "data": {
    "id": "task_01KPQ7J7DWB7QZ3WCEK3YVPBRA",
    "status": "completed",
    "progress": 100,
    "created": 1776748674,
    "completed": 1776748726,
    "actual_time": 52,
    "cost": 0.05279,
    "estimated_time": 100,
    "result": {
      "images": [
        {
          "url": [
            "https://upload.apimart.ai/f/image/xxxxxxxx-gpt_image_2_task_xxx_0.png"
          ],
          "expires_at": 1776835126
        }
      ]
    }
  }
}

​

Status da tarefa

​

Recomendações de polling

• Atraso da consulta inicial: Aguarde 10~20 segundos após o envio antes da primeira consulta
• Intervalo de consulta: 3~5 segundos recomendados, evite polling em nível de milissegundos
• Referência de timeout: Uma única imagem normalmente é concluída em 3060 segundos (actual_time observado de 4453s)
• Consulta em lote: Para consultar várias tarefas de uma só vez, use POST /v1/tasks/batch com o corpo {"task_ids": ["task_xxx", "task_yyy"]}

​

Observações

1. Processamento assíncrono: O envio retorna task_id, faça polling em /v1/tasks/{task_id} para obter a URL final da imagem
2. Moderação de conteúdo: O prompt é revisado primeiro — violações são rejeitadas sem cobrança
3. URL do resultado: A plataforma espelha os links assinados temporários do upstream para seu próprio armazenamento de objetos R2, retornando um link estável que os clientes podem acessar diretamente
4. Validade da URL: expires_at = completed + 24h na resposta é um campo indicativo, faça o download ou espelhe para sua própria CDN o quanto antes
5. Conflito de proporção: Use o campo size para a proporção — evite repeti-la no prompt para evitar ambiguidade no upstream
6. Cobrança: Cobrado por nível de resolução (1K / 2K / 4K), sem cobrança em caso de falha ou rejeição pela moderação
7. Proporções suportadas em 4K: Todas as 15 proporções acima suportam 4K; você também pode passar as dimensões em pixels correspondentes diretamente via size
8. Retenção de tarefas: O task_id é mantido no banco de dados por padrão durante vários dias (configurado por TASK_RETENTION_DAYS) — consultas expiradas retornam “a tarefa não existe ou expirou”