aisplice

Referencia de la API

Imágenes: tareas asíncronas

Modelos de este endpoint (12)

gpt-image-2.5-extgpt-image-2seedream-5-0-flashgpt-image-2.5-flare+8
Pruébalo en Workbench
POST/v1/images/tasks
GET/v1/images/tasks/{task_id}
GET/v1/images/tasks/{task_id}/content

Generación de imágenes asíncrona — la ruta que usan todos los modelos de imagen del catálogo. El envío devuelve un task_id; consulta el endpoint de estado y luego lee las URL persistentes del resultado en /content — o registra un webhook y evita las consultas.

#Parámetros de la solicitud

  • modelstringobligatorio

    Un ID de modelo de imagen asíncrono, p. ej. gpt-image-2. Los modelos solo síncronos rechazan este endpoint.

  • promptstringobligatorio

    Qué dibujar.

  • sizestringopcional

    Proporción predefinida como "16:9" — la que usan la mayoría de los modelos de imagen; los valores exactos están en la ficha del modelo. Algunos modelos más antiguos también aceptan WIDTHxHEIGHT.

  • resolutionstringopcional

    Nivel de resolución de salida como "1K", "2K" o "4K", cuando la ficha del modelo lo incluye — también una dimensión del nivel de precio.

  • qualitystringopcional

    Nivel de calidad del proveedor (p. ej. standard / hd) — también una dimensión del nivel de precio.

  • nintegeropcional

    Número de imágenes (la facturación se multiplica por imagen).

  • imagesarrayopcional

    Imágenes de referencia para editar o seguir, como URL o data URI. La ficha del modelo indica cuántas admite cada modelo.

  • maskstringopcional

    Vuelve a pintar una zona de la primera imagen de referencia; consulta «Editar una parte de una imagen» más abajo. Solo la admiten los modelos cuya ficha incluye mask; mask_url se acepta como el mismo campo.

  • webhook_urlstringopcional

    URL HTTPS a la que se llama cuando la tarea llega a un estado final — consulta la guía de video para conocer el contrato del callback.

  • webhook_secretstringopcional

    Si se define, las entregas incluyen X-Xiaoxiang-Signature: sha256=hex(HMAC-SHA256(body, secret)).

Los parámetros varían según el modelo

Consulta la ficha del modelo para ver los campos y valores que admite cada modelo. gpt-image-2.5-ext recibe size como proporción más resolution; un tamaño en píxeles como 2560x1088 se ajusta a la proporción y la resolución más cercanas (21:9 a 2K). No permite controlar background: "auto" se ignora y los demás valores se rechazan. Genera una imagen por solicitud y no permite elegir version: omítelo o envía "flare".

Los nombres de campo pueden variar según la familia de modelos

Los payloads de estado de las tareas reflejan lo que informa el proveedor upstream; toma tus respuestas reales como referencia y apóyate en task_id, status y el endpoint /content, que son estables entre proveedores.

#Editar una parte de una imagen

Envía la imagen en images y una mask: solo se vuelve a dibujar la zona enmascarada y el resto de la imagen queda igual. Indica en prompt qué debe aparecer ahí. Hoy admiten máscara gpt-image-2.5-flare y gpt-image-2.5-sunburst; la ficha del modelo la muestra como el campo mask.

curl https://www.aisplice.store/v1/images/tasks \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.5-flare",
    "prompt": "Replace the mug with a glass of orange juice; keep everything else",
    "images": ["https://example.com/desk.png"],
    "mask": "https://example.com/desk-mask.png",
    "resolution": "1K"
  }'

Cómo crear la máscara

Un PNG con canal alfa: los píxeles totalmente transparentes marcan la zona que se vuelve a dibujar y el resto se conserva. Debe tener exactamente el tamaño en píxeles de la primera imagen de referencia (no el de la salida) y pesar menos de 4 MB. Una máscara por solicitud; con varias imágenes de referencia se aplica a la primera. En los modelos gpt-image-2.5, omite size para que el resultado conserve la proporción de la imagen.
  • 400 invalid_requestSe envió mask sin imagen de referencia, o a un modelo que no admite máscara (gpt-image-2.5-ext responde "mask is not supported on Ext").

Tabla completa de códigos de error →

#Errores relacionados

  • 404 not_foundRuta desconocida, nombre de modelo desconocido, o un task_id caducado o de otra cuenta.
  • 401Bearer token no válido o ausente. Esta ruta no tiene error.code — compara por el estado.
  • 402 insufficient_user_quotaEl saldo de la billetera no cubre la estimación reservada previamente.
  • 429Limitación por clave. Cuerpo vacío; espera el Retry-After. Un 429 que sí incluye insufficient_user_quota indica en cambio un límite de gasto diario.
  • 503 model_not_foundModelo desconocido, o ningún canal sano lo atiende ahora mismo.

Tabla completa de códigos de error →

#Ejemplo de solicitud

# 1. submit
curl https://www.aisplice.store/v1/images/tasks \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-image-2.5-ext", "prompt": "A red paper crane on a desk", "size": "16:9", "resolution": "1K"}'

# 2. poll every 3s until a terminal status
curl https://www.aisplice.store/v1/images/tasks/$TASK_ID -H "Authorization: Bearer sk-YOUR_KEY"

# 3. fetch persistent result URLs
curl https://www.aisplice.store/v1/images/tasks/$TASK_ID/content -H "Authorization: Bearer sk-YOUR_KEY"

#Respuesta

response.json
// POST /v1/images/tasks
{"task_id": "task_xxx", "status": "queued"}

// GET /v1/images/tasks/{task_id}
{"task_id": "task_xxx", "status": "in_progress", "progress": "60%"}

// GET /v1/images/tasks/{task_id}/content — after completion
{"created": 1720000000, "data": [{"url": "https://…"}]}

¿Sigues con el problema?

Envíanos el ID de solicitud o el mensaje de error y lo revisaremos.

AnteriorMessages (formato Anthropic)SiguienteVideos