Generar imagen

POST/v1/generate/image

Scope: images:generate · consume tokens

Genera una imagen a partir de un prompt y devuelve el resultado en la misma respuesta. Para lotes, usa jobs.

Cuerpo

Parámetro	Tipo	Por defecto	Descripción
prompt	string		Obligatorio. Descripción de la imagen.
model_id	string	gemini-2.5-flash-image	Modelo. Ver GET /v1/models.
resolution	string	1K	1K, 2K o 4K. Limitada por el modelo.
aspectRatio	string	1:1	Relación de aspecto. Ver Modelos.
reference_images	string[]		Imágenes de referencia en base64, data URL o URL de Pictulab.
quality	string	auto	low, medium, high o auto. Solo modelos GPT Image.
target_width	integer		Ancho exacto en píxeles. Solo modelos con custom_size.
target_height	integer		Alto exacto en píxeles. Solo modelos con custom_size.
image_format	string	image/png	Tipo MIME con el que se guarda el archivo.
fileName	string	generated_image	Nombre base del archivo generado.

Nota

image_format solo cambia la extensión y el tipo con que se guarda el archivo; la imagen no se recodifica.

Ejemplo

cURL

curl https://api.beta.pictulab.com/v1/generate/image \
  -H "Authorization: Bearer $PICTULAB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Botella de perfume sobre mármol blanco, luz suave",
    "model_id": "gemini-3-pro-image-preview",
    "aspectRatio": "4:5",
    "resolution": "2K"
  }'

Node.js

const res = await fetch('https://api.beta.pictulab.com/v1/generate/image', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.PICTULAB_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    prompt: 'Botella de perfume sobre mármol blanco, luz suave',
    model_id: 'gemini-3-pro-image-preview',
    aspectRatio: '4:5',
    resolution: '2K',
  }),
});
const data = await res.json();

Python

res = requests.post(
    "https://api.beta.pictulab.com/v1/generate/image",
    headers={"Authorization": f"Bearer {os.environ['PICTULAB_API_KEY']}"},
    json={
        "prompt": "Botella de perfume sobre mármol blanco, luz suave",
        "model_id": "gemini-3-pro-image-preview",
        "aspectRatio": "4:5",
        "resolution": "2K",
    },
    timeout=300,
)
data = res.json()

Respuesta

{
  "success": true,
  "images": [
    {
      "fileName": "generated_image_0.png",
      "storedFileName": "…",
      "url": "https://cdn.pictulab.com/…",
      "path": "./generated_image_0.png",
      "mimeType": "image/png",
      "fileSize": 1843211
    }
  ],
  "textResponse": "",
  "numberOfImages": 1,
  "prompt": "Botella de perfume sobre mármol blanco, luz suave",
  "tokensUsed": 12,
  "transactionId": "…"
}

Campo	Descripción
images[].url	URL pública de la imagen en el CDN de Pictulab.
tokensUsed	Tokens cobrados.
transactionId	ID del movimiento de tokens.

Errores habituales

Código	Tipo	Causa
402	INSUFFICIENT_TOKENS	Saldo insuficiente.
422	INVALID_SIZE	Tamaño exacto fuera de rango.
422	CONTENT_BLOCKED	Contenido bloqueado por el proveedor.
503	GENERATION_BUSY	Capacidad saturada; reintenta o usa un job.

Si no se genera ninguna imagen, los tokens se devuelven. Ver Errores.