Tutorial
Cómo usar krea-3/text-to-image a través de la API de HiAPI: curl, Python y una solicitud ejecutable
En esta página
Por qué llamar a krea-3/text-to-image a través de una API agregadora
Cada nuevo modelo de imagen significa otro SDK, otro esquema de autenticación y otro conjunto de peculiaridades de respuesta. Si solo publicas una función de imagen, ese costo es tolerable. Pero si publicas varias — o esperas poder cambiar de modelo libremente en el futuro — se convierte en el principal costo de tu trabajo.
Llamar a krea-3/text-to-image a través de HiAPI elimina ese costo. Integras una vez contra una única convención de endpoint, una única credencial y una única estructura de respuesta. El identificador del modelo se convierte en un campo del payload de la solicitud, no en una bifurcación en tu base de código. Cuando quieras comparar la salida con otros modelos de imagen o migrar cargas de trabajo, cambias una cadena, no una integración.
Para este modelo en particular, los beneficios prácticos son concretos:
- Todas las solicitudes comparten la misma estructura. Las llamadas de texto a imagen siguen la misma convención de autenticación y payload en toda la plataforma, por lo que el conocimiento que obtienes de la primera llamada se transfiere directamente al siguiente modelo.
- Código de aplicación independiente del modelo. Mantén el nombre del modelo en la configuración. Prototipa con
krea-3/text-to-image; cambiar a otro modelo para servir después no debería requerir modificar tu capa HTTP. - Punto único de observación del uso. La facturación, los registros de solicitudes y las respuestas de error provienen de la misma interfaz, no de N paneles de proveedores.
- Menos claves. Sin importar cuántos modelos llames, solo necesitas almacenar, rotar y limitar una clave.
El costo es el costo habitual de la agregación: trabajas a través de una interfaz genérica, por lo que las peculiaridades específicas de cada modelo se normalizan. En la práctica, eso es exactamente lo que quieres — entradas normalizadas, errores predecibles y la libertad de tratar el modelo como un parámetro ajustable.
Este tutorial mantiene deliberadamente un alcance estrecho. Construiremos una solicitud ejecutable, la ejecutaremos dos veces (primero con curl, luego con Python), observaremos cómo la redacción del prompt guía las salidas de estilo fotográfico e ilustrado, y luego depuraremos las pocas fallas que representan la mayoría de los problemas en la primera llamada. Sin diagramas de arquitectura, sin opiniones de frameworks — solo una solicitud que puedes enviar en los próximos cinco minutos y una lista de verificación para usar cuando algo falle.
Supuestos: tienes una cuenta de HiAPI, puedes leer la clave de API desde el panel y estás familiarizado con la terminal y el intérprete de Python. No se necesita nada más.
Antes de enviar la solicitud
Hay tres condiciones que deben cumplirse antes de la primera llamada. Hazlas bien y el resto será principalmente ajuste; hazlas mal y pasarás una hora depurando la capa equivocada.
1. Cuenta y clave de API
Inicia sesión en HiAPI y obtén tu clave de API desde el panel. Trátala como confidencial: debe almacenarse en una variable de entorno o en un gestor de secretos, nunca en un archivo confirmado, y nunca en prompts o mensajes de soporte. Los ejemplos siguientes la leen de una variable de entorno:
export HIAPI_API_KEY="your-key-here"
Si tu organización admite múltiples claves, usa una clave dedicada para esta integración, de modo que puedas rotarla independientemente de otras ejecuciones.
2. Convención de endpoint y encabezado de autenticación
Las solicitudes de HiAPI usan autenticación con token bearer — el mismo patrón que has visto en otros cientos de API:
Authorization: Bearer $HIAPI_API_KEY
Content-Type: application/json
Usa la URL base que se muestra en la referencia de la API de HiAPI para la región de tu cuenta y añade la ruta de generación de imágenes documentada allí. No adivines la ruta de memoria ni a partir de publicaciones de blog (incluida esta) — la referencia de la API es la única fuente de verdad, y la ruta es la única parte de la solicitud que puede cambiar sin previo aviso. Consejo del tutorial: consulta la referencia una vez, copia la URL y guárdala en un valor de configuración.
3. Identificador del modelo, exactamente como se escribe
El identificador del modelo es krea-3/text-to-image. Mantén el prefijo de espacio de nombres y los guiones exactamente como se escriben — krea3/text2image o krea-3 solo fallarán con un modelo no encontrado. Las mayúsculas y minúsculas también importan. Guárdalo como una constante:
MODEL = "krea-3/text-to-image"
Esta cadena es lo que hace que tu integración sea independiente del modelo, así que dale un nombre y trátala como configuración, no la codifiques directamente en cada punto de llamada.
Lo que no necesitas averiguar de antemano
No necesitas conocer los nombres de los campos de tamaño de imagen, semilla o pasos antes de la primera llamada. Comienza con la configuración mínima: autenticación, identificador del modelo y prompt. Una vez que obtengas una respuesta 200, añade parámetros uno a uno, porque una solicitud fallida con cinco campos configurados te da cinco sospechosos. Una solicitud fallida mínima te da solo uno.
Construir una solicitud ejecutable con curl
curl es la forma más rápida de aislar los dos problemas de la primera llamada: credenciales y estructura del payload. Sin versión de SDK, sin entorno virtual, sin runtime asíncrono — solo una solicitud en el cable.
La llamada mínima solo lleva lo que el modelo realmente necesita: el encabezado de autenticación, el identificador del modelo y el prompt.
curl -sS -X POST "$HIAPI_BASE_URL/v1/images/generations" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "krea-3/text-to-image",
"prompt": "A weathered fisherman mending a net on a dock at dawn, overcast light, 35mm photograph"
}'
Dos notas antes de ejecutar. Primero, $HIAPI_BASE_URL es un marcador de posición — establécelo con la URL base de la referencia de la API de HiAPI y confirma el segmento de ruta con la misma referencia. Segundo, la bandera -sS mantiene la salida silenciosa pero muestra los errores, que es exactamente lo que quieres al depurar.
Aspecto de una respuesta saludable: un objeto JSON que contiene una referencia o datos de la imagen generada, junto con metadatos de la solicitud. La estructura exacta está documentada en la referencia de la API; no escribas código de análisis para una estructura que aún no has observado. Guarda la respuesta real en un archivo para tener una base de verdad:
curl -sS -X POST "$HIAPI_BASE_URL/v1/images/generations" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"krea-3/text-to-image","prompt":"A neon-lit alley after rain, cinematic still"}' \
-o response.json
Luego inspecciónalo con jq o tu editor. Este archivo es tu fixture de prueba: cuando migres a Python, compara la salida. Si la respuesta de Python difiere estructuralmente de response.json, entonces el problema está en tu código, no en el modelo.
La razón para hacer esto primero con curl es el apalancamiento de diagnóstico. Si la llamada curl tiene éxito, tu clave es buena, la URL es correcta y el identificador del modelo se resuelve — por lo tanto, cualquier falla posterior está en tu código de aplicación. Si la llamada curl falla, el cuerpo del error te dirá cuál de los tres falló, y aún no habrás escrito una sola línea de código.
Una vez que la solicitud mínima tenga éxito, añade un parámetro a la vez. Vuelve a ejecutar curl después de cada adición. Conserva los payloads de solicitud exitosos; se convertirán en fixtures de entrada aceptadas para tus pruebas.
La misma solicitud en Python
La versión de Python se mantiene deliberadamente aburrida: la misma URL, los mismos encabezados, el mismo cuerpo JSON. El objetivo es la portabilidad — la estructura de solicitud que validaste en curl debería migrar a un script y luego a un servicio sin rediseño.
import os
import json
import requests
BASE_URL = os.environ["HIAPI_BASE_URL"].rstrip("/")
API_KEY = os.environ["HIAPI_API_KEY"]
MODEL = "krea-3/text-to-image"
def generate(prompt: str) -> dict:
response = requests.post(
f"{BASE_URL}/v1/images/generations",
headers={
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
},
json={"model": MODEL, "prompt": prompt},
timeout=120,
)
response.raise_for_status()
return response.json()
if __name__ == "__main__":
result = generate(
"A weathered fisherman mending a net on a dock at dawn, overcast light, 35mm photograph"
)
print(json.dumps(result, indent=2))
Algunas decisiones deliberadas:
- Variables de entorno, no literales. La clave nunca aparece en el código fuente. Si la variable falta,
os.environ["HIAPI_API_KEY"]falla ruidosamente al inicio, lo cual es mejor que un 401 confuso tres capas más abajo. - Llamar a
raise_for_status()antes de analizar. Quieres que los errores HTTP surjan como excepciones, no como unKeyErrorcuando intentas leer un campo de un cuerpo de error que resulta ser JSON. - Tiempo de espera holgado. La generación de imágenes no es un endpoint instantáneo. Establece un tiempo de espera que lo refleje y manéjalo explícitamente en producción (ver la sección de producción).
- Usar
json=en lugar de construir cadenas manualmente. Deja que la biblioteca serialice. La concatenación manual de JSON es exactamente la fuente de errores de comas finales y comillas.
Ejecútalo una vez y compara la salida con el response.json capturado anteriormente. La estructura debería coincidir. Imprime la referencia de imagen o decodifica los datos de imagen según lo que devuelva la respuesta — de nuevo, escribe código para la estructura observada, no para una supuesta.
Como MODEL es una constante, la misma función generate() funciona para cualquier modelo de imagen en la plataforma. Esa es la recompensa del modelo agregado: moverlo a un servicio, añadir un segundo modelo o hacer pruebas A/B de salidas son cambios de parámetros, no reescrituras.
Controlar estilos fotográficos e ilustrados
El estilo no es un interruptor; es una dirección que le das al modelo, y krea-3/text-to-image responde a las mismas palancas que usarías con un fotógrafo o ilustrador: sujeto, medio, iluminación y vocabulario técnico.
Inclinarse hacia el estilo fotográfico
La salida fotográfica se trata principalmente de nombrar el instrumento y sus consecuencias. Las palabras que describen cámara, lente, película y luz real funcionan mejor que la palabra "realista".
- Nombra el medio y el método de captura: "35mm photograph", "editorial portrait", "documentary still".
- Nombra la luz: "overcast daylight", "golden hour backlight", "single softbox at camera left".
- Nombra las imperfecciones: "slight motion blur", "visible grain", "shallow depth of field".
Compara "a fisherman on a dock" con "a weathered fisherman mending a net on a dock at dawn, overcast light, 35mm photograph, visible grain". El segundo prompt restringe el modelo hacia la textura y la iluminación de la fotografía, en lugar de una representación genérica.
Inclinarse hacia el estilo ilustrado
La ilustración se trata de nombrar la tradición, la calidad de la línea y la paleta — y a menudo de eliminar las pistas fotográficas que acabas de aprender.
- Nombra el estilo: "flat vector illustration", "ink and watercolor", "mid-century editorial illustration", "isometric line art".
- Nombra la línea: "clean uniform strokes", "loose gestural linework".
- Nombra la paleta: "restrained two-color palette", "muted pastels".
Iterar, no preestablecer
Trata el prompt como configuración ajustable. Cambia una dimensión a la vez — reemplaza solo la frase del medio, mantén el sujeto y la iluminación sin cambios — para que aprendas qué hace cada token. Mantén un registro breve de las variantes de prompt y sus salidas; ese registro vale más que cualquier biblioteca de preajustes, porque está calibrado para tu modelo y tu contenido.
Si la solicitud expone parámetros más allá del prompt — tamaño, semilla o similares — ajústalos después de fijar el prompt, no antes. Cambiar el prompt y tres parámetros a la vez no te dice qué cambio fue el responsable.
Diagnosticar errores comunes
La mayoría de las fallas en la primera llamada se pueden agrupar en cuatro categorías. Sigue la lista de verificación en orden; cada paso elimina una capa.
Fallas de autenticación
Síntoma: 401 o 403, con un mensaje sobre credenciales o permisos.
- ¿Está
HIAPI_API_KEYrealmente configurada en el shell que ejecuta el comando?echo $HIAPI_API_KEY— una cadena vacía se parece mucho a una clave incorrecta. - ¿El encabezado es exactamente
Authorization: Bearer <key>? Falta deBearer, comillas sobrantes o un salto de línea pegado en la clave causarán fallas. - ¿La clave fue revocada o está limitada a un entorno diferente? En caso de duda, regénérala y vuelve a probar con curl.
Payload de solicitud mal formado
Síntoma: 400, con un mensaje sobre el cuerpo, los campos o el análisis de JSON.
- Valida el JSON antes de enviar. En curl, una comilla sin escapar dentro del prompt rompe el cuerpo. En Python,
json=maneja esto por ti — otra razón para preferirlo. - Verifica la presencia de
Content-Type: application/json. - Compara los nombres de los campos con la referencia de la API. Un valor escrito correctamente bajo un nombre de campo incorrecto sigue siendo un 400.
- Vuelve al payload mínimo — solo modelo y prompt — confirma que funciona y luego añade campos uno por uno.
Identificador de modelo incorrecto
Síntoma: 404, o 400 indicando que el modelo es desconocido o no está disponible.
- Compara tu cadena carácter por carácter con
krea-3/text-to-image. El prefijo del espacio de nombres, los guiones y el segmento de ruta importan. - Verifica si se introdujeron espacios en blanco o comillas tipográficas no deseadas al copiar y pegar desde la documentación.
- Confirma que el valor no está siendo sobrescrito por un valor predeterminado de configuración en algún lugar del código.
Respuestas de límite de velocidad y cuota
Síntoma: 429, o un mensaje sobre límites o saldo insuficiente.
- Retrocede y reintenta después de un breve retraso, en lugar de martillar el endpoint.
- Revisa tu uso y saldo en el panel.
- Si esto ocurre durante el desarrollo, busca un bucle de reintentos que se dispare más rápido de lo que crees — una solicitud fallida dentro de un bloque
trycombinada con reintentos agresivos agotará los límites rápidamente.
Si nada de lo anterior lo resuelve, captura el ID de solicitud completo y el cuerpo del error de la respuesta y envíalos a soporte. Los cuerpos de error en una API agregadora suelen ser lo suficientemente específicos como para indicar el problema; el error es parafrasearlos en lugar de pegarlos.
Pasar a producción
Tu solicitud actual es un prototipo. Cuatro prácticas la convierten en algo que puede ejecutarse de forma sostenida.
Manejar errores por categoría, no por cadena
Asigna los códigos de estado HTTP a comportamientos: los errores de autenticación son defectos de configuración que deben alertar a alguien; los errores de payload 4xx son defectos de código que deben hacer fallar la solicitud ruidosamente; 429 y 5xx son transitorios y deben reintentarse con retroceso exponencial y jitter. Nunca reintentes un 400 — solo desperdiciarás cuota confirmando el mismo defecto. Establece tiempos de espera explícitos y trata los tiempos de espera como transitorios.
if response.status_code == 429 or response.status_code >= 500:
raise TransientError(response.status_code)
response.raise_for_status()
Registrar prompts y versionarlos
Cada imagen generada debe ser rastreable hasta el prompt exacto que la produjo. Almacena el prompt, el identificador del modelo, los parámetros y el ID de solicitud de la respuesta juntos. Trata el texto del prompt como configuración versionada — una cadena prompt_v3 registrada en un archivo de configuración, no un literal enterrado en una función. Cuando la calidad de la salida cambie, necesitarás saber si fue el prompt, los parámetros o el modelo lo que cambió.
Mantener el nombre del modelo en la configuración
krea-3/text-to-image debería aparecer solo una vez, en una constante o entrada de configuración. Esa es exactamente la recompensa del modelo agregado: reemplazar el modelo, ejecutar comparaciones o revertir se convierten en cambios de configuración, no en el despliegue de una nueva ruta de código. También hace que sea trivial enrutar diferentes cargas de trabajo a diferentes modelos en el futuro.
Probar contra fixtures
Guarda las respuestas exitosas capturadas en este tutorial como fixtures. Afirma que tu código de análisis puede manejarlas y usa los cuerpos de error registrados para probar el mapeo de errores. Detectarás la deriva de la estructura de respuesta antes que tus usuarios.
Comienza con la llamada curl mínima, confirma la estructura de respuesta, migra a Python tal cual y luego itera el prompt una dimensión a la vez — y consulta la referencia de la API de HiAPI para los detalles del endpoint que puedan cambiar.
Artículos relacionados
Ver todos los artículos →-
Tutorial
Guía práctica de gpt-6.2-sol: 5 usos de alto valor de los modelos de texto en el negocio
-
Tutorial
Guía práctica de gpt-6.2-astra: puntos clave de integración e implementación en 5 escenarios de texto de alto valor
Lista de verificación desde la perspectiva del desarrollador: de la selección de escenarios a la implementación en ingeniería
-
Tutorial
Casos prácticos de Tripo H3.1: 5 usos de alto valor y puntos clave de implementación
De texto a 3D a la reconstrucción multivista: elige el modo y los parámetros correctos según el escenario de negocio