Generar imágenes

POST /v1/images/generations

Genera imágenes. Síncrono por defecto: la llamada espera a que la imagen esté lista y responde con la misma estructura que el endpoint images/generations de OpenAI, así que el SDK de OpenAI y las pasarelas de reenvío funcionan sin ajustes. Con async: true recibes un id de tarea al instante y lees el resultado en GET /v1/tasks/{id}. Con n mayor que 1 se crean n tareas independientes, cada una con su cobro.

Parámetros

Parámetro	Tipo	Descripción
prompt	string	Obligatorio. Qué dibujar
model	string	id de modelo de /v1/models. Sin él se usa el modelo por defecto
n	integer	Número de imágenes, de 1 a 4. Por defecto 1
size	string	Proporción 1:1 \| 16:9 \| 9:16 \| 4:3 \| 3:4. Por defecto 1:1. También acepta formatos en píxeles como 1024x1024 o 1792x1024 y los ajusta a la proporción más cercana
quality	string	Calidad 1k \| 2k \| 4k. Por defecto 1k; spec tiene prioridad. También acepta la nomenclatura de OpenAI: standard / low / auto equivalen a 1k, y medium / hd / high a 2k
spec	string	Clave de nivel tomada de specs[].key del modelo
reference_images	string[]	URLs de referencia. Lo que exceda max_reference_images se descarta
async	boolean	Por defecto false: espera a la imagen. Con true devuelve un objeto de tarea al instante y sondeas /v1/tasks/{id} por tu cuenta

Los valores no reconocidos no tumban la petición: se vuelve al valor por defecto (un size desconocido simplemente se genera en 1:1). Solo dan error un prompt vacío, contenido bloqueado, un límite alcanzado o falta de créditos. response_format no está soportado: los resultados llegan siempre como url.

Petición (síncrona)

bash

curl https://open.pikpikgo.com/v1/images/generations \
  -H "Authorization: Bearer $PIKPIK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "una calle cyberpunk bajo la lluvia de noche, reflejos de neón",
    "size": "16:9",
    "quality": "2k",
    "n": 1
  }'

Respuesta (síncrona)

json

{
  "created": 1786000246,
  "data": [
    { "url": "https://cdn.pikpikgo.com/ai/xxxx.png", "revised_prompt": "una calle cyberpunk bajo la lluvia de noche, reflejos de neón" }
  ],
  "id": "2608101909450810293847",
  "object": "image.generation",
  "model": "img-std-1",
  "status": "succeeded",
  "n": 1,
  "credits": 10,
  "tasks": [
    {
      "id": "2608101909450810293847",
      "status": "succeeded",
      "data": [{ "url": "https://cdn.pikpikgo.com/ai/xxxx.png", "revised_prompt": "una calle cyberpunk bajo la lluvia de noche, reflejos de neón" }]
    }
  ]
}

Campo	Descripción
created	Marca de tiempo de la respuesta
data	Resultados, cada uno con url y revised_prompt. Con n > 1 hay varios
id	Tarea principal (con n > 1, la primera subtarea)
status	succeeded, también en éxito parcial: compara tú mismo la longitud de data con n
credits	Créditos descontados en total
tasks	Todas las subtareas, cada una con su error y su resultado

Una llamada síncrona mantiene la conexión abierta, a menudo más de 30 segundos por imagen: amplía el tiempo límite del cliente a 300 segundos. Pasados 300 segundos el servidor devuelve 504 generation_timeout; la tarea sigue en marcha y los créditos no se devuelven, así que recupera el resultado más tarde en /v1/tasks/{id} con el id del mensaje. Si fallan todas las imágenes obtienes 502 generation_failed y los créditos se devuelven automáticamente.

Flujo asíncrono

Para lotes, mucha concurrencia o clientes sensibles a la latencia: la respuesta llega al momento, con status queued y data vacío.

bash

curl https://open.pikpikgo.com/v1/images/generations \
  -H "Authorization: Bearer $PIKPIK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "una calle cyberpunk bajo la lluvia de noche, reflejos de neón",
    "size": "16:9",
    "quality": "2k",
    "n": 1,
    "async": true
  }'

json

{
  "id": "2608101909450810293847",
  "object": "image.generation",
  "created": 1786000185,
  "model": "img-std-1",
  "status": "queued",
  "n": 1,
  "credits": 10,
  "tasks": [
    { "id": "2608101909450810293847", "status": "queued", "data": [] }
  ],
  "data": []
}

Con n > 1 recorre tasks. Consultar solo id deja fuera el resto de imágenes sin avisar.