Images API

Dos endpoints: generación (texto → imagen) y edición (imagen + texto → imagen). Las respuestas siguen la estructura estándar de OpenAI data[0].b64_json.

Lo que quieres hacer	Endpoint	Modelos compatibles
Generar una imagen a partir de texto	`POST /v1/images/generations`	`openai/gpt-image-2`, `google/gemini-3.1-flash-image`, `bailian/qwen-image-3.0-pro`
Subir una imagen y editarla con una instrucción	`POST /v1/images/edits`	Solo OpenAI / Azure: `openai/gpt-image-2`, `openai/gpt-image-1.5`

Dos excepciones en imagen-a-imagen: la familia Qwen hace imagen-a-imagen mediante el campo input_images de generations, no de edits; la familia Gemini no puede editar en ninguno de los dos endpoints de esta página — usa el protocolo nativo de Gemini.

Fijar un proveedor

provider.type fija la petición a un proveedor. Solo tiene sentido en modelos servidos por más de uno — hoy openai/gpt-image-2 (azure_foundry y openai). Indicar un proveedor que no sirve el modelo devuelve 400 provider_type_unavailable.

Proveedor	Descripción	Moderación de contenido
`azure_foundry`	Alojado en Microsoft Azure	Más estricta
`openai`	API oficial de OpenAI	Más permisiva

Los dos proveedores de openai/gpt-image-2 no moderan con el mismo criterio: azure_foundry es más estricta y openai más permisiva. Fija provider.type: "openai" de forma explícita si un prompt se rechaza repetidamente; sin eso, el reparto ponderado puede llevarte a azure_foundry.

Referencia completa: API · Enrutamiento de proveedores.

Texto a imagen — `/v1/images/generations`

/v1/images/generations recibe un cuerpo JSON, así que funcionan tanto el campo del cuerpo como la cabecera.

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

Con los SDK oficiales de OpenAI, extra_body debe estar presente como clave literal en el cuerpo de la petición. El SDK de TypeScript lo envía tal como se escribe en el objeto de parámetros. El argumento extra_body= del SDK de Python fusiona su contenido en el nivel superior del cuerpo, por lo que la clave debe anidarse un nivel más, o enviarse como cabecera.

Edición de imagen — `/v1/images/edits`

/v1/images/edits es una subida multipart: no hay cuerpo JSON donde anidar extra_body, por lo que aquí solo funciona la cabecera. Enviar extra_body como campo de formulario se ignora y la petición sigue sin la restricción.

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"

En /v1/images/edits, un extra_body enviado como campo de formulario se ignora en silencio: la imagen se genera sin la restricción. Usa X-OfoxAI-Provider-Type.

Generar imágenes


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

Parámetros

Parámetro	Tipo	Obligatorio	Descripción
`model`	string	Sí	`openai/gpt-image-2`, `google/gemini-3.1-flash-image`, `bailian/qwen-image-3.0-pro`
`prompt`	string	Sí	Descripción en lenguaje natural
`quality`	string	Sí	`auto` / `low` / `medium` / `high` / `standard` / `hd`
`n`	number	—	1–10, valor predeterminado 1. No compatible con modelos Gemini
`size`	string	—	`auto` / `1024x1024` / `1536x1024` / `1024x1536` / `256x256` / `512x512` / `1792x1024` / `1024x1792`
`input_images`	string[]	—	Array de imágenes de referencia (URL o base64), de 1 a 3, compatible con los modelos de imagen Qwen; cuando aplica, la respuesta incluye `usage.num_input_images`
`output_format`	string	—	`png` / `jpeg` / `webp`
`background`	string	—	`transparent` / `opaque` / `auto`
`stream`	boolean	—	Predeterminado `false`
`extra_body.provider.type`	string	—	Fija la petición a un proveedor. Solo tiene sentido en modelos servidos por más de un proveedor (en este endpoint, hoy `openai/gpt-image-2`); la cabecera `X-OfoxAI-Provider-Type` es equivalente

Respuesta


{
  "created": 1777385517,
  "data": [
    { "b64_json": "<imagen 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
  }
}

La imagen está en data[0].b64_json; decodifícala desde base64 y guárdala.

Familia 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: fijar un proveedor. Si lo omites, la plataforma enruta por ti
    # 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: fijar un proveedor. Si lo omites, la plataforma enruta por ti
  // extra_body: { provider: { type: 'openai' } },
})
 
fs.writeFileSync('output.png', Buffer.from(resp.data[0].b64_json!, 'base64'))

cURL

Terminal


# Opcional: fijar un proveedor. Si lo omites, la plataforma enruta por ti
# "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"
  }'

Resultado real:

Manzana roja generada por gpt-image-2

Familia Gemini (gemini-3.1-flash-image)

El mismo endpoint también acepta modelos de imagen de Gemini. No envíes n: el gateway lo mapea por error al campo numberOfImages y devuelve 400. Cada llamada genera 1 imagen.

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

Resultado real:

Manzana roja generada por Gemini

Familia Qwen (qwen-image-3.0-pro)

Los modelos de imagen Qwen como bailian/qwen-image-3.0-pro aceptan imágenes de referencia para imagen-a-imagen y edición directamente en este endpoint (de 1 a 3 imágenes), mediante el campo input_images (cada elemento es una URL de imagen o una cadena 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": "Pon la manzana azul y deja el resto igual",
    "size": "1024x1024",
    "input_images": ["https://example.com/ref-apple.png"]
  }'

Cuando las imágenes de referencia surten efecto, la respuesta usage incluye num_input_images (el número de imágenes de entrada), útil para confirmar por programa que el modelo las ha leído.

El campo debe llamarse input_images. Otras grafías como image_urls, image o images se ignoran en silencio y la petición se degrada a texto-a-imagen puro (el HTTP sigue siendo 200).

Editar imágenes


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

multipart/form-data, requiere subir un archivo de imagen.

Este endpoint solo admite modelos OpenAI / Azure OpenAI. Llamar a google/gemini-3.1-flash-image devolverá Image editing is not supported for model. Usa el protocolo nativo de Gemini para editar imágenes.

Parámetros

Parámetro	Tipo	Obligatorio	Descripción
`model`	string	Sí	Recomendado `openai/gpt-image-2`
`image`	file	Sí	Archivo PNG / JPEG
`prompt`	string	Sí	Instrucción de edición
`quality`	string	Sí	`low` / `medium` / `high`
`n`	number	—	Predeterminado 1
`size`	string	—	`auto` mantiene el tamaño del original
`X-OfoxAI-Provider-Type`	cabecera	—	Fija la petición a un proveedor. Este endpoint es una subida multipart, así que solo funciona la cabecera: un campo de formulario `extra_body` se ignora en silencio

Respuesta

Igual que la generación:


{
  "created": 1777385669,
  "data": [
    { "b64_json": "<imagen editada 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 es el consumo de tokens de la imagen de entrada y num_input_images es el número de imágenes de entrada.

Consulta los modelos compatibles y precios en el catálogo de modelos .

Llamada

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="Cambia la manzana a verde, mantén todo lo demás igual",
        size="auto",
        quality="low",
        # Opcional: fijar un proveedor. Este endpoint es multipart, solo funciona la cabecera
        # 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: fijar un proveedor. Este endpoint es multipart, solo funciona la cabecera
// pasa { 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: 'Cambia la manzana a verde, mantén todo lo demás igual',
  size: 'auto',
  quality: 'low',
})
 
fs.writeFileSync('apple_edited.png', Buffer.from(resp.data[0].b64_json!, 'base64'))

cURL

Terminal


# Opcional: fijar un proveedor. Este endpoint es multipart, solo funciona la cabecera
# -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="Cambia la manzana a verde, mantén todo lo demás igual"' \
  -F 'image=@/path/to/apple.png' \
  -F 'size="auto"' \
  -F 'quality="low"'

El campo image recibe una ruta de archivo local (cURL usa el prefijo @), no una URL.

Comparación real:

Original	Editada

Images API

Fijar un proveedor

Texto a imagen — /v1/images/generations

Python

TypeScript

cURL

Edición de imagen — /v1/images/edits

Generar imágenes

Parámetros

Respuesta

Familia OpenAI (gpt-image-2)

Python

TypeScript

cURL

Familia Gemini (gemini-3.1-flash-image)

Python

TypeScript

cURL

Familia Qwen (qwen-image-3.0-pro)

Editar imágenes

Parámetros

Respuesta

Llamada

Python

TypeScript

cURL

Texto a imagen — `/v1/images/generations`

Edición de imagen — `/v1/images/edits`