how-tos

Ideogram 4.6 API: guía para la primera imagen y edición en cURL y Python

Poyo.ai Team
9 min read
Share:

Guía de la Ideogram 4.6 API con cURL y Python

Esta guía de la Ideogram 4.6 API te lleva de una API key a una imagen terminada en cURL y Python, y después cubre todos los modos de entrada que acepta el esquema de PoYo: text-to-image con tamaños preset o personalizados, fondos transparentes, ediciones normales, ediciones con máscara, imágenes de referencia y ediciones de alta precisión. Text-to-image usa el ID de modelo ideogram-v4.6 y la edición usa ideogram-v4.6-edit; ambos aparecen en la página del modelo Ideogram 4.6.

Las reglas de los campos proceden de la referencia de la API de PoYo. Para saber qué es el modelo y cómo se compara, empieza por la introducción a la Ideogram 4.6 API.

Paso 1: envía una solicitud a la Ideogram 4.6 API con cURL

Crea una clave en el panel de PoYo y expórtala como POYO_API_KEY. Guárdala en tu servidor, no en el código del navegador.

curl https://api.poyo.ai/api/generate/submit \
  -H "Authorization: Bearer $POYO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "ideogram-v4.6",
    "input": {
      "prompt": "A colorful storefront with a neon sign reading \"HELLO\""
    }
  }'

Esto usa los valores por defecto: size: auto (unos 2K), quality: medium y una imagen, así que cuesta 12 créditos ($0.06). Un envío correcto devuelve code: 200 y un objeto data con task_id, status: "not_started" y created_time. Es una tarea en cola, no una imagen. Comprueba code en el cuerpo cada vez: algunos errores de validación llegan con HTTP 200 y code: 400.

Paso 2: consulta el estado de la tarea

curl https://api.poyo.ai/api/generate/status/YOUR_TASK_ID \
  -H "Authorization: Bearer $POYO_API_KEY"

El estado pasa por not_started, running y después finished o failed. Una tarea terminada incluye una entrada por imagen en data.files, cada una con file_url y file_type: "image", e indica el cargo en credits_amount. Una tarea fallida explica el motivo en error_message.

Paso 3: un bucle de polling en Python con límite de tiempo

Este bucle comprueba tanto el estado HTTP como el code del cuerpo, se detiene en failed, devuelve todas las imágenes cuando n es mayor que 1 y se rinde a los 10 minutos sin volver a enviar la tarea.

import os
import time
import requests

BASE = "https://api.poyo.ai"
session = requests.Session()
session.headers["Authorization"] = "Bearer " + os.environ["POYO_API_KEY"]

def checked(response):
    body = response.json()
    if response.status_code >= 400 or body.get("code") != 200:
        error = body.get("error") or {}
        raise RuntimeError(f"PoYo error {body.get('code')}: {error.get('message', body)}")
    return body["data"]

def run(model, input_body, max_wait=600):
    task = checked(session.post(BASE + "/api/generate/submit",
                                json={"model": model, "input": input_body},
                                timeout=60))
    task_id = task["task_id"]
    deadline = time.monotonic() + max_wait
    while time.monotonic() < deadline:
        time.sleep(5)
        task = checked(session.get(BASE + "/api/generate/status/" + task_id, timeout=60))
        if task["status"] == "failed":
            raise RuntimeError(task.get("error_message") or "generation failed")
        if task["status"] == "finished":
            images = [f["file_url"] for f in task.get("files", []) if f.get("file_type") == "image"]
            return images, task.get("credits_amount")
    raise TimeoutError("Still running, check this task later: " + task_id)

images, credits = run("ideogram-v4.6", {
    "prompt": "A minimalist poster titled \"SUMMER JAZZ NIGHTS\", bold typography",
    "size": "1728x2304",
    "quality": "high",
    "n": 2,
})
print(images, credits)

1728x2304 es un tamaño 3:4 de 3,981,312 píxeles, por debajo de la línea de 4,194,304 píxeles, así que las dos imágenes se facturan con la tarifa 2K de calidad alta: 2 × 20 = 40 créditos ($0.20). Un timeout significa «vuelve a consultar el mismo ID de tarea más tarde». Volver a enviarla iniciaría una segunda tarea facturable. La misma función run() sirve para ediciones: pasa "ideogram-v4.6-edit" como modelo.

Todos los modos de entrada de la Ideogram 4.6 API

Todos los campos van dentro de input. El ID de modelo y un callback_url opcional van en el nivel superior.

Text-to-image en 4K

{
  "model": "ideogram-v4.6",
  "input": {
    "prompt": "A minimalist poster titled \"SUMMER JAZZ NIGHTS\", bold typography",
    "size": "2048x3072",
    "quality": "high",
    "n": 2
  }
}

2048x3072 son 6,291,456 píxeles, por encima de 4,194,304, así que es el nivel 4K y very_low no está permitido en este tamaño.

Fondo transparente y seed fijo

{
  "model": "ideogram-v4.6",
  "input": {
    "prompt": "A flat sticker of a smiling coffee cup",
    "size": "1:1 HD",
    "quality": "low",
    "background": "transparent",
    "seed": 42
  }
}

transparent devuelve una imagen con canal alfa; opaque fuerza un fondo sólido. Envía el mismo cuerpo con el mismo seed para repetir un resultado.

Edición normal

{
  "model": "ideogram-v4.6-edit",
  "input": {
    "prompt": "Replace the background with a blue photo studio",
    "image_urls": [
      "https://example.com/source.png"
    ]
  }
}

Una edición normal regenera la imagen a partir del prompt. image_urls debe ser un array con exactamente una imagen, como URL HTTP(S) pública o data URI en base64. Para enviar archivos locales, súbelos primero con el endpoint de subida de archivos de PoYo.

Cambio de estilo con una imagen de referencia

{
  "model": "ideogram-v4.6-edit",
  "input": {
    "prompt": "Restyle the product shot to match the reference",
    "image_urls": [
      "https://example.com/product.png"
    ],
    "reference_image_urls": [
      "https://example.com/style.png"
    ],
    "size": "2048x2048",
    "quality": "low",
    "n": 2
  }
}

Se permiten hasta 4 referencias, o 3 con máscara. Aquí se admite un size personalizado porque es una edición normal sin máscara.

Edición de alta precisión de toda la imagen

{
  "model": "ideogram-v4.6-edit",
  "input": {
    "prompt": "Change only the date line to \"JULY 3-5 · RIVERSIDE PARK\". Keep everything else exactly the same.",
    "image_urls": [
      "https://example.com/poster.png"
    ],
    "edit_precision": "high",
    "context_window": "none",
    "size": "auto",
    "quality": "high"
  }
}

Este es el cuerpo de nuestra edición del día del lanzamiento (tarea 672JRU198S22NS8D, 20 de noviembre de 2026), con la URL de origen sustituida. El origen era un póster de 2304×3072; la salida conservó ese tamaño y solo cambió la línea de la fecha, y la tarea se cobró a 120 créditos ($0.60), la tarifa de edición 4K de calidad alta.

Edición localizada con máscara

{
  "model": "ideogram-v4.6-edit",
  "input": {
    "prompt": "Change the sign text to \"OPEN LATE\"",
    "image_urls": [
      "https://example.com/storefront.png"
    ],
    "mask_url": "https://example.com/sign-mask.png",
    "edit_precision": "high",
    "context_window": "auto",
    "quality": "high"
  }
}

La máscara debe coincidir con las dimensiones del origen y contener zonas negras (editar) y blancas (conservar). Con context_window: auto, solo se edita la región alrededor de la máscara a la resolución del origen. Una máscara demasiado grande recurre a la edición de la imagen completa.

Reglas de validación de campos

Valida en tu lado antes de enviar para que las solicitudes incorrectas fallen rápido:

CampoRegla
modelideogram-v4.6 o ideogram-v4.6-edit
promptObligatorio, de 1 a 10,000 caracteres, no solo espacios
sizeauto, 1:1, 1:1 HD, 4:3, 3:4, 16:9, 9:16 o WIDTHxHEIGHT con x en minúscula
Tamaño personalizadoCada lado de 256 a 4096 y múltiplo de 32; relación de aspecto entre 1:6 y 6:1
qualityvery_low solo cuando la salida tiene como máximo 4,194,304 píxeles
nEntero de 1 a 8; se rechazan strings y booleanos
image_urlsSolo en edición; array con exactamente una imagen
mask_url, edit_precision: highRequieren size: auto (o ningún size)
backgroundSe rechaza cuando edit_precision es high
context_window: autoRequiere mask_url y edit_precision: high
Campos desconocidosSe rechazan con un error unsupported fields

Ejemplos: 2304x3072 es válido (ambos lados son múltiplos de 32); 1296x3168 falla porque 1296 no es múltiplo de 32, aunque Ideogram 4.5 lo aceptaba; 4096x512 falla (relación 8:1); very_low en 2048x3072 falla.

Errores que conviene gestionar

codeSignificadoQué hacer
400Parámetros no válidosCorrige el cuerpo; no reintentes sin cambios
401API key ausente o no válidaRevisa la cabecera Authorization: Bearer
402Créditos insuficientesRecarga y vuelve a enviar
429Límite de frecuencia superadoEspera y reintenta más tarde
500, 502, 503Error del servidor, del proveedor o de disponibilidadReintenta con backoff; comprueba antes si ya se devolvió un ID de tarea

Una tarea que llega a failed indica el motivo en error_message. Consulta los códigos de error para ver la lista completa.

Usa un callback en lugar de polling

Añade "callback_url": "https://your-app.example.com/poyo-webhook" en el nivel superior del cuerpo, no dentro de input. Cuando la tarea termina o falla, PoYo envía por POST los datos de la tarea a esa URL, firmados con HMAC-SHA256 en la cabecera X-Webhook-Signature; la documentación de webhooks explica la regla de la firma. Mantén un polling lento de respaldo para los callbacks que nunca llegan.

Cómo se calcula tu primera factura

La Ideogram 4.6 API factura por imagen de salida: precio del nivel de calidad y tamaño × n. 1 crédito = $0.005.

SolicitudNivelCargo
Valores por defecto (auto, medium, n: 1)Text-to-image medium 2K12 créditos ($0.06)
very_low, 3:4, n: 1Text-to-image very_low 2K1.6 créditos ($0.008)
high, 1728x2304, n: 2Text-to-image high 2K40 créditos ($0.20)
high, 2304x3072, n: 1Text-to-image high 4K40 créditos ($0.20)
Edición de alta precisión de un origen de 2304×3072, highEdición high 4K120 créditos ($0.60)

Las filas de very_low y 2304x3072 coinciden con lo que se cobró en nuestras tareas del día del lanzamiento. En las ediciones con size: auto, el precio se calcula a partir del tamaño de la imagen de origen y se liquida sobre la imagen entregada, nunca por encima de lo presupuestado. El artículo de precios incluye más ejemplos prácticos.

Preguntas frecuentes

¿La Ideogram 4.6 API es compatible con el SDK de OpenAI? No. Es una API de tareas asíncronas: envía a /api/generate/submit y luego consulta /api/generate/status/{task_id} o recibe un callback. Basta con requests, fetch o cURL.

¿Cómo edito una imagen con la Ideogram 4.6 API? Llama a ideogram-v4.6-edit con una URL en image_urls y el cambio en prompt. Añade edit_precision: high para conservar los píxeles que no pediste cambiar.

¿Puedo enviar imágenes de referencia a ideogram-v4.6? No. En PoYo, las referencias van en reference_image_urls de ideogram-v4.6-edit, hasta 4, o 3 con máscara.

¿Cuántas imágenes devuelve una solicitud a la Ideogram 4.6 API? De 1 a 8, según n. Cada imagen se factura al precio de su nivel.

¿Por qué la Ideogram 4.6 API rechazó mi solicitud por el tamaño? Los lados personalizados deben ser múltiplos de 32 entre 256 y 4096, y las máscaras o las ediciones de alta precisión requieren size: auto.

Share: