Images API

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

Seedream y Qwen-Image no admiten /v1/images/edits: la generación de imagen a imagen se hace en el endpoint generations, pero el campo de la imagen de referencia es distinto: Seedream usa image y Qwen usa input_images; no los confunda. Si necesita controlar la resolución de Gemini (de 512 a 4K), utilice el protocolo nativo de Gemini. Las diferencias de parámetros de cada familia se detallan en su página.

Inicio rápido

Una petición mínima ejecutable: genera una imagen de 1024×1024, la decodifica y la guarda 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,  # la API de imágenes es síncrona y puede tardar
)
 
resp = client.images.generate(
    model="openai/gpt-image-2.5-flare",
    prompt="Una manzana roja sobre una mesa blanca",
    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": "Una manzana roja sobre una mesa blanca",
    "size": "1024x1024",
    "quality": "low"
  }' | jq -r '.data[0].b64_json' | base64 --decode > output.png

Todas las familias se llaman de la misma forma; para cambiar de modelo solo cambia model. Los valores admitidos y los parámetros propios de cada familia varían; consulte cada parámetro a continuación.

Generar imágenes

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

Parámetros de la petición

Los valores admitidos y los valores predeterminados siguientes corresponden a la familia GPT Image (gpt-image-2.5-flare, gpt-image-2.5-sunburst, gpt-image-2). Cuando otras familias difieren, se indica aparte. Detalles medidos: familia GPT Image.

Respuesta

{
  "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 imágenes

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

Parámetros de la petición

multipart/form-data: se envían como campos de formulario y requieren subir un archivo de imagen. Los valores admitidos y los valores predeterminados también corresponden a la familia GPT Image.

Respuesta

Misma estructura que en el endpoint de generación; usage añade los tokens de entrada de las imágenes de referencia:

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

Los demás campos son iguales que en la respuesta del endpoint de generación.

Llamada

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="Cambia la manzana a color verde y deja todo lo demás 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, // milisegundos
})
 
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 color verde y deja todo lo demás 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="Cambia la manzana a color verde y deja 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 (con el prefijo @ en cURL), no una URL.

Comparación medida:

Original	Editada

Errores

En caso de error se devuelve un código de estado HTTP de error y la siguiente estructura (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 puede ser null. Base la lógica en el código de estado HTTP y en message.

Al contactar con soporte, incluya el request_id de la respuesta y los detalles del error (código de estado HTTP y error.message). Se recomienda registrarlos en sus logs.

Avanzado: fijar un proveedor

Es opcional y normalmente innecesario. Los tres modelos GPT Image (gpt-image-2.5-flare, gpt-image-2.5-sunburst, gpt-image-2) los sirven tanto azure_foundry como openai, y ambos admiten generación y edición. Si no se indica, el gateway enruta automáticamente.

Puede fijar un proveedor si tiene requisitos de moderación de contenido. Las peticiones irán entonces solo a ese proveedor; si no está disponible, no se redirigirán automáticamente a otro.

Indicar un proveedor que no sirve el modelo devuelve 400 provider_type_unavailable.

Texto a imagen /v1/images/generations

Cuerpo JSON: funcionan tanto el campo del cuerpo extra_body.provider.type como la cabecera 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" } }
  }'

Imagen a imagen /v1/images/edits

Es una subida multipart y no hay cuerpo JSON donde anidar extra_body, por lo que solo se puede usar la cabecera.

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"

Con los SDK: en Python, pase extra_headers={"X-OfoxAI-Provider-Type": "openai"}; en TypeScript, pase { headers: { 'X-OfoxAI-Provider-Type': 'openai' } } como segundo argumento.

Referencia completa: API · Enrutamiento de proveedores.

Documentación oficial y más recursos

La documentación oficial describe el comportamiento al llamar directamente a OpenAI. Cuando difiere de lo medido en OfoxAI, prevalecen las mediciones de este sitio.

Documentación oficial de OpenAI

• Guía de generación de imágenes · Generar imágenes 
• Guía de generación de imágenes · Editar imágenes 
• Guía de generación de imágenes · Edición parcial con máscara 
• Guía de generación de imágenes · Tamaño y calidad 
• Guía de generación de imágenes · Cálculo de costes 
• Referencia de la Images API 

Páginas de familias de OfoxAI

• Descripción general de la familia GPT Image: elección de modelo, tamaño, calidad, tiempos y errores
• Texto a imagen
• Edición y múltiples imágenes
• Repintado parcial
• Familia Nano Banana (Gemini Image) y solución de errores
• Familia Seedream
• Familia Qwen-Image
• Familia MAI Image