Cómo usar seedream-5.0-flash a través de la API de hiapi: curl, Python y una solicitud ejecutable

Lo que vas a construir

Una integración ejecutable que llama al modelo de imágenes seedream-5.0-flash de hiapi desde curl y Python: envía una solicitud de texto a imagen (o de edición de imagen), consulta el resultado y descarga la URL de salida. Al final tendrás un script que puedes colocar directamente en tu propio proyecto.

Requisitos previos

• Una cuenta de hiapi y una clave de API. Obtén una desde la consola de hiapi — la clave tiene la forma sk-....
• curl o Python 3.8+ (pip install requests).
• No se necesita ninguna biblioteca de edición de imágenes — seedream-5.0-flash acepta solo un prompt, o un prompt más una URL de imagen de entrada para editar.

Referencia completa del modelo: seedream-5.0-flash en hiapi y la página de documentación de la API.

Ejemplo mínimo ejecutable

hiapi expone todos los modelos generativos a través de un único endpoint unificado: primero creas una tarea y luego la consultas (o recibes un callback) hasta que se complete.

curl

# 1. Crear la tarea
curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-<your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedream-5.0-flash",
    "input": {
      "prompt": "una tetera de cerámica minimalista sobre una mesa de madera, luz suave de la mañana, fotografía de producto",
      "size": "2K"
    }
  }'
# => {"code":0,"data":{"taskId":"task_xxx","status":"pending", ...}}

# 2. Consultar hasta completar
curl -s https://api.hiapi.ai/v1/tasks/task_xxx \
  -H "Authorization: Bearer sk-<your-api-key>"
# => {"code":0,"data":{"taskId":"task_xxx","status":"success",
#      "output":[{"url":"https://...signed-url...","expireAt":"..."}]}}

Python

import time
import requests

API_KEY = "sk-<your-api-key>"
BASE_URL = "https://api.hiapi.ai/v1"
HEADERS = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}


def generate_image(prompt: str, size: str = "2K") -> str:
    create = requests.post(
        f"{BASE_URL}/tasks",
        headers=HEADERS,
        json={"model": "seedream-5.0-flash", "input": {"prompt": prompt, "size": size}},
        timeout=30,
    )
    create.raise_for_status()
    task_id = create.json()["data"]["taskId"]

    while True:
        poll = requests.get(f"{BASE_URL}/tasks/{task_id}", headers=HEADERS, timeout=30)
        poll.raise_for_status()
        data = poll.json()["data"]
        if data["status"] == "success":
            return data["output"][0]["url"]
        if data["status"] == "fail":
            raise RuntimeError(f"task failed: {data}")
        time.sleep(2)


if __name__ == "__main__":
    image_url = generate_image("una tetera de cerámica minimalista sobre una mesa de madera, luz suave de la mañana")
    print(image_url)

Notas sobre el objeto input:

• prompt (obligatorio, 1–5000 caracteres) — qué generar, o qué modificar si también pasas image.
• image (opcional, una cadena o un array de hasta 10 URL/URI data:image/... en base64) — pasa esto para editar o usar como referencia una imagen existente en lugar de generar desde cero. Omítelo para texto a imagen puro.
• size (opcional, por defecto "2K") — uno de los valores predefinidos 1K / 1.5K / 2K, o una cadena personalizada WIDTHxHEIGHT como "1536x1024" (píxeles totales entre 921,600 y 4,624,220, relación de aspecto entre 1:16 y 16:1).
• output_format (opcional) — "jpeg" o "png".
• background (opcional, por defecto "opaque") — establece "transparent" solo cuando edites una imagen con canal alfa.

El output[].url de la respuesta es un enlace firmado que caduca (campo expireAt) — descárgalo o realójalo a tiempo, en lugar de conservar ese hotlink a largo plazo.

Patrones para producción

Usar callbacks en lugar de polling

Para integraciones servidor a servidor, omite el polling y deja que hiapi te notifique cuando la tarea se complete. Añade un objeto callback de nivel superior junto a model/input (no lo anides dentro de input):

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-<your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedream-5.0-flash",
    "input": {"prompt": "una tetera de cerámica minimalista sobre una mesa de madera"},
    "callback": {"url": "https://yourapp.example.com/hooks/hiapi", "when": "final"}
  }'

when: "final" es actualmente el único valor admitido — cuando la tarea alcanza un estado terminal (success o fail), tu endpoint recibe exactamente un POST. Para evitar reintentos de entrega, deduplica por taskId y confirma que tu endpoint sea accesible por HTTPS antes de depender de él en producción.

Polling vs. callbacks

• Usa polling cuando estés prototipando, ejecutando scripts de corta duración o cuando aún no tengas un endpoint HTTPS público. Es simple, pero añade latencia y volumen de solicitudes para tareas lentas.
• Usa callbacks cuando ejecutes un servicio — sin solicitudes de polling desperdiciadas, y sabrás de inmediato cuando una tarea se complete. Requiere una URL HTTPS accesible públicamente.

Idempotencia

La generación de imágenes no es idempotente por sí misma (el mismo prompt no devuelve la misma imagen dos veces), así que si tu flujo de trabajo necesita semántica de "reintentar sin cobrar dos veces", lleva un registro del taskId de tu lado y comprueba el estado de la tarea antes de reenviar la misma solicitud tras un tiempo de espera, en lugar de reintentar a ciegas.

Manejo de errores

• 401 con permission_denied — tu clave de API falta, tiene un formato incorrecto o fue revocada:

  {"error":{"code":"permission_denied","message":"This API key is invalid. Check that it is correct or use another API key and try again.","type":"hiapi_error"}}
  

  Verifica que estés enviando Authorization: Bearer sk-... (y no solo la clave sin procesar) y que la clave no haya sido rotada.

• 400 con INVALID_REQUEST — algún campo no superó la validación. El message te dirá exactamente qué campo y por qué, por ejemplo un size fuera de rango. Corrige ese campo y vuelve a enviar; no reintentes tal cual.

• Fallos a nivel de tarea — la llamada HTTP puede tener éxito (200) mientras que la tarea termina con status: "fail" después de procesarse. Comprueba siempre data.status en la respuesta de polling/callback, no solo el código de estado HTTP de la llamada de creación.

Enlaces internos relacionados

• Página del modelo seedream-5.0-flash — precios, límites y panel de prueba en línea.
• Crear tarea (documentación) — esquema completo de la solicitud de POST /v1/tasks.
• Obtener detalles de la tarea (documentación) — estructura de la respuesta de polling y valores de estado.
• Autenticación (documentación) — cómo funcionan las claves de API y los encabezados en todos los endpoints de hiapi.
• Precios de hiapi — precio actual por imagen de seedream-5.0-flash y todos los demás modelos.
• Guía de la API de texto a imagen de seedream-5.0-pro — consulta el modelo hermano de mayor fidelidad del nivel Pro si necesitas salidas de mayor resolución.

Preguntas frecuentes

¿seedream-5.0-flash es gratuito? No — se factura por imagen a través de tu clave de API de hiapi. Consulta las tarifas actuales en la página de precios; sin una clave válida no hay acceso en producción.

¿seedream-5.0-flash admite edición imagen a imagen, no solo texto a imagen? Sí. Añade el campo image junto a prompt (una URL o una cadena data:image/... en base64, o un array de hasta 10), y el modelo editará o fusionará a partir de la imagen de referencia en lugar de generar desde cero.

¿Por qué mi solicitud devuelve 200 pero no hay imagen? Que POST /v1/tasks devuelva 200 solo significa que la tarea fue aceptada — la generación es asíncrona. Consulta GET /v1/tasks/<id> (o espera el callback) y comprueba data.status; la URL de la imagen solo aparece cuando status es "success".

¿Puedo solicitar una resolución personalizada en lugar de 1K/1.5K/2K? Sí — pasa size como "WIDTHxHEIGHT" (por ejemplo "1536x1024") en lugar de un valor predefinido. Los píxeles totales deben estar entre 921,600 y 4,624,220, y la relación de aspecto entre 1:16 y 16:1, o la solicitud devolverá 400.

¿Qué pasa con la URL de salida después de un tiempo? El output[].url devuelto es una URL firmada con una marca de tiempo expireAt — no es almacenamiento permanente. En cuanto la tarea tenga éxito, descarga los bytes o cópialos a tu propio almacenamiento lo antes posible.

Mi callback nunca se activó — ¿qué debería comprobar primero? Confirma que tu callback.url sea un endpoint HTTPS accesible públicamente (no localhost ni una dirección solo interna) y que callback sea un campo de nivel superior en el cuerpo de la solicitud — no anidado dentro de input.