Cómo usar recraft-v4.1/text-to-image a través de la API de HiAPI: guía con curl y Python

Qué te ofrece este endpoint

recraft-v4.1/text-to-image es un endpoint de modelo de texto a imagen: envías un prompt de texto y varias opciones de configuración en el cuerpo de la solicitud, y recibes los datos de la imagen generada. Es muy adecuado cuando quieres producir una imagen final en una sola llamada, sin tener que orquestar tú mismo una canalización de varios pasos.

En HiAPI, este modelo forma parte de un modo agregado: una URL base, una cabecera de autenticación y una estructura de solicitud/respuesta coherente entre endpoints. No necesitas conectar un SDK y un conjunto de credenciales distintos para cada modelo de imagen que quieras evaluar: basta con apuntar tu cliente al endpoint de recraft-v4.1/text-to-image en HiAPI y mantener el resto del código estable. Esto importa especialmente en la fase de prototipado, cuando quieres comparar prompts, estilos y modelos sin reescribir la capa de transporte cada vez.

Una forma práctica de entender esta llamada:

• Prompt: la descripción en lenguaje natural de la imagen que deseas.
• Style: campo del cuerpo de la solicitud que orienta el tratamiento visual de la salida.
• Resolution: campo del cuerpo de la solicitud que determina el tamaño de la salida.

Como los tres viajan en el mismo cuerpo JSON, la ingeniería de prompts y la configuración de la salida se resuelven en un solo intercambio. Si te preguntas si este es el endpoint adecuado, la respuesta suele ser sí: cuando necesitas generación de imágenes síncrona y guiada por prompts, y quieres mantener los detalles de la infraestructura del proveedor fuera del código de tu aplicación.

Requisitos previos y autenticación

Antes de la primera llamada, asegúrate de tener:

• Una cuenta de HiAPI y una clave de API. Mantenla fuera del control de código fuente y cárgala desde una variable de entorno.
• curl para una prueba de humo rápida, y Python 3 con requests instalado si vas a usar el ejemplo en Python.
• Un prompt que realmente quieras renderizar, aunque sea tosco, para verificar que la conexión funciona.

La autenticación de HiAPI se basa en cabeceras. La clave de API se transmite mediante una cabecera, y el patrón de cabecera es el mismo tanto si llamas desde curl, Python u otro cliente HTTP. La selección del modelo se realiza mediante la ruta del endpoint, por lo que la cabecera de autenticación no cambia cuando cambias de modelo.

Una configuración local segura es la siguiente:

export HIAPI_API_KEY="your-key-here"

Después, haz referencia a $HIAPI_API_KEY en los comandos de shell y a os.environ["HIAPI_API_KEY"] en Python. Nunca codifiques la clave directamente en scripts que puedan ser confirmados en el repositorio, y evita pegarla en registros o informes de errores. Si la clave se filtra, rótala en la configuración de tu cuenta en lugar de intentar eliminarla del historial.

Los ejemplos siguientes asumen dos cosas: la URL base de la API de HiAPI y la ruta del modelo recraft-v4.1/text-to-image. Antes de integrarlo en tu build, confirma ambos con la referencia de API de tu cuenta, ya que el host y la ruta exactos son lo único en esta guía que debes copiar de la documentación actual y no de memoria.

Solicitud curl ejecutable

La forma más rápida de confirmar que la clave, el endpoint y la estructura del payload funcionan es una llamada con curl. La solicitud envía un cuerpo JSON con el prompt y los campos de configuración, y transmite la clave de API en la cabecera:

curl -X POST "$HIAPI_BASE_URL/recraft-v4.1/text-to-image" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A minimalist isometric illustration of a developer workstation, soft pastel palette, clean background",
    "style": "illustration",
    "resolution": "1024x1024"
  }'

Hay varios aspectos que conviene tener en cuenta sobre esta llamada:

• Ruta del endpoint. El nombre del modelo está en la ruta. Cambiar a otro modelo más adelante implica cambiar ese segmento de la ruta, no reconstruir la solicitud.
• Cuerpo de la solicitud, no cadena de consulta. prompt, style y resolution van en el cuerpo JSON. Así la URL se mantiene estable y el payload es fácil de registrar y reproducir.
• Autenticación por cabecera. La cabecera Authorization transporta la clave; Content-Type debe ser application/json.

Si en el primer intento recibes una respuesta que no es 200, revisa en este orden: si la clave está definida en el shell, si la URL base no tiene una barra final duplicada y si el cuerpo JSON es válido (una coma final suele ser la causa). Una vez que la llamada funcione, guarda el comando exacto en un archivo de borrador: una llamada curl que sabes que funciona es tu referencia para comparar cada cambio de SDK y de cliente.

La misma solicitud en Python

Para código real, encapsula la llamada en una función pequeña, de modo que los reintentos, el registro y el cambio de modelo tengan un lugar único donde vivir. Usa requests:

import os
import requests

HIAPI_BASE_URL = os.environ["HIAPI_BASE_URL"]
API_KEY = os.environ["HIAPI_API_KEY"]


def generate_image(prompt, style="illustration", resolution="1024x1024", timeout=120):
    url = f"{HIAPI_BASE_URL}/recraft-v4.1/text-to-image"
    headers = {
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json",
    }
    payload = {
        "prompt": prompt,
        "style": style,
        "resolution": resolution,
    }
    response = requests.post(url, headers=headers, json=payload, timeout=timeout)
    response.raise_for_status()
    return response.json()

Decisiones de diseño que vale la pena conservar:

• Usa json= en lugar de data=. Pasar un dict a json= establece el tipo de contenido por ti y serializa el cuerpo, por lo que el payload coincide byte a byte con la versión de curl.
• Timeout explícito. La generación de imágenes no es instantánea; un timeout holgado evita falsos fallos por solicitudes lentas pero saludables. No dependas de los valores predeterminados del cliente.
• raise_for_status() primero. Convierte los errores HTTP en excepciones antes de intentar leer el cuerpo de la respuesta, para que un 4xx o 5xx nunca se confunda con datos de imagen.
• Configuración basada en el entorno. Tanto la URL base como la clave provienen del entorno, lo que hace que la función sea portable entre local, preproducción y producción.

La función devuelve el JSON analizado. Cómo extraer la imagen de ese JSON es el siguiente tema, y es donde fallan la mayoría de las integraciones.

Manejo de la respuesta de imagen síncrona

recraft-v4.1/text-to-image devuelve los datos de la imagen de forma síncrona: la imagen llega en la misma respuesta HTTP que la solicitud, sin bucles de sondeo ni identificadores de tarea que seguir. Esto simplifica el cliente, pero traslada dos responsabilidades a tu código: decodificar el payload y gestionar los fallos de forma explícita.

La ruta de procesamiento robusta es la siguiente:

1. Comprueba el estado antes de analizar. Trata cualquier código distinto de 200 como un error y muestra el cuerpo de la respuesta, que normalmente explica el problema.
2. Lee el campo de imagen de forma consciente. El JSON de respuesta transporta los datos de la imagen; según el campo que recibas, puede ser una URL o bytes de imagen codificados. Gestiona ambas rutas en lugar de asumir una de ellas.
3. Decodificación defensiva. Si el payload está codificado en base64, decodifícalo y escribe los bytes en un archivo. No enrutes datos binarios por rutas solo de texto ni los imprimas en la terminal.
4. Limita el tamaño del payload. En comparación con un JSON típico, las respuestas de imagen síncronas son grandes. Escribe en disco en streaming cuando el cliente lo permita y evita mantener varias respuestas en memoria a la vez.

Pasos mínimos de guardado para un payload en base64:

import base64

data = generate_image("A calm forest at dawn, soft light")
image_b64 = data["image"]  # adjust to the actual field name in the response
with open("out.png", "wb") as f:
    f.write(base64.b64decode(image_b64))

Hay dos modos de fallo que merecen un tratamiento específico. Los timeouts deben reintentarse con retroceso exponencial, pero solo si se espera idempotencia: regenerar una imagen produce resultados distintos, así que registra el prompt en cada intento. Los errores de cliente (como un cuerpo de solicitud mal formado o un valor de opción no válido) no se corrigen solos con reintentos; falla rápido y registra el texto de la respuesta. Por último, verifica que el campo de imagen exista antes de decodificar, de modo que un cambio de esquema o un payload erróneo provoque una excepción clara en lugar de un error de decodificación confuso.

Ajuste de estilo y resolución para tu caso de uso

style y resolution son los dos campos del cuerpo de la solicitud que más influyen en el resultado, y ambos son baratos de iterar porque viajan junto con el prompt.

Style

style orienta el tratamiento visual de la salida. Úsalo para mantener la coherencia visual de una serie de imágenes; por ejemplo, fija el mismo estilo en un lote de ilustraciones de producto o en las imágenes de cabecera de artículos, para que parezcan un conjunto. Cuando el resultado no se sienta correcto, comprueba primero si el estilo coincide con el contenido: aplicar un estilo orientado a la ilustración a un prompt realista entrará en conflicto con el texto. Antes de añadir detalles, prueba prompts simples con un estilo fijo, así podrás determinar si un mal resultado proviene del estilo o de la redacción.

Resolution

resolution determina el tamaño de la salida. Haz que coincida con el uso previsto: elige tamaños cercanos al cuadrado para avatares y miniaturas, y tamaños más anchos para banners e imágenes principales. Dos reglas prácticas:

• Genera al tamaño final en lugar de ampliar. Genera directamente una imagen cercana al tamaño de visualización final, en lugar de generar una pequeña y ampliarla.
• Ten en cuenta la relación de aspecto. Si tu diseño espera una proporción específica, elige una resolución que coincida con esa proporción en lugar de recortar después.

Depuración de salidas inesperadas

Cuando una imagen no se vea bien, aísla una variable a la vez. Mantén el prompt sin cambios y modifica style; luego mantén ambos y modifica resolution. Si nada de eso ayuda, reescribe el prompt con sustantivos concretos y señales de composición claras en lugar de añadir adjetivos. Comprueba también que no estés enviando silenciosamente un tipo de valor incorrecto: una cadena de estilo que no coincida con las opciones aceptables puede ser rechazada o ignorada, según la lógica de validación. Registra el cuerpo exacto de la solicitud en cada llamada; es el único registro fiable de qué produjo cada imagen.

Encapsulamiento para producción

El valor de esa pequeña función se hace evidente cuando la endureces. Un encapsulamiento de nivel de producción debe hacer cuatro cosas:

• Encapsular el transporte. Una función posee la URL, las cabeceras, la estructura del payload y el timeout. Quien llama solo pasa el prompt y las opciones, nada más.
• Añadir reintentos con retroceso. Reintenta un número limitado de veces los timeouts y las respuestas 5xx; nunca reintentes errores 4xx. Como la generación de imágenes no es idempotente, mantén bajo el límite de reintentos y asocia el prompt a cada intento.
• Registrar la solicitud, no solo el resultado. Registra el prompt, el estilo, la resolución, el estado y la duración. Cuando alguien pregunte por qué una imagen se ve así, ese registro es la respuesta.
• Tratar el modelo como parámetro. Pasa la ruta del modelo como parámetro, con recraft-v4.1/text-to-image como valor predeterminado. Así, cambiar a otro modelo de imagen se convierte en un cambio de configuración y no en una refactorización, lo que abarata la evaluación comparativa.

Mantén la capa de encapsulamiento ligera. Resiste la tentación de añadirle almacenamiento en caché, colas o políticas de almacenamiento; eso pertenece a una capa superior, para que pueda evolucionar de forma independiente a la llamada a la API. Una interfaz estable también significa que tus pruebas pueden simular la capa de transporte y verificar el payload que vas a enviar, lo que detecta la mayoría de los errores de integración antes de que lleguen a una solicitud real.

Con la autenticación, una solicitud que sabes que funciona y un manejo explícito de la respuesta, tienes todo lo necesario para llamar a recraft-v4.1/text-to-image desde HiAPI con curl y Python, y para cambiar de modelo después sin tocar el resto del código.