Images API

Dois endpoints: geração (texto → imagem) e edição (imagem + texto → imagem). Ambas as respostas seguem a estrutura padrão da OpenAI em data[0].b64_json.

Seedream e Qwen-Image não suportam /v1/images/edits; a geração de imagem a partir de imagem passa pelo endpoint generations, mas o campo da imagem de referência é diferente: Seedream usa image e Qwen usa input_images. Cuidado para não trocá-los. Para controlar a resolução do Gemini (de 512 a 4K), use o protocolo nativo do Gemini. As diferenças de parâmetros de cada família estão na página da família correspondente.

Início rápido

Uma requisição mínima executável: gera uma imagem de 1024×1024, decodifica e salva como output.png.

import base64
from openai import OpenAI
 
client = OpenAI(
    api_key="YOUR_OFOX_API_KEY",
    base_url="https://api.ofox.io/v1",
    timeout=600,  # a API de imagens é síncrona e pode demorar
)
 
resp = client.images.generate(
    model="openai/gpt-image-2.5-flare",
    prompt="Uma maçã vermelha sobre uma mesa branca",
    size="1024x1024",
    quality="low",
)
 
with open("output.png", "wb") as f:
    f.write(base64.b64decode(resp.data[0].b64_json))

curl https://api.ofox.io/v1/images/generations \
  --max-time 600 \
  -H "Authorization: Bearer $OFOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-image-2.5-flare",
    "prompt": "Uma maçã vermelha sobre uma mesa branca",
    "size": "1024x1024",
    "quality": "low"
  }' | jq -r '.data[0].b64_json' | base64 --decode > output.png

Todas as famílias são chamadas da mesma forma; para trocar de modelo, basta alterar model. Os valores aceitos e os parâmetros exclusivos variam; consulte a descrição de cada parâmetro abaixo.

Gerar imagens

POST https://api.ofox.io/v1/images/generations

Parâmetros da requisição

Os valores e padrões abaixo se aplicam à família GPT Image (gpt-image-2.5-flare, gpt-image-2.5-sunburst, gpt-image-2). Quando outras famílias diferem, isso é indicado separadamente. Detalhes medidos: família GPT Image.

Resposta

{
  "created": 1777385517,
  "data": [
    { "b64_json": "iVBORw0KGgoAAAANSUhEUgAA…", "index": 0 }
  ],
  "model": "openai/gpt-image-2.5-flare",
  "size": "1024x1024",
  "quality": "low",
  "usage": {
    "input_tokens": 13,
    "input_tokens_details": { "text_tokens": 13 },
    "output_tokens": 196,
    "output_tokens_details": { "image_tokens": 196 },
    "total_tokens": 209
  }
}

Editar imagens

POST https://api.ofox.io/v1/images/edits

Parâmetros da requisição

Enviados como campos de formulário multipart/form-data, com o upload de um arquivo de imagem. Os valores e padrões também se aplicam à família GPT Image.

Resposta

Mesma estrutura do endpoint de geração; usage inclui também os tokens de entrada das imagens de referência:

{
  "created": 1777385669,
  "data": [
    { "b64_json": "iVBORw0KGgoAAAANSUhEUgAA…", "index": 0 }
  ],
  "model": "openai/gpt-image-2",
  "size": "auto",
  "quality": "low",
  "usage": {
    "input_tokens": 1041,
    "input_tokens_details": { "image_tokens": 1024, "text_tokens": 17 },
    "num_input_images": 1,
    "output_tokens": 358,
    "total_tokens": 1399
  }
}

Os demais campos são iguais aos da resposta do endpoint de geração.

Chamada

import base64
from openai import OpenAI
 
client = OpenAI(api_key="YOUR_OFOX_API_KEY", base_url="https://api.ofox.io/v1", timeout=600)
 
with open("apple.png", "rb") as f:
    resp = client.images.edit(
        model="openai/gpt-image-2",
        image=f,
        prompt="Deixe a maçã verde e mantenha todo o resto igual",
        size="auto",
        quality="low",
    )
 
with open("apple_edited.png", "wb") as out:
    out.write(base64.b64decode(resp.data[0].b64_json))

import OpenAI, { toFile } from 'openai'
import fs from 'node:fs'
 
const client = new OpenAI({
  apiKey: 'YOUR_OFOX_API_KEY',
  baseURL: 'https://api.ofox.io/v1',
  timeout: 600_000, // milissegundos
})
 
const resp = await client.images.edit({
  model: 'openai/gpt-image-2',
  image: await toFile(fs.createReadStream('apple.png'), 'apple.png'),
  prompt: 'Deixe a maçã verde e mantenha todo o resto igual',
  size: 'auto',
  quality: 'low',
})
 
fs.writeFileSync('apple_edited.png', Buffer.from(resp.data[0].b64_json!, 'base64'))

curl -X POST 'https://api.ofox.io/v1/images/edits' \
  --max-time 600 \
  -H 'Authorization: Bearer YOUR_OFOX_API_KEY' \
  -F 'model="openai/gpt-image-2"' \
  -F 'prompt="Deixe a maçã verde e mantenha todo o resto igual"' \
  -F 'image=@/path/to/apple.png' \
  -F 'size="auto"' \
  -F 'quality="low"'

O campo image recebe um caminho de arquivo local (com o prefixo @ no cURL), não uma URL.

Comparação medida:

Original	Editada

Erros

Em caso de erro, a API retorna um status HTTP de erro e a estrutura abaixo (medido):

{
  "error": {
    "code": null,
    "message": "The model 'gpt-image-2' does not support quality 'xhigh'.",
    "param": null,
    "request_id": "fbe4f24c-779d-41a0-8b3a-c62886cdd1ae",
    "type": "image_generation_user_error"
  }
}

code pode ser null. Baseie a lógica no status HTTP e em message.

Ao entrar em contato com o suporte, inclua o request_id da resposta e os detalhes do erro (status HTTP e error.message). Recomendamos registrá-los nos seus logs.

Avançado: fixar um provedor

É opcional e normalmente desnecessário. Os três modelos GPT Image (gpt-image-2.5-flare, gpt-image-2.5-sunburst, gpt-image-2) são atendidos por azure_foundry e openai, tanto na geração quanto na edição. Sem indicação, o gateway faz o roteamento automaticamente.

Selecione um provedor quando houver requisitos de moderação de conteúdo. As requisições passam a ir somente para esse provedor; se ele estiver indisponível, elas não recorrem automaticamente a outro provedor.

Indicar um provedor que não oferece o modelo retorna 400 provider_type_unavailable.

Texto para imagem /v1/images/generations

Corpo JSON; funcionam tanto o campo do corpo extra_body.provider.type quanto o cabeçalho X-OfoxAI-Provider-Type.

resp = client.images.generate(
    model="openai/gpt-image-2",
    prompt="A simple red apple on a white table",
    size="1024x1024",
    extra_body={"extra_body": {"provider": {"type": "openai"}}},
)

const resp = await client.images.generate({
  model: 'openai/gpt-image-2',
  prompt: 'A simple red apple on a white table',
  size: '1024x1024',
  extra_body: { provider: { type: 'openai' } },
})

curl https://api.ofox.io/v1/images/generations \
  -H "Authorization: Bearer $OFOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-image-2",
    "prompt": "...",
    "n": 1,
    "size": "1024x1024",
    "extra_body": { "provider": { "type": "openai" } }
  }'

Imagem para imagem /v1/images/edits

Um upload multipart não tem corpo JSON onde aninhar extra_body; por isso, só é possível usar o cabeçalho.

curl https://api.ofox.io/v1/images/edits \
  -H "Authorization: Bearer $OFOX_API_KEY" \
  -H "X-OfoxAI-Provider-Type: openai" \
  -F "model=openai/gpt-image-2" \
  -F "prompt=..." \
  -F "image=@input.png"

Com os SDKs: em Python, passe extra_headers={"X-OfoxAI-Provider-Type": "openai"}; em TypeScript, passe { headers: { 'X-OfoxAI-Provider-Type': 'openai' } } como segundo argumento.

Referência completa: API · Roteamento de provedores.

Documentação oficial e mais

A documentação oficial descreve o comportamento das chamadas diretas à OpenAI. Quando ela diverge das medições na OfoxAI, prevalecem as medições deste site.

OpenAI (oficial)

• Guia de geração de imagens · Gerar imagens 
• Guia de geração de imagens · Editar imagens 
• Guia de geração de imagens · Edição parcial com máscara 
• Guia de geração de imagens · Tamanho e qualidade 
• Guia de geração de imagens · Cálculo de custos 
• Referência da Images API 

Páginas de família da OfoxAI

• Visão geral da família GPT Image: escolha de modelo, tamanho, qualidade, tempos e erros
• Texto para imagem
• Edição e várias imagens
• Inpainting
• Família Nano Banana (Gemini Image) e solução de erros
• Família Seedream
• Família Qwen-Image
• Família MAI Image