Documentación de GPT Image API

Descripción general

GPT Image API te ofrece generación y edición de imágenes detrás de una sola cuenta y una sola clave de API. Las solicitudes usan campos familiares de estilo OpenAI (model, prompt, size, quality), lo que reduce el coste de migración, mientras los proveedores de modelos quedan abstraídos detrás de una superficie de API estable. GPT Image 2 está diseñado para imágenes con mucho texto: la ortografía, la ubicación y el texto pequeño o denso deben revisarse antes de publicar.

Inicio rápido

1. Crea una clave de API

Inicia sesión en el panel y crea una clave desde Configuración → Claves de API. Guarda el valor en el entorno de tu servidor y nunca lo expongas en código del lado del navegador.

GPT_IMAGE_API_KEY=sk_...

2. Elige un modelo

3. Haz tu primera solicitud

curl https://api.gptimageapi.dev/v1/images/generations \
  -H "Authorization: Bearer $GPT_IMAGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "A cinematic product photo of a ceramic coffee cup",
    "size": "1:1"
  }'

Las respuestas exitosas devuelven las URLs de los activos generados en data[].url.

Autenticación

GPT Image API usa claves de API con autenticación estándar Bearer.

Authorization: Bearer $GPT_IMAGE_API_KEY

Seguridad de la clave:

• Nunca pongas una clave de API en JavaScript del lado del cliente: llama a GPT Image API desde tu backend.
• Rota las claves desde Configuración → Claves de API cuando un compañero se vaya o un secreto quede expuesto.
• Usa claves separadas para desarrollo, pruebas y producción.

Las credenciales inválidas o ausentes devuelven 401 Unauthorized:

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid API key."
  }
}

Endpoints

Las solicitudes de imagen admiten los endpoints síncronos compatibles con OpenAI. Las tareas de imagen de larga duración se pueden enviar de forma asíncrona y consultarse con GET /v1/tasks/{id} hasta que alcancen completed o failed.

Generación de imágenes

POST /v1/images/generations

Edición de imágenes

POST /v1/images/edits

Obtener resultado de tarea

GET /v1/tasks/{id}

Estados de tarea: submitted, processing, completed o failed. Cada tarea reporta progress de 0 a 100 y un credits_cost al completarse.

Formato de respuesta

Las respuestas de imagen siguen la forma de OpenAI:

{
  "created": 1766880000,
  "data": [
    {
      "url": "https://cdn.gptimageapi.dev/generated/image.png"
    }
  ]
}

Las tareas devuelven un id de tarea inmediatamente:

{
  "status": "submitted",
  "id": "task_01KPQ7J7DWB7QZ3WCEK3YVPBRA",
  "progress": 0,
  "created_at": 1703884800,
  "model": "gpt-image-2"
}

Niveles de calidad y créditos

Cuando el modelo admite estos parámetros, el costo en créditos depende del tamaño de salida y del nivel de calidad:

quality=auto se factura como high y size=auto usa el nivel 1K por defecto. La disponibilidad y las reglas de créditos pueden cambiar; consulta la página de precios antes de solicitudes de producción y revisa la actividad en Créditos.

Errores

Reintenta solo los errores transitorios (429, 500, 503) con retroceso exponencial. Ante 402 insufficient_credits, dirige a los usuarios a Créditos o Facturación para que lo resuelvan sin salir de tu flujo de producto.

Ejemplos de código

Node.js

const response = await fetch('https://api.gptimageapi.dev/v1/images/generations', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.GPT_IMAGE_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'gpt-image-2',
    prompt: 'A cinematic product photo of a ceramic coffee cup',
    size: '1:1',
  }),
});

if (!response.ok) {
  throw new Error(await response.text());
}

const result = await response.json();
console.log(result.data?.[0]?.url ?? result);

Python

import os
import requests

response = requests.post(
    "https://api.gptimageapi.dev/v1/images/generations",
    headers={
        "Authorization": f"Bearer {os.environ['GPT_IMAGE_API_KEY']}",
        "Content-Type": "application/json",
    },
    json={
        "model": "gpt-image-2",
        "prompt": "A cinematic product photo of a ceramic coffee cup",
        "size": "1:1",
    },
)

response.raise_for_status()
result = response.json()
print(result["data"][0]["url"])

Generación asíncrona de imágenes (Node.js)

Envía la tarea y consulta GET /v1/tasks/{id} hasta que se complete:

// 1. Envía la tarea asíncrona
const submit = await fetch('https://api.gptimageapi.dev/v1/async/images/generations', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.GPT_IMAGE_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'gpt-image-2',
    prompt: 'A cinematic product photo of a ceramic coffee cup',
    size: '1:1',
  }),
});
const task = await submit.json();
console.log(task.id); // task_01KPQ7J7DWB7QZ3WCEK3YVPBRA

// 2. Consulta hasta que se complete
let status = task.status;
while (status === 'submitted' || status === 'processing') {
  await new Promise((resolve) => setTimeout(resolve, 2000));
  const poll = await fetch(`https://api.gptimageapi.dev/v1/tasks/${task.id}`, {
    headers: { Authorization: `Bearer ${process.env.GPT_IMAGE_API_KEY}` },
  });
  const result = await poll.json();
  status = result.status;
  if (status === 'completed') {
    console.log(result.result?.data?.[0]?.url ?? result);
  } else if (status === 'failed') {
    throw new Error(result.error?.message ?? 'Task failed');
  }
}

Generación asíncrona de imágenes (Python)

import os
import time
import requests

headers = {"Authorization": f"Bearer {os.environ['GPT_IMAGE_API_KEY']}"}

# 1. Envía la tarea asíncrona
submit = requests.post(
    "https://api.gptimageapi.dev/v1/async/images/generations",
    headers={**headers, "Content-Type": "application/json"},
    json={
        "model": "gpt-image-2",
        "prompt": "A cinematic product photo of a ceramic coffee cup",
        "size": "1:1",
    },
)
submit.raise_for_status()
task = submit.json()
print(task["id"])

# 2. Consulta hasta que se complete
while task["status"] in ("submitted", "processing"):
    time.sleep(2)
    task = requests.get(f"https://api.gptimageapi.dev/v1/tasks/{task['id']}", headers=headers).json()

if task["status"] == "completed":
    print(task["result"]["data"][0]["url"])
else:
    raise RuntimeError(task.get("error", {}).get("message", "Task failed"))

Siguientes pasos

• Prueba el Playground para experimentar con prompts antes de escribir código.
• Revisa Precios para conocer los paquetes de créditos y los costos actuales.
• Gestiona claves, créditos y registros de uso en el panel.