API de geração de imagens

A API de geração e edição de imagens é compatível com o protocolo OpenAI Images. Atualmente fornece gpt-image-2, com suporte a text-to-image e image-to-image. A cobrança é baseada na quantidade de imagens e no quality tier, não em tokens.

Há dois endpoints disponíveis:

/v1/images/generations - gera imagens (text-to-image; image-to-image quando houver imagens de referência)
/v1/images/edits - edita imagens (image-to-image com imagens de referência), compatível com o uso nativo de edits da OpenAI

Os dois endpoints têm a mesma capacidade e cobrança. Com imagens de referência, a requisição é image-to-image; sem referências, é text-to-image.

Endpoint e autenticação

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

Os exemplos usam o domínio oficial https://jp.icodeeasy.cc; mantenha o caminho sem alterações.

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:

JSON (Content-Type: application/json): coloque imagens de referência em image_urls como URLs ou data URLs base64. É o formato mais comum.
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): atualmente apenas gpt-image-2 é compatível.
prompt (obrigatório): descrição da imagem em inglês ou chinês. A OpenAI 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): tier de resolução, 1k ou 2k.
quality (somente cobrança): low, medium, high ou auto. Não afeta a saída real e só decide o preço cobrado. Valor ausente usa medium.
image_urls / image_input (opcional, JSON): imagens de referência para image-to-image, até 16 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.

1k e 2k aceitam todas as proporções.

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.

	Síncrono padrão	Assíncrono `?async=1`
Return timing	Waits tens of seconds until image is ready	Returns immediately (< 1 second)
Status code	`200`	`202`
Response body	`{"created":...,"data":[{"url":"..."}],"id":"..."}`	`{"status":"pending","task_id":"..."}`
How to get image	Returned in one response	Poll `GET /v1/images/tasks/{task_id}`

Exemplos de requisição

Minimal text-to-image, sync

curl -X POST https://jp.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"
  }'

Specify ratio and 2K

curl -X POST https://jp.icodeeasy.cc/v1/images/generations \
  -H "Authorization: Bearer sk_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "a corgi astronaut on the moon, cinematic",
    "size": "16:9",
    "resolution": "2k",
    "quality": "medium"
  }'

Image-to-image using image URL (JSON)

curl -X POST https://jp.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://jp.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://jp.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",
    "resolution": "2k",
    "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://jp.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://jp.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 16 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 quality tier em CNY e não depende de tokens:

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

quality decide o tier de cobrança. Valor ausente usa medium. Em Usage Details, a requisição é registrada como model = gpt-image-2, 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: only gpt-image-2; no gpt-image-1 or dall-e-3
Endpoints: generations and edits have the same capability and switch automatically based on whether reference images exist
size: aspect ratios such as 16:9 are recommended; pixel strings are also accepted
resolution: new field not present in OpenAI Images API, 1k or 2k
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: image_urls / image_input (JSON) or image[] (multipart), up to 16 images, URLs and base64 can be mixed
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

Criar conta e obter uma API Key