Integración de la API de generación de imágenes a partir de texto Seedream 5.0 Pro: curl, Python y técnicas para escribir texto

Seedream 5.0 Pro de texto a imagen (seedream-5.0-pro/text-to-image) es el nivel más caro de la familia Seedream 5.0, y su punto fuerte es el texto dentro de la imagen: letreros, envases y títulos de pósteres se escriben palabra por palabra siguiendo el prompt. En este artículo se ofrecen ejemplos de curl y Python listos para ejecutar, todos los parámetros, errores comunes y varias técnicas para que el texto se escriba correctamente.

Primero, el precio

Resolución	Por imagen	100 imágenes
1K	$0.05	$5
2K (predeterminada)	$0.10	$10

Precio actual de HiAPI, verificado el 18 de octubre de 2026.

La relación de aspecto no afecta al precio y las ejecuciones fallidas no se cobran. Pro no tiene 4K; si necesitas 4K puedes usar Seedream 5.0 Lite (2K/4K al mismo precio de $0.035). Para comparar los tres niveles, consulta Precios de la API de Seedream 5.0.

Una imagen real generada

16:9, 1K, con el texto del letrero de neón escrito palabra por palabra:

A neon-lit night market street in a rainy cyberpunk city, a glowing storefront sign reads "SEEDREAM 5 PRO" in crisp lettering, cinematic composition, dramatic directional lighting, rich cohesive color grade, ultra-detailed, premium commercial finish, subtle film grain, shallow depth of field, high dynamic range

Generar con este prompt →

seedream-5.0-pro/text-to-image, 16:9, 1K, $0.05.

Genera tu primera imagen

Preparación: crea una API Key en la consola y establécelo como variable de entorno:

export HIAPI_KEY="tu Key"

curl: enviar la tarea

curl -X POST "https://api.hiapi.ai/v1/tasks" \
  -H "Authorization: Bearer $HIAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedream-5.0-pro/text-to-image",
    "input": {
      "prompt": "A cozy coffee shop storefront at dusk, warm window light, a hand-painted wooden sign that reads \"THE DAILY GRIND\" in serif letters",
      "aspect_ratio": "16:9",
      "resolution": "2K"
    }
  }'

Devuelve un taskId:

{"code": 200, "message": "success", "data": {"taskId": "tk-hiapi-..."}}

curl: consultar el resultado

curl "https://api.hiapi.ai/v1/tasks/tk-hiapi-..." \
  -H "Authorization: Bearer $HIAPI_KEY"

Cuando data.status es success, la URL de la imagen está en data.output[0].url. Es un enlace temporal con caducidad, así que descárgala en cuanto lo obtengas:

curl -o result.png "<url de output>"

Con 2K, la imagen suele estar lista en aproximadamente un minuto.

Python (solo biblioteca estándar)

import json, os, time, urllib.request

API = "https://api.hiapi.ai/v1/tasks"
KEY = os.environ["HIAPI_KEY"]

def api(url, payload=None):
    req = urllib.request.Request(
        url,
        data=json.dumps(payload).encode() if payload else None,
        headers={"Authorization": f"Bearer {KEY}", "Content-Type": "application/json"},
        method="POST" if payload else "GET",
    )
    with urllib.request.urlopen(req) as resp:
        return json.loads(resp.read())

task_id = api(API, {
    "model": "seedream-5.0-pro/text-to-image",
    "input": {
        "prompt": 'A minimalist product poster on matte black, bold white headline that reads "SHIP FASTER", small caption "batch v2.1" bottom right',
        "aspect_ratio": "3:4",
        "resolution": "2K",
    },
})["data"]["taskId"]

while True:
    task = api(f"{API}/{task_id}")["data"]
    if task["status"] == "success":
        break
    if task["status"] == "fail":
        raise RuntimeError(task)
    time.sleep(5)

urllib.request.urlretrieve(task["output"][0]["url"], "result.png")

Todos los parámetros

Campo	Obligatorio	Valores
prompt	Sí	3–4000 caracteres, se recomienda mantenerlo dentro de unas 600 palabras en inglés
aspect_ratio	Sí	1:1, 4:3, 3:4, 16:9, 9:16, 2:3, 3:2, 21:9
resolution	Sí	1K ($0.05) o 2K ($0.10)
output_format	No	png (predeterminado) o jpeg

Los campos son estrictos: seed, n, size, image_urls, entre otros, no se aceptan; si envías campos de más, devuelve HTTP 400. Cada solicitud genera una imagen; si necesitas varias, envía varios tasks en paralelo.

Las resoluciones varían según el nivel dentro de la misma familia: Pro es 1K/2K, Lite es 2K/4K. Al cambiar de nivel, recuerda cambiar resolution.

Hacer que el texto se escriba correctamente

• Pon entre comillas el texto que quieres que aparezca: a sign that reads "OPEN 24 HOURS" es mucho más fiable que parafrasearlo.
• Especifica la posición y el estilo: sensación tipográfica (serif, manuscrita, neón), posición (esquina inferior derecha, centrado), soporte (letrero de madera, puerta de vidrio).
• No pongas demasiado texto: unos pocos textos cortos en una imagen funcionan de forma estable; los bloques largos de texto no.
• Si el texto es lo importante, usa 2K: las letras pequeñas se ven más nítidas en alta resolución.

Errores comunes

Síntoma	Respuesta	Cómo corregirlo
Falta un campo obligatorio	400, missing required field "aspect_ratio"	Envía los tres campos obligatorios
Valor de enumeración incorrecto	400, resolution: value must be one of '1K', '2K'	Rellena según la tabla anterior
Envío de seed, n, etc. de más	400, additional properties ... not allowed	Elimina los campos sobrantes
Key no válida	401, permission_denied	Revisa la Key en la consola

Si una tarea falla después de crearse, en la consulta del resultado aparece como status: "fail" y no se cobra.

Antes de salir a producción

• Usa callbacks en lugar de polling: añade en el nivel superior del cuerpo de la solicitud (al mismo nivel que model e input) "callback": {"url": "https://tu-dominio/hooks/hiapi", "when": "final"}. Tras recibir la notificación, haz un GET una vez al task para confirmar el resultado.
• Evita cobros duplicados: la tarea se factura en cuanto se acepta. Antes de reintentar, comprueba si ya has registrado el taskId de esta tarea; si lo tienes, sigue consultándolo y no la reenvíes; también puedes incluir la cabecera Idempotency-Key al enviarla.
• Guarda los archivos a tiempo: el enlace de salida caduca, no lo uses directamente como enlace externo.

Preguntas frecuentes

¿Se puede fijar el seed para reproducir?

No, esta interfaz no acepta seed. Para generar versiones similares basadas en una imagen existente, usa seedream-5.0-pro/image-to-image, que admite hasta 10 imágenes de referencia.

¿En qué se diferencia de Lite?

Lite cuesta $0.035 por imagen y su resolución es 2K/4K; Pro es 1K/2K, y 2K cuesta $0.10 por imagen. La forma de invocación es la misma. Para comparar Flash y Lite con el mismo prompt, consulta Seedream 5.0 Flash vs Lite.

¿Es obligatorio usar callbacks?

No. Para scripts y tareas por lotes basta con hacer polling, consultando cada 5 segundos.

También puedes copiar directamente el prompt del letrero de neón de arriba y generar una imagen por $0.05.