Images API

Dois endpoints: gerar (texto → imagem) e editar (imagem + texto → imagem). As respostas seguem a estrutura padrão da OpenAI em data[0].b64_json.

O que você quer fazer	Endpoint	Modelos suportados
Gerar uma imagem a partir de texto	`POST /v1/images/generations`	`openai/gpt-image-2`, `google/gemini-3.1-flash-image`, `bailian/qwen-image-3.0-pro`
Enviar uma imagem e editá-la com uma instrução	`POST /v1/images/edits`	Somente OpenAI / Azure: `openai/gpt-image-2`, `openai/gpt-image-1.5`

Duas exceções em imagem-para-imagem: a família Qwen faz imagem-para-imagem pelo campo input_images de generations, não de edits; a família Gemini não edita em nenhum dos dois endpoints desta página — use o protocolo nativo do Gemini.

Fixar um provedor

provider.type fixa a requisição em um provedor. Só faz sentido em modelos atendidos por mais de um — hoje openai/gpt-image-2 (azure_foundry e openai). Indicar um provedor que não atende o modelo retorna 400 provider_type_unavailable.

Provedor	Descrição	Moderação de conteúdo
`azure_foundry`	Hospedado no Microsoft Azure	Mais rígida
`openai`	API oficial da OpenAI	Mais permissiva

Os dois provedores de openai/gpt-image-2 não moderam pelo mesmo critério: azure_foundry é mais rígida e openai mais permissiva. Fixe provider.type: "openai" explicitamente quando um prompt for recusado repetidamente — sem isso, a distribuição por peso pode cair em azure_foundry.

Referência completa: API · Roteamento de provedores.

Texto para imagem — `/v1/images/generations`

/v1/images/generations recebe um corpo JSON, então tanto o campo do corpo quanto o cabeçalho funcionam.

Python

gen_pinned.py


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

TypeScript

gen_pinned.ts


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

Terminal


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

Com os SDKs oficiais da OpenAI, extra_body precisa existir como chave literal no corpo da requisição. O SDK de TypeScript envia exatamente como está escrito no objeto de parâmetros. O argumento extra_body= do SDK de Python mescla o conteúdo no nível superior do corpo, então a chave precisa ser aninhada um nível a mais, ou enviada como cabeçalho.

Edição de imagem — `/v1/images/edits`

/v1/images/edits é um upload multipart — não há corpo JSON onde aninhar extra_body, portanto aqui só o cabeçalho funciona. Enviar extra_body como campo de formulário é ignorado e a requisição segue sem a restrição.

Terminal


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"

Em /v1/images/edits, um extra_body enviado como campo de formulário é ignorado silenciosamente — a imagem é gerada sem a restrição. Use X-OfoxAI-Provider-Type.

Gerar imagens


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

Parâmetros

Parâmetro	Tipo	Obrigatório	Descrição
`model`	string	✅	`openai/gpt-image-2`, `google/gemini-3.1-flash-image`, `bailian/qwen-image-3.0-pro`
`prompt`	string	✅	Descrição em linguagem natural
`quality`	string	✅	`auto` / `low` / `medium` / `high` / `standard` / `hd`
`n`	number	—	1–10, padrão 1. Não suportado em modelos Gemini
`size`	string	—	`auto` / `1024x1024` / `1536x1024` / `1024x1536` / `256x256` / `512x512` / `1792x1024` / `1024x1792`
`input_images`	string[]	—	Array de imagens de referência (URL ou base64), 1 a 3, suportado pelos modelos de imagem Qwen; quando aplicado, a resposta inclui `usage.num_input_images`
`output_format`	string	—	`png` / `jpeg` / `webp`
`background`	string	—	`transparent` / `opaque` / `auto`
`stream`	boolean	—	Padrão `false`
`extra_body.provider.type`	string	—	Fixa a requisição em um provedor. Só faz sentido em modelos atendidos por mais de um provedor (neste endpoint, hoje `openai/gpt-image-2`); o cabeçalho `X-OfoxAI-Provider-Type` é equivalente

Resposta


{
  "created": 1777385517,
  "data": [
    { "b64_json": "<Imagem em Base64>", "index": 0 }
  ],
  "model": "openai/gpt-image-2",
  "size": "1024x1024",
  "quality": "low",
  "usage": {
    "input_tokens": 14,
    "input_tokens_details": { "text_tokens": 14 },
    "output_tokens": 208,
    "total_tokens": 222
  }
}

A imagem está em data[0].b64_json. Decodifique o Base64 e salve o arquivo.

Família OpenAI (gpt-image-2)

Python

gen.py


import base64
from openai import OpenAI
 
client = OpenAI(api_key="YOUR_OFOX_API_KEY", base_url="https://api.ofox.io/v1")
 
resp = client.images.generate(
    model="openai/gpt-image-2",
    prompt="A simple red apple on a white table",
    size="1024x1024",
    quality="low",
    output_format="png",
    # Opcional: fixar um provedor. Se omitir, a plataforma faz o roteamento
    # extra_body={"extra_body": {"provider": {"type": "openai"}}},
)
 
with open("output.png", "wb") as f:
    f.write(base64.b64decode(resp.data[0].b64_json))

TypeScript

gen.ts


import OpenAI from 'openai'
import fs from 'node:fs'
 
const client = new OpenAI({ apiKey: 'YOUR_OFOX_API_KEY', baseURL: 'https://api.ofox.io/v1' })
 
const resp = await client.images.generate({
  model: 'openai/gpt-image-2',
  prompt: 'A simple red apple on a white table',
  size: '1024x1024',
  quality: 'low',
  output_format: 'png',
  // Opcional: fixar um provedor. Se omitir, a plataforma faz o roteamento
  // extra_body: { provider: { type: 'openai' } },
})
 
fs.writeFileSync('output.png', Buffer.from(resp.data[0].b64_json!, 'base64'))

cURL

Terminal


# Opcional: fixar um provedor. Se omitir, a plataforma faz o roteamento
# "extra_body": { "provider": { "type": "openai" } }
curl -X POST 'https://api.ofox.io/v1/images/generations' \
  -H 'Authorization: Bearer YOUR_OFOX_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "openai/gpt-image-2",
    "prompt": "A simple red apple on a white table",
    "size": "1024x1024",
    "quality": "low",
    "output_format": "png"
  }'

Saída real:

Maçã vermelha gerada pelo gpt-image-2

Família Gemini (gemini-3.1-flash-image)

O mesmo endpoint também aceita modelos de imagem do Gemini. Não envie n — o gateway mapeia incorretamente n para o campo numberOfImages e retorna 400. Cada chamada gera apenas 1 imagem.

Python

gen_gemini.py


import base64
from openai import OpenAI
 
client = OpenAI(api_key="YOUR_OFOX_API_KEY", base_url="https://api.ofox.io/v1")
 
resp = client.images.generate(
    model="google/gemini-3.1-flash-image",
    prompt="A simple red apple on a white table, photorealistic",
    size="1024x1024",
    quality="low",
    output_format="png",
)
 
with open("output.png", "wb") as f:
    f.write(base64.b64decode(resp.data[0].b64_json))

TypeScript

gen_gemini.ts


import OpenAI from 'openai'
import fs from 'node:fs'
 
const client = new OpenAI({ apiKey: 'YOUR_OFOX_API_KEY', baseURL: 'https://api.ofox.io/v1' })
 
const resp = await client.images.generate({
  model: 'google/gemini-3.1-flash-image',
  prompt: 'A simple red apple on a white table, photorealistic',
  size: '1024x1024',
  quality: 'low',
  output_format: 'png',
})
 
fs.writeFileSync('output.png', Buffer.from(resp.data[0].b64_json!, 'base64'))

cURL

Terminal


curl -X POST 'https://api.ofox.io/v1/images/generations' \
  -H 'Authorization: Bearer YOUR_OFOX_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "google/gemini-3.1-flash-image",
    "prompt": "A simple red apple on a white table, photorealistic",
    "size": "1024x1024",
    "quality": "low"
  }'

Saída real:

Maçã vermelha gerada pelo Gemini

Família Qwen (qwen-image-3.0-pro)

Modelos de imagem Qwen como bailian/qwen-image-3.0-pro aceitam imagens de referência para imagem-para-imagem e edição diretamente neste endpoint (1 a 3 imagens), pelo campo input_images (cada elemento é uma URL de imagem ou uma string base64):

Terminal


curl -X POST 'https://api.ofox.io/v1/images/generations' \
  -H 'Authorization: Bearer YOUR_OFOX_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "bailian/qwen-image-3.0-pro",
    "prompt": "Deixe a maçã azul e mantenha o resto igual",
    "size": "1024x1024",
    "input_images": ["https://example.com/ref-apple.png"]
  }'

Quando as imagens de referência têm efeito, a resposta usage inclui num_input_images (o número de imagens de entrada) — use-o para confirmar programaticamente que o modelo as leu.

O campo precisa se chamar input_images. Outras grafias como image_urls, image ou images são ignoradas silenciosamente e a requisição vira texto-para-imagem puro (o HTTP continua 200).

Editar imagens


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

multipart/form-data, exige o upload do arquivo de imagem.

Este endpoint só suporta modelos OpenAI / Azure OpenAI. Chamar google/gemini-3.1-flash-image retorna Image editing is not supported for model — use o protocolo nativo do Gemini para editar imagens.

Parâmetros

Parâmetro	Tipo	Obrigatório	Descrição
`model`	string	✅	Recomendado `openai/gpt-image-2`
`image`	file	✅	Arquivo PNG / JPEG
`prompt`	string	✅	Instrução de edição
`quality`	string	✅	`low` / `medium` / `high`
`n`	number	—	Padrão 1
`size`	string	—	`auto` mantém o tamanho original
`X-OfoxAI-Provider-Type`	cabeçalho	—	Fixa a requisição em um provedor. Este endpoint é um upload multipart, então só o cabeçalho funciona — um campo de formulário `extra_body` é ignorado silenciosamente

Resposta

Idêntica à de geração:


{
  "created": 1777385669,
  "data": [
    { "b64_json": "<Imagem editada em Base64>", "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
  }
}

usage.input_tokens_details.image_tokens são os tokens consumidos pela imagem de entrada; num_input_images é a quantidade de imagens enviadas.

Modelos suportados e preços em Catálogo de Modelos .

Chamada

Python

edit.py


import base64
from openai import OpenAI
 
client = OpenAI(api_key="YOUR_OFOX_API_KEY", base_url="https://api.ofox.io/v1")
 
with open("apple.png", "rb") as f:
    resp = client.images.edit(
        model="openai/gpt-image-2",
        image=f,
        prompt="Mude a maçã para verde, mantenha o resto inalterado",
        size="auto",
        quality="low",
        # Opcional: fixar um provedor. Este endpoint é multipart, então só o cabeçalho funciona
        # extra_headers={"X-OfoxAI-Provider-Type": "openai"},
    )
 
with open("apple_edited.png", "wb") as out:
    out.write(base64.b64decode(resp.data[0].b64_json))

TypeScript

edit.ts


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' })
 
// Opcional: fixar um provedor. Este endpoint é multipart, então só o cabeçalho funciona
// passe { headers: { 'X-OfoxAI-Provider-Type': 'openai' } } como segundo argumento
const resp = await client.images.edit({
  model: 'openai/gpt-image-2',
  image: await toFile(fs.createReadStream('apple.png'), 'apple.png'),
  prompt: 'Mude a maçã para verde, mantenha o resto inalterado',
  size: 'auto',
  quality: 'low',
})
 
fs.writeFileSync('apple_edited.png', Buffer.from(resp.data[0].b64_json!, 'base64'))

cURL

Terminal


# Opcional: fixar um provedor. Este endpoint é multipart, então só o cabeçalho funciona
# -H 'X-OfoxAI-Provider-Type: openai' \
curl -X POST 'https://api.ofox.io/v1/images/edits' \
  -H 'Authorization: Bearer YOUR_OFOX_API_KEY' \
  -F 'model="openai/gpt-image-2"' \
  -F 'prompt="Mude a maçã para verde, mantenha o resto inalterado"' \
  -F 'image=@/path/to/apple.png' \
  -F 'size="auto"' \
  -F 'quality="low"'

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

Comparação real:

Original	Editada

Images API

Fixar um provedor

Texto para imagem — /v1/images/generations

Python

TypeScript

cURL

Edição de imagem — /v1/images/edits

Gerar imagens

Parâmetros

Resposta

Família OpenAI (gpt-image-2)

Python

TypeScript

cURL

Família Gemini (gemini-3.1-flash-image)

Python

TypeScript

cURL

Família Qwen (qwen-image-3.0-pro)

Editar imagens

Parâmetros

Resposta

Chamada

Python

TypeScript

cURL

Texto para imagem — `/v1/images/generations`

Edição de imagem — `/v1/images/edits`