Blog

Tutorial

Cómo usar seedream-4.5/text-to-image a través de la API de HiAPI: ejemplos en curl y Python

Guía práctica de integración mínima ejecutable para desarrolladores

Nov 17, 2026
Imagen de portada del blog de hiapi.ai: planos de hormigón gris cálido entrelazados bajo la luz solar oblicua, superficies de sombra azul grisácea profunda y juntas finas verde salvia que forman una composición geométrica minimalista.
En esta página

Qué puede ofrecerte seedream-4.5/text-to-image

seedream-4.5/text-to-image es el endpoint de texto a imagen que se ofrece a través de la API de HiAPI. Envías un prompt de texto y unos pocos parámetros opcionales, y el modelo devuelve una imagen generada. Puedes usarlo para crear ilustraciones de escenas, imágenes de maquetas de productos, arte conceptual o cualquier contenido visual que requiera texto legible renderizado dentro de la imagen: rótulos, etiquetas, titulares cortos. El endpoint no tiene estado: cada solicitud es una generación independiente, por lo que el control de la repetición y la variación recae en el código de tu aplicación.

Como se ejecuta tras la misma interfaz unificada que otros modelos de HiAPI, solo necesitas autenticarte una vez, usar la misma URL base y las mismas convenciones de error, y no aprender un nuevo patrón de integración al cambiar de modelo. La página de detalles del modelo seedream-4.5/text-to-image enumera los nombres de parámetros y valores aceptables actuales; usa esa página como fuente autorizada de los campos, no este artículo.

Estructura de la solicitud: qué enviar y qué recibir

Cada llamada de texto a imagen tiene la misma estructura: se envía una solicitud POST con un cuerpo JSON al endpoint de HiAPI del modelo. El cuerpo contiene los campos que el modelo requiere; la respuesta contiene la imagen generada y metadatos sobre la solicitud.

Qué se envía

  • prompt (cadena, obligatorio): la descripción de la imagen. Es la principal superficie de control; consulta la sección de prompts más abajo.
  • aspect_ratio o algún campo relacionado con el tamaño (opcional): controla la forma del lienzo de salida. Usa el nombre exacto del campo que aparece en la página de detalles del modelo; no supongas que coincide con el nombre de parámetro de otros modelos.
  • Cualquier opción específica del modelo que documente la página del modelo (por ejemplo, indicaciones de estilo o calidad). Omite los campos que no necesites; la API aplica valores predeterminados.

Qué se recibe

Una respuesta correcta es un objeto JSON. Los campos que realmente leerás en tu código suelen ser:

  • La carga de la imagen: según el esquema de respuesta, puede ser la URL de la imagen generada o una cadena de imagen codificada en base64. Tu código debe gestionar la forma que realmente devuelva el endpoint; la página del modelo indicará cuál es.
  • Metadatos de la solicitud, como un identificador o un estado, útiles para el registro y el soporte.

No todos los campos están garantizados en todas las versiones, así que valida la estructura de la respuesta en lugar de suponer un esquema fijo. Si tu analizador solo busca los campos que necesitas y trata los demás como opcionales, tu integración resistirá cambios menores en la respuesta.

Tu primera solicitud curl ejecutable

La llamada válida mínima envía solo un prompt y nada más. Sustituye la clave de marcador de posición y el prompt por los tuyos y ejecútala.

curl -X POST "https://api.hiapi.ai/v1/models/seedream-4.5/text-to-image" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Una tranquila cafetería de barrio al atardecer, luz cálida en las ventanas, un cartel de pizarra que dice OPEN",
    "aspect_ratio": "1:1"
  }'

Explicación línea por línea:

  • La URL apunta al endpoint de HiAPI de este modelo. Mantén el identificador del modelo exactamente como en la documentación.
  • La cabecera Authorization transporta tu clave de API. Usar variables de entorno evita que la clave aparezca en el historial de tu shell y en los archivos fuente.
  • Content-Type: application/json indica al servidor que analice el cuerpo como JSON.
  • El cuerpo JSON contiene el prompt y una relación de aspecto opcional. Empieza con una imagen y un prompt; itera la redacción antes de añadir opciones.

Si la llamada se realiza correctamente, la respuesta contendrá los datos de imagen descritos en la sección anterior. Guarda la salida en un archivo (o abre la URL devuelta) y revísala antes de construir más. Si encuentras un error de autenticación, confirma que la clave existe y que la cabecera está escrita correctamente; si encuentras un error de parámetro, vuelve a comprobar los nombres de campo con la página del modelo.

Implementar la misma solicitud en Python

La versión en Python usa la biblioteca estándar requests; no se necesita SDK.

import os
import requests

API_KEY = os.environ["HIAPI_API_KEY"]
URL = "https://api.hiapi.ai/v1/models/seedream-4.5/text-to-image"

payload = {
    "prompt": "Una tranquila cafetería de barrio al atardecer, luz cálida en las ventanas, un cartel de pizarra que dice OPEN",
    "aspect_ratio": "1:1",
}

response = requests.post(
    URL,
    headers={"Authorization": f"Bearer {API_KEY}"},
    json=payload,
    timeout=60,
)
response.raise_for_status()
result = response.json()
print(result)

Dos detalles son importantes aquí. Primero, pasa json=payload en lugar de una cadena construida a mano; requests establece el tipo de contenido y serializa correctamente. Segundo, establece un timeout explícito. La generación de imágenes puede tardar más que una llamada típica a la API, por lo que un tiempo de espera amplio con un modo de fallo claro es mejor que una solicitud colgada.

El resultado impreso es la respuesta sin procesar. En código real, extrae el campo de imagen que devuelva tu endpoint (URL o base64) y luego o bien descarga esa URL con una segunda solicitud, o bien decodifica el base64 a bytes y lo escribe en disco. Coloca esa lógica de extracción en una pequeña función auxiliar para que las pruebas y el código de producción compartan la misma lógica de análisis.

Escribir prompts para realismo y texto legible

La calidad del prompt determina la calidad de la salida más que cualquier otro parámetro. Los dos objetivos más frecuentes son: escenas fotorrealistas y texto claro y legible dentro de la imagen.

Realismo

Describe la escena como lo haría un fotógrafo al encuadrar: sujeto, iluminación, hora del día, sensación de objetivo y entorno. Los sustantivos concretos superan a los adjetivos abstractos. En lugar de «una buena cafetería», escribe «el interior de una cafetería estrecha y alargada, luz del mediodía entrando por grandes ventanales, mostrador de madera, profundidad de campo reducida». Añade una breve indicación de estilo, como «photograph» o «documentary photo», para alejar al modelo del estilo de ilustración. Mantén un sujeto principal por prompt; los sujetos que compiten entre sí suelen producir composiciones caóticas.

Texto legible

Cuando la imagen deba contener texto, pon el texto exacto entre comillas y mantenlo corto. Un rótulo que dice OPEN o una etiqueta que dice FRESH BREAD es mucho más fiable que un párrafo entero de texto. Indica dónde aparece el texto —«un cartel de pizarra que dice OPEN sobre el mostrador»— para que el modelo sepa que el texto pertenece a un objeto. Si el texto sale distorsionado, acórtalo, simplifica la escena circundante y vuelve a generar. Es normal ajustar ligeramente la redacción; cuenta con varias iteraciones.

Iteración

Cambia una sola variable a la vez: primero el prompt, luego la relación de aspecto y por último cualquier opción de estilo. Guarda tus prompts junto con los ajustes que produjeron buenos resultados. Ese registro se convertirá en tu línea base para regenerar y evitará que la depuración se convierta en adivinación.

Elegir la relación de aspecto y los ajustes de salida

La relación de aspecto decide la composición antes de que el modelo dibuje nada. Elígela según el uso previsto, no para coincidir con el valor predeterminado.

  • Cuadrada (1:1): publicaciones sociales, avatares, fichas de producto. Sencilla y segura.
  • Horizontal (por ejemplo, 16:9): banners, imágenes principales, diapositivas de presentación. Favorece escenas amplias: horizontes, escaparates, interiores espaciosos.
  • Vertical (por ejemplo, 9:16): pantallas móviles, historias, pósteres. Los prompts con un sujeto vertical claro —una persona de pie, un edificio alto— funcionan mejor.

Si tu prompt describe una escena amplia pero solicitas un lienzo vertical, el modelo tendrá que recortar o distorsionar la composición. Haz que la descripción coincida con el formato. Para canalizaciones posteriores, genera al tamaño que se adapte a tu caso de uso más grande y reduce después; ampliar imágenes pequeñas rara vez se ve bien. Cuando necesites varios formatos, realiza llamadas separadas para cada relación en lugar de recortar una imagen en distintos diseños.

Los ajustes de salida más allá de la relación de aspecto (indicaciones de calidad, controles de estilo) son específicos del modelo. Establece solo lo que documente la página del modelo y trata cada parámetro adicional como una variable que hay que probar, no como un valor predeterminado que copiar.

Gestionar errores y límites de velocidad

Las causas de fallo en una integración de producción son previsibles: clave incorrecta, parámetro no válido, tiempo de espera agotado y limitación de velocidad. Gestiona cada una de forma explícita.

Validar antes de analizar

Comprueba primero el código de estado HTTP. 2xx significa éxito; entonces analiza el cuerpo de la respuesta. 4xx normalmente significa que tu solicitud tiene un problema: clave no autorizada, JSON mal formado o valor de parámetro no admitido. Estos problemas no se resuelven solos al reintentar; registra el cuerpo de la respuesta, informa al llamador y corrige la solicitud. 5xx indica un problema del lado del servidor, normalmente temporal.

Reintentos con retroceso

Reintenta solo los fallos que podrían tener éxito después: respuestas 429, tiempos de espera agotados, errores de conexión y la mayoría de los códigos de estado 5xx. Usa retroceso exponencial con fluctuación aleatoria: espera un intervalo base corto, duplícalo en cada intento y establece un límite máximo de intentos. Nunca reintentes un 400 o un 401; solo consumirás cuota en vano.

import time, random

def generate(payload, max_attempts=5):
    for attempt in range(max_attempts):
        try:
            r = requests.post(URL, headers=HEADERS, json=payload, timeout=60)
        except requests.RequestException:
            pass  # Error de red: reintentar abajo
        else:
            if r.status_code == 200:
                return r.json()
            if r.status_code not in (429, 500, 502, 503, 504):
                raise RuntimeError(f"Irrecuperable: {r.status_code} {r.text}")
        time.sleep(min(2 ** attempt + random.random(), 30))
    raise RuntimeError("Intentos agotados")

Respetar los límites

Mantén el volumen de solicitudes por debajo del límite de velocidad indicado en tu cuenta y trata el 429 como una señal para reducir la velocidad, no para reintentar con más fuerza. Añade un límite de concurrencia en los workers y registra el ID de solicitud de cada intento para diagnosticar después la limitación de velocidad y los fallos. Como las llamadas de imagen se facturan por la salida generada, los reintentos que producen imágenes no son gratuitos; valida la entrada antes de realizar la solicitud.

De la llamada de prueba a la lista de verificación de producción

Antes de pasar a producción, confirma los siguientes puntos operativos:

  • Gestión de claves: las claves se guardan en variables de entorno o en un gestor de secretos, nunca en el control de código fuente. Rota las claves según un calendario y de inmediato ante cualquier sospecha de filtración.
  • Tiempos de espera: cada llamada saliente tiene un tiempo de espera explícito y tu llamador tiene un plan para cuando se agota.
  • Registro: registra el ID de solicitud, la versión del prompt, los parámetros, el estado y la latencia de cada llamada. Oculta las claves y la carga completa cuando sea necesario.
  • Versionado de prompts: guarda los prompts y los ajustes que produjeron las salidas aceptadas, para poder reproducir y revertir.
  • Conciencia de costes: la generación se factura por salida, así que limita el tamaño de los lotes, evita reintentos innecesarios y almacena en caché los resultados que vayas a reutilizar.
  • Degradación elegante: cuando la generación siga fallando tras los reintentos, recurre a una imagen almacenada en caché o a un marcador de posición en lugar de romper la página.

Empieza con la llamada curl única de esta guía, llévala a una pequeña función auxiliar de Python y solo entonces añade concurrencia y procesamiento por lotes. A medida que escales la integración, la página de referencia del modelo seedream-4.5/text-to-image es el lugar donde confirmar los nombres de campo.

Artículos relacionados

Ver todos los artículos →

Empieza a crear con artefactos de IA persistentes

Consigue tu API key y llama a modelos de imagen, vídeo y audio a través de una única API basada en tasks.

Leer la documentación de la API