Tutorial
Cómo usar qwen-image-2.0-pro a través de la API de HiAPI: curl, Python y una solicitud que funciona
Ejercicio práctico de integración para desarrolladores: primera llamada exitosa, anatomía de la estructura de la solicitud y diagnóstico de fallos
En esta página
Qué ofrece qwen-image-2.0-pro a los usuarios de la API
qwen-image-2.0-pro es un modelo de generación de imágenes que se invoca por HTTP. Desde la perspectiva de tu código, se comporta de forma similar a un endpoint de chat completions: envías una carga JSON que describe la imagen deseada y recibes una respuesta JSON que contiene la imagen generada.
La ventaja de acceder a él a través de la API de HiAPI es la consistencia. Una clave de API, una URL base y una estructura de solicitud comunes a todos los modelos. Si más adelante cambias el identificador del modelo o ajustas los parámetros, el código circundante no cambia. No necesitas aprender un SDK nuevo ni gestionar múltiples conjuntos de credenciales para cada modelo de imagen que pruebes.
Este tutorial primero completa una primera llamada de principio a fin con curl, luego la traslada a Python, explica cómo leer la imagen de la respuesta y finalmente ofrece una lista de verificación para el diagnóstico y un pequeño contenedor reutilizable. Todos los ejemplos usan la misma carga y la misma variable de entorno para la clave, de modo que lo que funciona en la terminal se ejecuta en el script sin cambios.
Requisitos previos y preparación de la clave
Antes de escribir cualquier código, asegúrate de que las siguientes tres cosas estén listas.
1. Cuenta de HiAPI y clave de API
Crea una cuenta y genera una clave de API en el panel de control. La clave es información confidencial; trátala como una contraseña. No la pegues en archivos de código fuente que se vayan a confirmar en el control de versiones.
2. Exporta la clave como variable de entorno
Los ejemplos siguientes leen la clave de HIAPI_API_KEY, de modo que los mismos comandos y scripts funcionan sin modificaciones tanto en local como en CI.
export HIAPI_API_KEY="your_key_here"
En Windows PowerShell, usa $env:HIAPI_API_KEY = "your_key_here". En CI, configúrala como una variable de entorno secreta en la configuración del pipeline.
3. Herramienta para realizar solicitudes HTTP
curl suele venir preinstalado. Para Python, necesitas Python 3 y la biblioteca requests:
pip install requests
Antes de continuar, puedes confirmar que la shell ve la clave:
# macOS / Linux
echo "${HIAPI_API_KEY:0:4}..."
Si no aparece nada, la variable no está configurada y todas las solicitudes fallarán con un error de autenticación. Resuelve esto primero.
Solicitud mínima viable con curl
La forma más rápida de confirmar la conectividad es ejecutar una llamada con curl que lea la clave de la variable de entorno. La carga es un objeto JSON que contiene el campo model y un arreglo messages al estilo de chat completions.
curl -sS https://api.hiapi.ai/v1/chat/completions \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "qwen-image-2.0-pro",
"messages": [
{
"role": "user",
"content": "A small ceramic mug on a wooden table, soft morning light, product photo"
}
]
}'
Tres detalles importantes aquí. El encabezado Authorization usa el esquema Bearer. El valor de model debe coincidir exactamente con el identificador del modelo. content es una cadena de texto sin formato que describe la imagen.
Si la solicitud tiene éxito, verás la respuesta JSON impresa en la terminal. Si falla, verás el código de estado HTTP y el mensaje de error. Comprueba el código de estado antes de leer el cuerpo de la respuesta: 401 indica una clave incorrecta o ausente, 400 suele indicar un formato de carga incorrecto, y 404 o un error de modelo no encontrado indica un identificador de modelo incorrecto.
Una vez que este comando devuelve una respuesta exitosa, se confirma que la conectividad es correcta y puedes pasar a escribir código.
La misma solicitud en Python
Al trasladar la llamada a Python, mantén la carga idéntica. La única diferencia está en cómo se lee la variable de entorno y se serializa la solicitud.
import json
import os
import requests
api_key = os.environ["HIAPI_API_KEY"]
payload = {
"model": "qwen-image-2.0-pro",
"messages": [
{
"role": "user",
"content": "A small ceramic mug on a wooden table, soft morning light, product photo",
}
],
}
response = requests.post(
"https://api.hiapi.ai/v1/chat/completions",
headers={
"Authorization": f"Bearer {api_key}",
"Content-Type": "application/json",
},
json=payload,
timeout=120,
)
response.raise_for_status()
data = response.json()
print(json.dumps(data, indent=2))
Observa que json=payload hace que requests configure automáticamente el encabezado Content-Type y serialice el cuerpo de la solicitud. El timeout es importante porque la generación de imágenes puede tardar más que una típica completación de texto; 120 segundos es un punto de partida razonable. raise_for_status() convierte los códigos de estado de error en excepciones, de modo que un fallo no pasa desapercibido.
Ejecuta este script y deberías obtener el mismo JSON que viste con curl. Si no es así, tu entorno difiere de la shell donde curl funcionó; lo más habitual es la variable de la clave.
Leer la respuesta y manejar la salida de imagen
La respuesta sigue la estructura de chat completions, por lo que la imagen generada se obtiene por la misma vía que usarías para una respuesta de texto. Primero examina el JSON impreso; su estructura te resultará familiar:
{
"choices": [
{
"message": {
"role": "assistant",
"content": "..."
}
}
]
}
La imagen generada aparece en el contenido del mensaje del asistente, normalmente como una URL o una carga codificada en base64, según cómo el modelo devuelva los medios. No asumas cuál de las dos es; lee el valor y ramifica según su prefijo:
content = data["choices"][0]["message"]["content"]
if isinstance(content, str) and content.startswith("http"):
image_url = content
# Download and save if you want a local copy
image_bytes = requests.get(image_url, timeout=60).content
with open("output.png", "wb") as f:
f.write(image_bytes)
print("saved output.png from URL")
else:
# Treat as base64-encoded image data
import base64
image_bytes = base64.b64decode(content)
with open("output.png", "wb") as f:
f.write(image_bytes)
print("saved output.png from base64")
Dos notas prácticas. Si el contenido es una URL, trátala como un enlace temporal y descárgala cuanto antes, en lugar de enlazarla directamente en tu producto. Si es base64, aísla el proceso de decodificación para que una carga mal formada lance un error capturable. Antes de analizar, escribe siempre la respuesta sin procesar en un archivo de registro, para poder depurar sin volver a ejecutar una solicitud que puede ser lenta.
Lista de verificación para solicitudes fallidas
Cuando una solicitud falla, no te apresures a reescribir toda la llamada. Realiza las siguientes comprobaciones en orden y detente en la primera que falle. Cada comprobación aísla una variable.
1. Autenticación
Comprueba primero el código de estado. 401 indica que la clave falta, ha caducado o tiene un formato incorrecto. Confirma que la variable de entorno está configurada en la shell actual, que usaste el prefijo Bearer y que el encabezado no tiene espacios finales.
2. Identificador del modelo
Un error de modelo no encontrado indica que el valor de model no coincide exactamente con un modelo disponible. Tanto las mayúsculas y minúsculas como los sufijos importan. Compara tu valor carácter por carácter con la página de documentación del modelo.
3. Estructura de la carga
Un 400 suele provenir de un cuerpo de solicitud mal formado. Confirma que messages es un arreglo, que cada mensaje contiene role y content, y que el JSON es válido. Procesar la carga con jq o python -m json.tool antes de enviarla puede detectar errores de sintaxis.
4. Manejo de la respuesta
Si la solicitud tiene éxito pero el script falla, el problema está en el código de análisis, no en la API. Registra el cuerpo de la respuesta sin procesar antes de hacer slicing y confirma que la ruta que lees realmente existe. La imagen puede devolverse como URL en una llamada y como base64 en otra, así que ramifica según el contenido en lugar de asumir.
5. Tiempos de espera y reintentos
La generación de imágenes puede ser lenta. Si se agota el tiempo de espera, aumenta el timeout del cliente y reintenta una vez. Evita reintentar errores 4xx, ya que volverán a fallar de la misma manera.
Un hábito útil: guarda una copia de una solicitud que sabes que funciona y compárala con la que falla. La mayoría de los fallos difieren en un solo campo.
Encapsular en un cliente reutilizable
Una vez que la llamada funciona, encapsúlala detrás de una pequeña función para que los cambios de modelo y parámetros queden centralizados en un solo lugar. Este contenedor gestiona de forma centralizada la búsqueda de la clave, los encabezados y el manejo de errores:
import base64
import os
import requests
HIAPI_BASE = "https://api.hiapi.ai/v1"
DEFAULT_MODEL = "qwen-image-2.0-pro"
def generate_image(prompt: str, model: str = DEFAULT_MODEL) -> bytes:
"""Generate an image and return its raw bytes."""
api_key = os.environ["HIAPI_API_KEY"]
payload = {
"model": model,
"messages": [{"role": "user", "content": prompt}],
}
response = requests.post(
f"{HIAPI_BASE}/chat/completions",
headers={"Authorization": f"Bearer {api_key}"},
json=payload,
timeout=120,
)
response.raise_for_status()
content = response.json()["choices"][0]["message"]["content"]
if isinstance(content, str) and content.startswith("http"):
return requests.get(content, timeout=60).content
return base64.b64decode(content)
El código de llamada se reduce a una línea: open("out.png", "wb").write(generate_image("A ceramic mug on a wooden table")). Si más adelante cambias a otro modelo de imagen o añades parámetros, solo tienes que modificar esta función. El identificador del modelo y cualquier detalle de los parámetros están en la página del modelo; puedes consultar primero los detalles del modelo qwen-image-2.0-pro antes de integrarlo.
Empieza con la llamada curl, luego el script de Python y finalmente el contenedor. Cada paso confirma una parte más pequeña antes de construir el siguiente nivel.
Artículos relacionados
Ver todos los artículos →-
Tutorial
Casos prácticos de aplicación de kling-image-4.0: 5 usos de alto valor y puntos clave de integración
-
Tutorial
Cómo llamar a gemini-omni-1.1-flash mediante la API de HiAPI: guía con curl y Python
-
Tutorial
Cómo llamar a la API de texto a video veo-3.1: ejemplos con curl y Python
Guía práctica de integración para desarrolladores