¿Cómo usar la API de Qwen Image 3.0? Escribe un póster en chino bien a la primera

TL;DR

• Qwen Image 3.0 (Tongyi Qianwen Image 3.0) tiene 4 entradas en HiAPI: versión estándar qwen-image-3.0/text-to-image, qwen-image-3.0/image-to-image, y versión Pro qwen-image-3.0-pro/text-to-image, qwen-image-3.0-pro/image-to-image. Abre la página del modelo y pruébalo en línea.
• Precio fijo de la versión estándar: $0.0358 por imagen (1K y 2K al mismo precio); Pro 1K $0.0497, 2K $0.0993. Editar imagen y generar imagen cuestan lo mismo; de 1 a 3 imágenes de referencia no añaden coste.
• El chino y el texto bilingüe chino-inglés son su punto fuerte. Modo de llamada: POST /v1/tasks con prompt, aspect_ratio, resolution, y tras consultar hasta success, descarga el resultado.

Mira una primero

Versión estándar, 16:9, el chino del letrero escrito carácter por carácter correctamente:

qwen-image-3.0/text-to-image, 16:9, $0.0358.

Consulta rápida de parámetros

Campo	Obligatorio	Valores	Descripción
prompt	Sí	Hasta 18000 caracteres	El texto que debe aparecer se escribe literalmente entre comillas
aspect_ratio	No	1:1 (predeterminado) 3:2 2:3 4:3 3:4 16:9 9:16 21:9
resolution	No	1K (predeterminado) / 2K	En la versión estándar ambas opciones cuestan lo mismo; en Pro, 2K cuesta el doble
output_format	No	png (predeterminado) / jpeg
prompt_extend	No	Booleano, por defecto true	Reescribe automáticamente el prompt; desactívalo cuando el texto deba ser exacto
negative_prompt	No	Hasta 500 caracteres	Contenido que no quieres que aparezca
seed	No	0–2147483647	Fijarlo facilita la reproducibilidad
image_urls	Obligatorio en la entrada de edición de imagen	1–3 imágenes	JPEG, PNG, WEBP, etc., máximo 10 MB cada una

Los parámetros se validan estrictamente; enviar campos de más devuelve 400. Nota: la forma antigua "model": "qwen-image-3.0" con size ya no funciona; devolverá «modelo no disponible» o additional properties 'size' not allowed. Cámbialo por el nombre de modelo anterior y aspect_ratio + resolution.

curl: consigue la primera imagen

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen-image-3.0/text-to-image",
    "input": {
      "prompt": "一张秋季饮品海报，中间是一杯桂花拿铁，顶部大标题逐字写“秋日限定”，下方副标题写“桂花拿铁”，留白充足，柔和自然光",
      "aspect_ratio": "3:4",
      "resolution": "2K",
      "prompt_extend": false
    }
  }'

La respuesta incluye data.taskId. Consulta GET /v1/tasks/{taskId}; cuando status cambie a success, descarga desde output[0].url. En la versión estándar 2K y 1K cuestan lo mismo: pide directamente 2K.

Python: primero generar imagen, luego editarla

# pip install requests; export HIAPI_KEY=tu Key
import os, time, uuid, requests

API = "https://api.hiapi.ai/v1/tasks"
H = {"Authorization": f"Bearer {os.environ['HIAPI_KEY']}"}

def run(model, timeout_s=300, **inp):
    # 重试同一次提交时复用同一个 Idempotency-Key，只会扣一次费
    r = requests.post(API, json={"model": model, "input": inp},
                      headers={**H, "Idempotency-Key": str(uuid.uuid4())}, timeout=30)
    r.raise_for_status()
    task_id = r.json()["data"]["taskId"]
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        d = requests.get(f"{API}/{task_id}", headers=H, timeout=30).json()["data"]
        if d["status"] == "success":
            return d["output"][0]["url"]
        if d["status"] in ("fail", "failed"):
            raise RuntimeError(d)
        time.sleep(4)
    raise TimeoutError(task_id)

# 文生图，标准版 2K（$0.0358）
poster = run("qwen-image-3.0/text-to-image",
             prompt="茶叶礼盒产品图，牛皮纸方盒正面写“云雾绿茶”，下方小字“净含量 100 克”，石板台面，柔和顶光",
             aspect_ratio="1:1", resolution="2K", prompt_extend=False)

# 改图：换成深色背景，文字不变（同样 $0.0358）
edited = run("qwen-image-3.0/image-to-image",
             prompt="保持礼盒和上面的文字完全不变，把背景换成深墨绿色绒布，加一缕侧光",
             image_urls=[poster], aspect_ratio="1:1", resolution="2K")

with open("tea.png", "wb") as f:
    f.write(requests.get(edited).content)

Para cambiar a Pro, solo cambia el nombre del modelo: qwen-image-3.0-pro/text-to-image o qwen-image-3.0-pro/image-to-image; los parámetros son exactamente iguales.

Cuánto cuesta

Entrada	1K	2K
Estándar texto a imagen / edición de imagen	$0.0358	$0.0358
Pro texto a imagen / edición de imagen	$0.0497	$0.0993

Precio actual de HiAPI, verificado el 18 de octubre de 2026. Los fallos no se cobran.

Para comparar ambas versiones con el mismo prompt, consulta Precio de la API de Qwen Image 3.0.

A tener en cuenta antes de lanzar

• Desactiva prompt_extend cuando el texto deba ser exacto: por defecto reescribe tu prompt y puede modificar sin querer los caracteres que necesitas.
• Escribe literalmente entre comillas el texto que debe aparecer y añade «除以上文字外不要其他文字».
• Usa callback en lugar de sondeo: al mismo nivel de input añade "callback": {"url": "https://your-app.example.com/hiapi/callback", "when": "final"}, y deduplica por taskId.
• Incluye la cabecera Idempotency-Key; al reintentar, la misma Key solo crea una tarea.
• Descarga el resultado de inmediato: output[0].url tiene caducidad.

Preguntas frecuentes

¿Cuál es la diferencia entre la versión estándar y Pro?

Los parámetros son iguales; Pro tiene más detalle visual y mayor densidad de composición, cuesta aproximadamente un 39% más en 1K y el doble en 2K. En ambas versiones el texto en chino se escribe con precisión.

¿Cuántas imágenes se pueden enviar como máximo para editar?

De 1 a 3, en image_urls, sin coste adicional.

¿Por qué mi código antiguo devuelve «model not available»?

El nombre de modelo antiguo qwen-image-3.0 ya no está disponible; cámbialo por qwen-image-3.0/text-to-image; el parámetro size también se ha sustituido por aspect_ratio y resolution.

También puedes ir directamente a la página del modelo y probar un póster en chino.