API de geração de imagens

A API de imagens é compatível com o protocolo OpenAI Images. A lista abaixo contém oito modelos selecionados e verificados. Todos fazem text-to-image por generations; use /edits somente nos modelos explicitamente marcados.

Há dois endpoints disponíveis:

• /v1/images/generations - gera imagens; alguns modelos também aceitam referências neste endpoint
• /v1/images/edits - edita imagens para os modelos explicitamente marcados abaixo, compatível com o uso nativo de edits da OpenAI

Endpoint e autenticação

POST https://api.icodeeasy.cc/v1/images/generations
POST https://api.icodeeasy.cc/v1/images/edits

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

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

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.

Parâmetros da requisição

• model (obrigatório): um dos oito IDs selecionados na tabela acima.
• 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.
• 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.
• resolution (padrão 1k): Gemini 2.5 aceita somente 1k; os modelos Gemini 3.x listados aceitam 1k, 2k ou 4k. Não use este campo para escolher tier em gpt-image-2.
• quality (somente cobrança de gpt-image-2): low, medium, high ou auto. Não afeta a saída real e só decide o preço cobrado de gpt-image-2. Modelos Gemini ignoram esse campo e usam preço fixo por modelo.
• image_urls / image_input (opcional, JSON): imagens de referência para image-to-image, até 4 imagens. 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.

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 e não tem tier de resolução publicado.

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

Minimal text-to-image, sync

curl -X POST https://api.icodeeasy.cc/v1/images/generations \
  -H "Authorization: Bearer sk_xxxxxxxx" \
  -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 sk_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.1-flash-image-preview",
    "prompt": "a corgi astronaut on the moon, cinematic",
    "size": "16:9",
    "resolution": "2k"
  }'

Gemini text-to-image

curl -X POST https://api.icodeeasy.cc/v1/images/generations \
  -H "Authorization: Bearer sk_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.1-flash-image-preview",
    "prompt": "a futuristic coffee shop at sunrise, realistic photography",
    "size": "16:9",
    "resolution": "1k"
  }'

Image-to-image using image URL (JSON)

curl -X POST https://api.icodeeasy.cc/v1/images/edits \
  -H "Authorization: Bearer sk_xxxxxxxx" \
  -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 sk_xxxxxxxx" \
  -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 sk_xxxxxxxx" \
  -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..."
    ]
  }'

Async submit + polling

# 1) Submit and get task_id immediately
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",
    "prompt": "make this person 70 years old",
    "image_urls": ["https://example.com/photo.png"]
  }'
# -> {"status":"pending","task_id":"d142c93a-..."}

# 2) Poll until completed
curl "https://api.icodeeasy.cc/v1/images/tasks/d142c93a-..." \
  -H "Authorization: Bearer sk_xxxxxxxx"
# -> {"status":"completed","result_url":"https://...png","cost":0.2,...}

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" }

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.

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: o link permanece disponível por longo prazo
• 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: invalid parameters, unsupported ratio, more than 4 reference images, non-https reference URL, invalid base64, and similar issues
• 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.

Cobrança

A cobrança é fixa por quantidade de imagens x modelo / tier em CNY e não depende de tokens.

gpt-image-2 é cobrado por quality tier:

• low: CNY 0.10 / image
• medium / auto (default): CNY 0.20 / image
• high: CNY 0.40 / image

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.

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

• Model: use um dos oito IDs selecionados acima; não há gpt-image-1 nem dall-e-3
• Endpoints: todos os modelos selecionados aceitam generations; use edits somente nos modelos explicitamente marcados acima
• size: aspect ratios such as 16:9 are recommended; pixel strings are also accepted
• resolution: Gemini 2.5 aceita somente 1k; os Gemini 3.x listados aceitam 1k, 2k e 4k; gpt-image-2 não tem tier de resolução publicado
• quality: low, medium, high, or auto; billing only, different from OpenAI standard / hd
• response_format: b64_json is not supported; URLs are always returned
• Reference images: apenas modelos marcados acima as aceitam; solicitações compatíveis usam image_urls / image_input (JSON) ou image[] (multipart), dentro dos limites do modelo
• Modo assíncrono: a OpenAI não possui esse modo; esta API aceita ?async=1, retorna task_id e consulta /v1/images/tasks/{id} para obter o resultado
• Task ID: responses include id / task_id for troubleshooting