HiAPI
Blog

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

Nov 17, 2026
Imagen de portada minimalista con capas de papel superpuestas: sobre un fondo color crema, varias hojas finas de color grafito se escalonan y retroceden en una profundidad de campo reducida, con una hoja de color terracota en el centro como acento.
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 →

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