Crear job

POST/v2/jobs

Scope: images:generate · consume tokens

Encola una generación y responde al momento. El resultado llega por webhook o consultando GET /v2/jobs/:jobId.

Cuerpo

Parámetro	Tipo	Por defecto	Descripción
`type`	`string`		Obligatorio. `image_generation`.
`params`	`object`		Obligatorio. Los mismos parámetros que `POST /v1/generate/image` (`prompt`, `model_id`, `resolution`, `aspectRatio`, `reference_images`…).
`callback_url`	`string`		URL a la que se envía el resultado de este job. Ver abajo.
`priority`	`number`	`0`	Prioridad de 0 a 10.

Ejemplo

curl https://api.beta.pictulab.com/v2/jobs \
  -H "Authorization: Bearer $PICTULAB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "image_generation",
    "params": {
      "prompt": "Zapatilla deportiva sobre fondo pastel, estudio",
      "model_id": "gemini-2.5-flash-image",
      "aspectRatio": "1:1",
      "resolution": "2K"
    }
  }'

Respuesta

{
  "id": "6f1c2a7e-…",
  "type": "image_generation",
  "status": "queued",
  "params": {
    "prompt": "Zapatilla deportiva sobre fondo pastel, estudio",
    "model_id": "gemini-2.5-flash-image",
    "aspectRatio": "1:1",
    "resolution": "2K"
  },
  "tokens_charged": 6,
  "created_at": "2026-10-07T08:00:00.000Z",
  "estimated_seconds": 30
}

reference_images no se devuelve en params.

Cobro

Los tokens se debitan al crear el job (tokens_charged).
Si el job falla definitivamente o lo cancelas mientras está en cola, se devuelven íntegros.

Comprobaciones previas

Antes de cobrar, la API comprueba en este orden:

Código	Tipo	Causa
`429`	`CONCURRENT_JOBS_LIMIT`	Demasiados jobs en curso para tu plan. Ver Límites.
`403`	`MODEL_BLOCKED`	Modelo no disponible para tu equipo.
`413`	`REFERENCE_IMAGES_TOO_LARGE`	Imágenes de referencia > 8 MB en total.
`400`	`PRICING_ERROR`	No se pudo calcular el precio.
`402`	`INSUFFICIENT_TOKENS`	Saldo insuficiente.

`callback_url`

Además de los webhooks del equipo, puedes indicar una URL por job. Al terminar, Pictulab envía un único POST:

{
  "job_id": "6f1c2a7e-…",
  "status": "completed",
  "result": { "images": [ … ], "tokens_used": 6, "prompt": "…" },
  "error": null,
  "timestamp": "2026-10-07T08:00:31.000Z"
}