API de geração de imagens

A API é compatível com OpenAI Images e permite gerar e editar imagens e consultar tarefas assíncronas.

Endpoint e autenticação

POST https://api.icodeeasy.cc/v1/images/generations
POST https://api.icodeeasy.cc/v1/images/edits
GET  https://api.icodeeasy.cc/v1/images/tasks/{task_id}

Alguns modelos aceitam referências em generations. Use edits com modelos que oferecem edição.

Use https://api.icodeeasy.cc como Base URL principal. https://jp.icodeeasy.cc e https://sg.icodeeasy.cc são domínios de backup / fallback; mantenha o mesmo caminho ao trocar.

Headers da requisição:

• Authorization: Bearer <your API Key> (obrigatório, começa com sk_)
• Content-Type: application/json para JSON ou multipart/form-data para upload de arquivos

Defina a variável de ambiente ICODEEASY_API_KEY no terminal antes de executar os exemplos.

POST /images/generations e POST /images/edits sem o prefixo /v1 também são aceitos e têm o mesmo comportamento.

Modos síncrono / assíncrono

Modo síncrono padrão: a requisição aguarda a geração da imagem terminar e retorna data[].url compatível com OpenAI.

Modo assíncrono: adicione ?async=1 à URL (true e yes também são aceitos). A API retorna task_id imediatamente, e você consulta o resultado por polling. Use quando não quiser manter uma conexão longa, precisar tratar progresso ou enviar lotes.

Exemplos de requisição

GPT Image 2 a partir de texto (síncrono)

curl -X POST https://api.icodeeasy.cc/v1/images/generations \
  -H "Authorization: Bearer $ICODEEASY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "an orange cat sitting on a windowsill watching the sunset, watercolor style"
  }'

Especificar proporção e 2K com Gemini 3.x

curl -X POST https://api.icodeeasy.cc/v1/images/generations \
  -H "Authorization: Bearer $ICODEEASY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.1-flash-image-preview",
    "prompt": "a corgi astronaut on the moon, cinematic",
    "aspect_ratio": "16:9",
    "image_size": "2K"
  }'

Dois formatos de corpo da requisição

A API aceita dois formatos de corpo da requisição:

1. JSON (Content-Type: application/json): coloque imagens de referência em image_urls como URLs ou data URLs base64. É o formato mais comum.
2. multipart/form-data: envie imagens de referência por arquivos image[] e coloque os outros parâmetros nos campos do formulário. Isso corresponde ao uso nativo de edits da OpenAI e serve para uploads locais.

Image-to-image using image URL (JSON)

curl -X POST https://api.icodeeasy.cc/v1/images/edits \
  -H "Authorization: Bearer $ICODEEASY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "make this person 70 years old",
    "size": "1536x1024",
    "image_urls": ["https://example.com/photo.png"]
  }'

Image-to-image uploading a local file (multipart)

curl -X POST https://api.icodeeasy.cc/v1/images/edits \
  -H "Authorization: Bearer $ICODEEASY_API_KEY" \
  -F "model=gpt-image-2" \
  -F "prompt=make this person 70 years old" \
  -F "size=1536x1024" \
  -F "image[]=@/path/to/photo.png"

Image-to-image with multiple references (URL + base64 mixed)

curl -X POST https://api.icodeeasy.cc/v1/images/edits \
  -H "Authorization: Bearer $ICODEEASY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "merge these two photos into a poster",
    "size": "4:3",
    "image_urls": [
      "https://example.com/photo-a.jpg",
      "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..."
    ]
  }'

Enviar uma edição assíncrona

curl -X POST "https://api.icodeeasy.cc/v1/images/edits?async=1" \
  -H "Authorization: Bearer $ICODEEASY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "make this person 70 years old",
    "image_urls": ["https://example.com/photo.png"]
  }'
# -> {"status":"pending","task_id":"d142c93a-..."}

Guarde o task_id da resposta HTTP 202 e consulte a tarefa para obter o resultado.

Estrutura da resposta

Sync success (HTTP 200, OpenAI Images compatible):

{
  "id": "3e0c77bb-9cbd-4c44-9549-bff1b4060623",
  "created": 1781599773,
  "data": [
    {
      "url": "https://api.icodeeasy.cc/v1/images/files/gpt-image-2/20260616/3e0c77bb-...-1.png"
    }
  ]
}

Async submit (HTTP 202):

{ "status": "pending", "task_id": "d142c93a-de26-40c9-be62-0de840d10960" }

Consulte o status de uma tarefa de imagem

curl -sS 'https://api.icodeeasy.cc/v1/images/tasks/YOUR_TASK_ID' \
  -H "Authorization: Bearer $ICODEEASY_API_KEY"

Async task query (GET /v1/images/tasks/{task_id}):

{
  "task_id": "d142c93a-de26-40c9-be62-0de840d10960",
  "status": "completed",
  "model": "gpt-image-2",
  "cost": 0.2,
  "result_url": "https://api.icodeeasy.cc/v1/images/files/gpt-image-2/20260616/d142c93a-...-1.png"
}

• status: pending / completed / failed
• data[].url / result_url: image URL, usable directly in <img src>
• id / task_id: task ID for support troubleshooting

A API sempre retorna URLs e não suporta response_format: b64_json. Baixe a imagem você mesmo se precisar dos bytes.

A consulta pode retornar HTTP 200 com status: failed. Exiba a mensagem de error. Quando presente, error_detail contém type, message, retryable, charged e os campos opcionais code, moderation_stage e categories. Use retryable para decidir se deve criar uma nova tarefa. Se o campo não estiver presente, confira o erro antes de reenviar. Para HTTP 404, confira o ID e a conta que enviou a tarefa.

Comportamento da URL da imagem

data[].url looks like https://api.icodeeasy.cc/v1/images/files/gpt-image-2/YYYYMMDD/<id>-<seq>.png:

• Abrir diretamente: GET retorna 302 e redireciona para a URL real da imagem
• Forçar download: adicione ?download=1
• Disponibilidade de longo prazo: guarde a URL do I Code Easy retornada pela API. O destino do redirecionamento 302 pode mudar.
• Controle de acesso: este caminho não exige API Key; o link completo funciona como credencial. Não publique links de resultado gerado, porque qualquer pessoa com a URL completa pode baixar a imagem.

Semântica síncrona e timeout

No modo síncrono padrão, a requisição fica aberta até a imagem ficar pronta:

• Timeout HTTP recomendado no cliente: pelo menos 200 segundos
• Uma imagem geralmente leva de 30 a 60 segundos; image-to-image, 2K ou múltiplas imagens podem levar mais tempo
• Se não quiser esperar em uma conexão longa, use modo assíncrono (?async=1) para obter um task_id e consultar depois

Resposta de erro

Error bodies use:

{
  "error": {
    "type": "server_error",
    "message": "...",
    "provider": "icodeeasy.cc"
  }
}

Common statuses:

• 400 invalid_request_error: parâmetros inválidos, como proporção incompatível, referências acima do limite do modelo ou modo, URL sem HTTPS ou base64 inválido
• 401 authentication_error: missing or invalid API Key
• 402 payment_required: insufficient balance or exhausted monthly quota
• 429 rate_limit_error: rate limit exceeded
• 5xx: service temporarily unavailable or generation failed; retry later

Requisições com falha não são cobradas e não descontam saldo.

Parâmetros da requisição

Os parâmetros abaixo se aplicam a imagens estáticas. Para gerar GIFs, use os parâmetros da seção de GIF com GPT Image 2.6.

• model (obrigatório): um ID dos modelos em destaque ou da seção de imagens estáticas com GPT Image 2.6.
• prompt (obrigatório): descrição da imagem em inglês ou chinês. O upstream faz revisão de segurança de conteúdo; conteúdo rejeitado não é cobrado.
• n (padrão 1): número de imagens. A cobrança acumula por quantidade de imagens. Quando GPT Image 2 usa o custo total real da tarefa, a quantidade não é multiplicada novamente.
• size (padrão 1:1): proporção de saída. Veja abaixo. auto é tratado como 1:1; strings em pixels como 1536x1024 também são aceitas.
• aspect_ratio (opcional, padrão 1:1): proporção de saída do GPT Image 2.5 e 2.6, como 16:9.
• image_size (opcional, padrão 1K): resolução de saída do GPT Image 2 / 2.5 / 2.6, com valores 1K, 2K ou 4K. Para Gemini, consulte as resoluções compatíveis.
• quality: GPT Image 2 aceita low / medium / high / auto, sem faixas de preço por qualidade. GPT Image 2.5 cobra por imagem e resolução, sem configuração de qualidade separada. O campo é aceito em pedidos antigos, mas não altera os parâmetros de geração nem o preço.
• image_urls / image_input (opcional, JSON): imagens de referência para edição ou geração. O limite depende do modelo e do modo. Os quatro modelos Seedream dos modelos em destaque, FLUX 3 e GPT Image 2.6 aceitam até 8 referências. Os modelos Gemini da mesma tabela aceitam até 4. Os itens podem ser URLs públicas https://... ou data:image/...;base64,...; valores mistos são permitidos. Os dois campos são aliases.
• image[] (opcional, multipart): arquivos de imagem de referência para image-to-image. Vários arquivos são permitidos e equivalem ao formato de upload de image_urls.

Nota sobre imagem de referência: URLs devem usar https:// (http é rejeitado); base64 deve ser um valor válido data:image/*;base64,.

Proporções e resolução compatíveis

Proporções size compatíveis: 1:1 / 3:2 / 2:3 / 4:3 / 3:4 / 5:4 / 4:5 / 16:9 / 9:16 / 2:1 / 1:2 / 21:9 / 9:21 / auto.

O aspect_ratio do GPT Image 2.5 aceita: 1:1 / 3:2 / 2:3 / 4:3 / 3:4 / 5:4 / 4:5 / 16:9 / 9:16 / 21:9.

gemini-2.5-flash-image aceita somente 1k. Os modelos Gemini 3.x listados aceitam 1k, 2k e 4k. gpt-image-2 usa size para proporção ou dimensões em pixels, com preços de referência por resolução 1K, 2K e 4K.

Diferenças em relação à OpenAI Images API

• Consulte os modelos em destaque para conferir os IDs aceitos e o suporte a edição.
• Confira proporções, resolução e formatos de referência nos parâmetros da requisição.
• Os resultados contêm URLs das imagens. No modo assíncrono, guarde o ID da tarefa e consulte o resultado.

Modelos em destaque

Todos os 16 modelos verificados na tabela geram imagens a partir de texto com generations. A tabela indica quais oferecem o endpoint de edição.

Imagens estáticas com GPT Image 2, 2.5 e 2.6

As três versões geram imagens estáticas em 1K, 2K e 4K. Use POST /v1/images/generations para gerar a partir de texto. Para editar, use POST /v1/images/edits com URLs HTTPS públicas ou valores data:image/...;base64,... em image_urls. O Image 2.6 aceita até oito referências. As referências para imagens estáticas do Image 2.6 em 2K e 4K devem estar em PNG, JPEG ou WebP.

Selecione a resolução com image_size. No Image 2, informe uma proporção como 16:9 em size. No Image 2.5 e 2.6, use aspect_ratio. Para imagens estáticas no Image 2.6, defina output_format: "png" e n: 1.

Veja nos exemplos de requisição como gerar uma imagem a partir de texto com GPT Image 2 em modo síncrono.

GPT Image 2.5 text-to-image (2K)

curl -X POST "https://api.icodeeasy.cc/v1/images/generations?sync=1" \
  -H "Authorization: Bearer sk_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.5-flare",
    "prompt": "um gato laranja usando capacete de astronauta, iluminação cinematográfica",
    "aspect_ratio": "16:9",
    "image_size": "2K"
  }'

GPT Image 2.5 image-to-image (edição com imagem de referência)

curl -X POST "https://api.icodeeasy.cc/v1/images/edits?sync=1" \
  -H "Authorization: Bearer sk_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.5-sunburst",
    "prompt": "substitua o fundo por uma praia ao pôr do sol, preservando a pose e a roupa",
    "aspect_ratio": "3:2",
    "image_size": "1K",
    "image_urls": ["https://example.com/photo.png"]
  }'

Edição com referência no GPT Image 2.6 (4K)

O exemplo usa Sunburst. Para usar Flare, defina model como gpt-image-2.6-flare. Troque a URL de exemplo pela URL da sua referência.

curl -X POST 'https://api.icodeeasy.cc/v1/images/edits?async=1' \
  -H "Authorization: Bearer sk_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.6-sunburst",
    "prompt": "Troque o fundo por uma parede azul-clara. Preserve a xícara e a composição da imagem de referência.",
    "output_format": "png",
    "aspect_ratio": "16:9",
    "image_size": "4K",
    "n": 1,
    "image_urls": ["https://example.com/reference.png"]
  }'

Geração de GIF com GPT Image 2.6

Use gpt-image-2.6-flare ou gpt-image-2.6-sunburst em POST /v1/images/generations. Defina output_format: "gif", size: "auto" e n: 1 para gerar um GIF com dimensões e parâmetros de quadros automáticos.

Para gerar um GIF apenas com texto, omita image_urls. Para usar referências, envie até oito imagens como URLs HTTPS públicas ou valores no formato data:image/...;base64,....

O exemplo usa Flare. Troque a URL de exemplo pela URL da sua imagem de referência. Para usar Sunburst, defina model como gpt-image-2.6-sunburst.

curl -X POST 'https://api.icodeeasy.cc/v1/images/generations?async=1' \
  -H "Authorization: Bearer sk_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.6-flare",
    "prompt": "Anime a lanterna de papel da imagem de referência balançando suavemente. Preserve a composição e crie um loop contínuo.",
    "output_format": "gif",
    "size": "auto",
    "n": 1,
    "image_urls": [
      "https://example.com/reference.png"
    ]
  }'

A requisição assíncrona retorna um task_id. Consulte GET /v1/images/tasks/{task_id} e baixe o GIF em result_url após a conclusão.

• GIF gerado apenas com texto tem tarifa padrão de ¥0,0833 por resultado. No Flare, a tarifa é de ¥0,30 quando o serviço de contingência é usado.
• GIF com imagens de referência é cobrado pelo uso real. O valor final aparece no histórico de uso.

FLUX 2 Pro / Max / Flex

Preços de referência por resolução (CNY / imagem). Cobrança pelo uso real de geração; o valor final consta na fatura: O valor varia conforme as dimensões e as imagens de referência.

Série Seedream

Os quatro novos modelos geram e editam imagens com até 8 referências. Use proporção explícita em size / aspect_ratio, a resolução abaixo em image_size e referências em image_input. Uma imagem por tarefa; várias imagens viram tarefas independentes. Proporções 5 Flash/Pro: 1:1, 4:3, 3:4, 16:9, 9:16, 3:2, 2:3, 2:1, 1:2, 21:9; 4.5/4.0 também aceitam 9:21. O prompt do 4.0 tem limite de 1000 caracteres. Camadas, fundo transparente e recursos avançados não estão habilitados. Lite mantém 2K ¥0.30 / 3K ¥0.45.

Preços de referência; tarefas concluídas são cobradas pelo valor real da geração. Consulte o uso para o valor final. Somente Seedream 5 Pro: cada referência após a primeira acrescenta aproximadamente ¥0.01911; a cobrança real da tarefa tem prioridade.

FLUX 3 Image e Klein

flux-3-image e flux-3-image-klein usam image_size: 768sq / 1K / 1.5K / 2K / 4K, com aspect_ratio explícito: 1:1 / 9:16 / 16:9 / 2:3 / 3:2 / 4:5 / 5:4. Não envie auto nem dimensões em pixels; o limite antigo de 2048 pixels por lado do FLUX 2 não se aplica. Envie até 8 referências por image_input (URLs ou data URLs base64); edição com caixas delimitadoras não é aceita. Cada tarefa gera uma imagem; a página de desenho divide várias imagens em tarefas independentes. Image não aceita seed; Klein aceita seed de 0 a 4294967295. Nenhum dos dois aceita prompt_upsampling, style ou negative_prompt.

Preços de referência; tarefas concluídas são cobradas pelo valor real da geração. Consulte o uso para o valor final.

{
  "model": "flux-3-image",
  "prompt": "A watercolor landscape",
  "aspect_ratio": "16:9",
  "image_size": "4K",
  "image_input": []
}

Cobrança

Consulte os preços de imagens estáticas com GPT Image e as regras de cobrança de GIFs.

Modelos de imagem Gemini são cobrados por preço fixo por modelo:

Em Usage Details, a requisição é registrada com o model real, e cost_breakdown inclui image_count, image_cost_rmb e image_urls, então você pode copiar links ou baixar imagens do histórico.