Cómo usar la API de Qwen Image 2.1 Turbo: curl, Python y una solicitud probada en la práctica

Qwen Image 2.1 Turbo (qwen-image-2.1-turbo) es el nivel rápido y de bajo precio de la serie de imágenes 2.1 de Alibaba en hiapi. Recibe una indicación de texto, opcionalmente de 0 a 10 imágenes de referencia, y devuelve un PNG de 2048×2048. Esta guía presenta una solicitud lista para ejecutar, el esquema de entrada que la API aplica realmente, una llamada de edición y los resultados que vimos al probar la afirmación de «PNG transparente».

Necesitas una clave de API de hiapi desde la consola. Las llamadas van a través de la API unificada de tareas asíncronas, por lo que no hay respuesta de imagen síncrona.

Solicitud mínima: texto a imagen

curl -s -X POST https://www.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen-image-2.1-turbo",
    "input": {
      "prompt": "Ilustración estilo pegatina: un shiba inu con sombrero de paja sentado en una tabla de surf, colores planos, contornos gruesos, naranja coral y azul marino",
      "aspect_ratio": "1:1",
      "seed": 42
    }
  }'
# {"code":200,"data":{"taskId":"tk-hiapi-..."},"message":"success"}

Luego consulta repetidamente GET /v1/tasks/<taskId> hasta que data.status sea success y lee data.output[0].url.

import os, time, requests

BASE = "https://www.hiapi.ai"
HEADERS = {"Authorization": f"Bearer {os.environ['HIAPI_KEY']}"}

def run(input_: dict) -> str:
    r = requests.post(f"{BASE}/v1/tasks", headers=HEADERS, timeout=30,
                      json={"model": "qwen-image-2.1-turbo", "input": input_})
    r.raise_for_status()
    task_id = r.json()["data"]["taskId"]          # Nota: el campo es taskId, no id

    while True:
        try:
            d = requests.get(f"{BASE}/v1/tasks/{task_id}", headers=HEADERS, timeout=30).json()["data"]
        except requests.RequestException:
            time.sleep(3)                          # Error de red temporal: sigue consultando el mismo id
            continue
        if d["status"] == "success":
            return d["output"][0]["url"]
        if d["status"] in ("fail", "failed"):
            raise RuntimeError(d)
        time.sleep(3)                              # pending / running / archiving

url = run({"prompt": "a straw-hat shiba on a surfboard, flat sticker style", "aspect_ratio": "1:1"})
open("out.png", "wb").write(requests.get(url, timeout=60).content)

Descarga el archivo de inmediato. La URL de salida está en temp.hiapi.ai, con una marca de tiempo expireAt (aproximadamente siete días después de la creación en nuestra ejecución); si necesitas conservarlo más tiempo, guarda tú mismo los bytes del archivo.

Esquema de entrada (las reglas que la API aplica realmente)

Lo siguiente proviene de los errores de validación devueltos cuando enviamos solicitudes inválidas a propósito, por lo que refleja el comportamiento real del endpoint en producción, no la paráfrasis de la documentación:

Campo	Regla
prompt	Cadena obligatoria (el formulario de la página del modelo fija su límite en 4500 caracteres)
aspect_ratio	Uno de estos valores: 1:1, 16:9, 9:16, 4:3, 3:4
image_urls	Arreglo de URL de imágenes de referencia, de 0 a 10 elementos; pasar una cadena directamente se rechaza con image_urls must be an array
prompt_extend	Booleano, interruptor de optimización de la indicación
seed	Entero, de 0 a 2147483647

Hay dos puntos que difieren de otros modelos Qwen de la misma serie. Aquí no hay campo resolution: enviarlo devuelve additional properties 'resolution' not allowed. Para 1:1, la salida es un lienzo fijo de 2048×2048, lo cual comprobamos en la práctica. Además, los campos desconocidos suelen rechazarse en lugar de ignorarse. Un aspect_ratio incorrecto devuelve HTTP 400 con error_code: INVALID_REQUEST y enumera los valores permitidos en message.

Edición con imágenes de referencia

La edición y el repintado de estilo usan el mismo id de modelo. Coloca la imagen de origen en image_urls y describe la modificación en la indicación:

curl -s -X POST https://www.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_KEY" -H "Content-Type: application/json" \
  -d '{
    "model": "qwen-image-2.1-turbo",
    "input": {
      "prompt": "Recolorea el sombrero de paja en morado oscuro, mantén el resto sin cambios",
      "image_urls": ["https://temp.hiapi.ai/.../source.png"],
      "aspect_ratio": "1:1",
      "seed": 42
    }
  }'

Lo que observamos en ejecuciones reales

Ejecutamos una llamada de texto a imagen y una llamada de edición el 2026-10-24, ambas con seed: 42 y aspect_ratio: "1:1".

• Latencia: la generación de texto a imagen alcanzó success aproximadamente 29 segundos después de su creación (marcas de tiempo de created a completed de la tarea); la edición tardó unos 22 segundos. El estado pasa por archiving durante varias consultas antes de llegar a success, así que no consideres un estado no terminal como un error. Estas son solo dos muestras, no una prueba de rendimiento.
• Salida: ambas devolvieron PNG de 2048×2048; el resultado de texto a imagen pesó aproximadamente 3,9 MB.
• Comportamiento de edición: volvimos a introducir la primera salida y pedimos cambiar el sombrero a morado. El resultado conservó el perro, la pose, las olas y la composición, y desplazó la banda y la cinta del sombrero hacia el morado; el cuerpo de paja del sombrero siguió siendo básicamente de color paja. Para cambios de color en objetos con textura, el grado de seguimiento de instrucciones de la edición puede ser solo parcial; conviene escribir indicaciones específicas (por ejemplo, «recolorea la banda del sombrero») en lugar de descripciones genéricas.
• Fondo transparente: el canal alfa es completamente opaco. La página del modelo promociona la salida de PNG con fondo transparente, y en la indicación escribimos «fondo completamente transparente, conserva solo el sujeto y el efecto de salpicadura». El archivo devuelto es RGBA, pero el alfa de cada píxel es 255 (cero píxeles transparentes), y las cuatro esquinas son de un blanco grisáceo claro (por ejemplo, (241, 243, 248, 255)). Al examinar la imagen, descubrimos que el modelo dibujó un fondo tenue con estilo de tablero de ajedrez en los píxeles en lugar de dejar esos píxeles transparentes. La salida de edición se comportó igual (alfa mínimo de 241). Por lo tanto, en nuestra ejecución, solo con la indicación no obtuvimos un recorte listo para colocar sobre una página de color. Este resultado corresponde solo a una forma de escribir la indicación; no encontramos ningún campo de solicitud para alternar la transparencia (transparent se rechaza por ser una propiedad desconocida). Si necesitas un canal alfa real, planifica un paso de eliminación de fondo, por ejemplo consultando la guía de eliminación de fondo de 851-labs, y verifícalo antes de publicar con una comprobación de píxeles como Image.open(f).getchannel("A").getextrema().

Consideraciones para producción

• Usa devoluciones de llamada en lugar de sondeos con alta concurrencia: añade "callback": {"url": "https://your.app/hook", "when": "final"} al cuerpo de la solicitud de la tarea, trata la devolución de llamada como una pista y luego confirma el resultado con GET /v1/tasks/<taskId>.
• Conserva el taskId: si el sondeo falla por un error de red, vuelve a consultar el mismo id en lugar de reenviar la solicitud. Reenviarla crea y factura una segunda tarea.
• Fija seed para obtener salidas comparables mientras ajustas la indicación; considéralo un esfuerzo de mejor nivel, no una garantía estricta.
• Valida antes de facturar: los errores de esquema (HTTP 400, INVALID_REQUEST) se devuelven en el momento de la creación, cuando aún no se ha generado ninguna imagen.

Qué nivel elegir

En la misma serie también está Qwen Image 2.1 Pro, cuyo precio por imagen indicado en la página de precios es superior al de Turbo. Ambos se describen como compatibles con texto a imagen, edición y de 0 a 10 imágenes de referencia; nosotros solo ejecutamos Turbo, por lo que no hacemos ninguna afirmación sobre la calidad relativa de las imágenes. La ventaja de Turbo es su precio más bajo y su velocidad de 8 pasos; si tu material valora más la calidad de salida, ejecuta ambos con la misma indicación y seed y compáralos. Para la generación más reciente Qwen 3.0, consulta la guía de la API de Qwen Image 3.0 y la guía de Qwen Image 3.0 Pro.

Contenido relacionado

• Página del modelo Qwen Image 2.1 Turbo
• Precios
• Guía de la API de Qwen Image 3.0
• Documentación

Preguntas frecuentes

¿Cuál es el id del modelo? qwen-image-2.1-turbo, enviado mediante POST /v1/tasks.

¿Se puede elegir la resolución de salida? En este esquema no: no hay campo resolution. Elige uno de los cinco valores permitidos para aspect_ratio.

¿Se admite la edición? Sí: pasa de 1 a 10 imágenes de origen en image_urls junto con una indicación de instrucciones. En nuestras pruebas, la edición de color en zonas con textura solo funcionó parcialmente.

¿Devuelve PNG transparentes? En nuestras pruebas no: el archivo está en modo RGBA, pero el canal alfa es completamente opaco y tiene un fondo dibujado. Verifica tú mismo el alfa y, si necesitas transparencia real, añade un paso de eliminación de fondo.

¿Cuál es el precio? Consulta la página de precios; en el momento de escribir esto, es el más económico de los dos niveles 2.1.