GPT Image 2 Generación de imágenes

El modelo GPT Image 2 (gpt-image-2) soporta modos de generación de texto a imagen, imagen a imagen, edición de imagen y otros

Modo de procesamiento asíncrono, usa el ID de tarea devuelto para consultar
Los enlaces de imágenes generadas son válidos por 24 horas, guárdalos oportunamente

Autorización

AuthorizationstringheaderObligatorio

##Todas las APIs requieren autenticación Bearer Token## **Obtener API Key:** Visita la [Página de gestión de API Key](https://starmagic.ai/app/api-keys) para obtener tu API Key **Agregar al encabezado de la solicitud:** ``` Authorization: Bearer YOUR_API_KEY ```

Authorization: Bearer YOUR_API_KEY

Cuerpo de solicitud

application/json

modelenum<gpt-image-2>Obligatorio

Nombre del modelo de generación de imágenes, canal oficial, mejor estabilidad y controlabilidad, adecuado para escenarios comerciales

"gpt-image-2"

promptstringObligatorio

Prompt que describe la imagen a generar, o que describe cómo editar la imagen de entrada **Límites:** - Hasta `32000` caracteres (contados por puntos de código Unicode, válido para CJK y otros idiomas)

"Una hermosa puesta de sol colorida sobre el océano"

image_urlsstring<uri>[]

Lista de URLs de imagen de referencia para funciones de imagen a imagen y edición de imagen **Nota:** - Número de imágenes de entrada por solicitud: `1~16` - Tamaño de una sola imagen: no más de `50MB` - Formatos de archivo admitidos: `.jpeg`, `.jpg`, `.png`, `.webp` - Las URLs de imagen deben ser directamente accesibles por el servidor, o la URL de imagen debe activar la descarga directa al acceder (generalmente estas URLs terminan con extensiones de archivo de imagen, como `.png`, `.jpg`) - En escenarios de imagen a imagen / edición de imagen, las imágenes de referencia enviadas generan consumo adicional de tokens de imagen de entrada

[
  "https://example.com/image1.png",
  "https://example.com/image2.png"
]

mask_urlstring<uri>

URL de la máscara de inpainting — marca la región de la imagen de referencia que se va a regenerar. **Solo válida en modo de edición de imagen** (debe combinarse con `image_urls`); en texto-a-imagen puro, la máscara se ignora silenciosamente. **Requisitos de formato:** - **Debe ser un PNG con canal alfa**: píxeles transparentes (`alpha < 255`) = áreas a regenerar, píxeles opacos = preservados - **Las dimensiones de la máscara deben coincidir exactamente con las de la imagen de referencia** (ancho × alto en píxeles) - Una máscara por solicitud **Nota:** - Se requiere al menos una imagen de referencia en `image_urls`; una máscara sola no tiene efecto - Errores comunes: - `Invalid mask image format - mask image missing alpha channel`: la imagen subida no tiene canal alfa (JPEG, PNG opaco, etc.). Reexporta la máscara como PNG con regiones transparentes. - `Invalid mask image format - mask size does not match image size`: las dimensiones de la máscara no coinciden con la imagen de referencia. Redimensiona la máscara a las mismas dimensiones en píxeles que tu imagen de referencia.

"https://example.com/mask.png"

sizestring

Tamaño de la imagen generada. Admite **formato de proporción** y **formato de píxeles explícito**, por defecto `auto` **① Formato de proporción (recomendado, 15 opciones)** - `1:1`: Cuadrado - `1:2` / `2:1`: Vertical / horizontal extremo - `1:3` / `3:1`: Ultra vertical / horizontal (límite 3:1) - `2:3` / `3:2`: Vertical / horizontal estándar - `3:4` / `4:3`: Vertical / horizontal clásico - `4:5` / `5:4`: Comunes en redes sociales - `9:16` / `16:9`: Pantalla ancha móvil / escritorio - `9:21` / `21:9`: Ultra-ancha **② Formato de píxeles explícito**: `WxH` (o `W×H`), p. ej. `1024x1024`, `1536x1024`, `3840×2160` - Ancho y alto deben ser múltiplos de `16` - Rango de cada borde: `[16, 3840]` - Presupuesto de píxeles: `655.360 ≤ width × height ≤ 8.294.400` (aprox. 0,65 MP ~ 8,29 MP) - Relación de aspecto: `≤ 3:1` **③ `auto`**: El modelo decide el tamaño automáticamente (en este caso `resolution` no se aplica) **Manejo de desbordamiento:** - Si una combinación de proporción + `resolution` excede el presupuesto de píxeles, las dimensiones se reducen proporcionalmente al máximo permitido (p. ej. 4K 2:1 → 3840×1920)

"auto"

resolutionenum<1K | 2K | 4K>

Parámetro rápido de nivel de resolución, solo efectivo cuando `size` está en formato de proporción; en formato de píxeles explícito este campo se ignora **Reglas de presupuesto de píxeles** (las dimensiones se calculan a partir del recuento total de píxeles objetivo y la proporción de `size`, alineadas a múltiplos de 16): - `1K`: ~1 MP (1024² = 1.048.576 píxeles) - `2K`: ~4 MP (2048² = 4.194.304 píxeles) - `4K`: ~8,29 MP (3840×2160 = 8.294.400 píxeles, el máximo) **Tamaños de salida horizontal / cuadrado** (los tamaños verticales son el horizontal con ancho/alto intercambiados, p. ej. `2:3` = `3:2` invertido): | Proporción | 1K | 2K | 4K | |---|---|---|---| | `1:1` | 1024×1024 | 2048×2048 | 2880×2880 | | `2:1` | 1456×720 | 2896×1456 | 3840×1920 \* | | `3:1` | 1776×592 | 3552×1184 | 3840×1280 \* | | `3:2` | 1248×832 | 2512×1680 | 3520×2352 | | `4:3` | 1184×880 | 2368×1776 | 3312×2480 \* | | `5:4` | 1152×912 | 2288×1824 | 3216×2576 | | `16:9` | 1360×768 | 2736×1536 | 3840×2160 (UHD) | | `21:9` | 1568×672 | 3136×1344 | 3840×1632 \* | \* Indica combinaciones que se reducen automáticamente para caber en el presupuesto de píxeles. Los valores no distinguen mayúsculas/minúsculas.

"1K"

qualityenum<low | medium | high>

Calidad de renderizado, controla la "profundidad de razonamiento" del modelo, afecta directamente el número de tokens de salida y el costo. Por defecto `medium` | Valor | Base de tile | Costo relativo (1024²) | |---|---|---| | `low` | 16 | ~0,11× | | `medium` | 48 | 1,0× | | `high` | 96 | ~4,0× |

"medium"

ninteger

Cantidad de imágenes a generar, cada una facturada de forma independiente **Nota:** - Los tokens de entrada de texto escalan proporcionalmente con `n`

callback_urlstring<uri>

Dirección de callback HTTPS después de completar la tarea **Momento del callback:** - Se activa cuando la tarea se completa, falla o se cancela - Se envía después de completar la confirmación de facturación **Restricciones de seguridad:** - Solo se admite el protocolo HTTPS - El callback a direcciones IP internas está prohibido (127.0.0.1, 10.x.x.x, 172.16-31.x.x, 192.168.x.x, etc.) - La longitud de la URL no debe exceder `2048` caracteres **Mecanismo de callback:** - Tiempo de espera: `10` segundos - Máximo `3` reintentos en caso de fallo (reintentos después de `1` segundo/`2` segundos/`4` segundos) - El formato del cuerpo de respuesta del callback es consistente con el formato de respuesta de la API de consulta de tareas - La dirección de callback que devuelve un código de estado 2xx se considera exitosa, otros códigos de estado activarán reintentos

"https://your-domain.com/webhooks/image-task-completed"

Respuesta

application/json

成功

Cuerpo de respuesta

createdinteger

Marca de tiempo de creación de la tarea

1757156493

idstring

ID de tarea

"task-unified-1757156493-imcg5zqt"

modelstring

Nombre del modelo usado realmente

"gpt-image-2"

objectenum<image.generation.task>

Tipo específico de tarea

"image.generation.task"

progressinteger

Porcentaje de progreso de la tarea (0-100)

statusenum<pending | processing | completed | failed>

Estado de la tarea

"pending"

task_infoobject

{
  "can_cancel": true,
  "estimated_time": 100
}

typeenum<text | image | audio | video>

Tipo de salida de la tarea

"image"

usageobject

Información de uso y facturación

{
  "billing_rule": "per_call",
  "credits_reserved": 2.5,
  "user_group": "default"
}

POST/v1/images/generations

curl --request POST \
  --url https://api.starmagic.ai/v1/images/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "gpt-image-2",
  "prompt": "Una hermosa puesta de sol colorida sobre el océano"
}'

Respuesta: 成功

{
  "created": 1757156493,
  "id": "task-unified-1757156493-imcg5zqt",
  "model": "gpt-image-2",
  "object": "image.generation.task",
  "progress": 0,
  "status": "pending",
  "task_info": {
    "can_cancel": true,
    "estimated_time": 100
  },
  "type": "image",
  "usage": {
    "billing_rule": "per_call",
    "credits_reserved": 2.5,
    "user_group": "default"
  }
}