Como usar a API do Qwen Image 3.0? Escreva um pôster em chinês certo de primeira

TL;DR

• O Qwen Image 3.0 (Tongyi Qianwen Image 3.0) tem 4 entradas no HiAPI: as versões padrão qwen-image-3.0/text-to-image, qwen-image-3.0/image-to-image, e as versões Pro qwen-image-3.0-pro/text-to-image, qwen-image-3.0-pro/image-to-image. Abra a página do modelo para testar online.
• A versão padrão tem preço fixo de $0.0358 por imagem (1K e 2K têm o mesmo preço); o Pro custa $0.0497 em 1K e $0.0993 em 2K. Editar imagem e gerar imagem têm o mesmo preço, e de 1 a 3 imagens de referência não têm custo extra.
• Chinês e textos bilíngues chinês-inglês são o ponto forte. Como chamar: POST /v1/tasks enviando prompt, aspect_ratio, resolution, e faça polling até success para então baixar.

Veja uma primeiro

Versão padrão, 16:9, os caracteres chineses da placa escritos corretamente, um por um:

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

Consulta rápida de parâmetros

Campo	Obrigatório	Valores	Descrição
prompt	Sim	Até 18000 caracteres	Escreva o texto que deve aparecer, literalmente, entre aspas
aspect_ratio	Não	1:1 (padrão) 3:2 2:3 4:3 3:4 16:9 9:16 21:9
resolution	Não	1K (padrão) / 2K	Na versão padrão as duas faixas têm o mesmo preço; no Pro, 2K custa o dobro
output_format	Não	png (padrão) / jpeg
prompt_extend	Não	Booleano, padrão true	Reescreve automaticamente o prompt; desligue quando precisar de texto exato
negative_prompt	Não	Até 500 caracteres	O que você não quer que apareça
seed	Não	0–2147483647	Fixe para facilitar a reprodução
image_urls	Obrigatório na entrada de edição de imagem	1–3 imagens	JPEG, PNG, WEBP etc., cada uma com no máximo 10 MB

Os parâmetros são validados rigorosamente; enviar campos extras retorna 400. Atenção: o formato antigo "model": "qwen-image-3.0" com size não funciona mais e retorna 「modelo indisponível」 ou additional properties 'size' not allowed. Mude para o nome de modelo acima e aspect_ratio + resolution.

curl: gere a primeira imagem

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
    }
  }'

A resposta traz data.taskId. Faça polling em GET /v1/tasks/{taskId} e, quando status virar success, baixe de output[0].url. Na versão padrão, 2K e 1K têm o mesmo preço, então peça 2K direto.

Python: gerar imagem primeiro, depois editar

# pip install requests; export HIAPI_KEY=你的 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 trocar para o Pro, basta mudar o nome do modelo: qwen-image-3.0-pro/text-to-image ou qwen-image-3.0-pro/image-to-image; os parâmetros são exatamente os mesmos.

Quanto custa

Entrada	1K	2K
Versão padrão texto-para-imagem / edição de imagem	$0.0358	$0.0358
Pro texto-para-imagem / edição de imagem	$0.0497	$0.0993

Preço atual do HiAPI, verificado em 18 de outubro de 2026. Falhas não são cobradas.

Para comparar as duas faixas com o mesmo prompt, veja Preços da API do Qwen Image 3.0.

Atenção antes de ir ao ar

• Desligue prompt_extend quando precisar de texto exato: por padrão ele reescreve seu prompt e pode alterar os caracteres que você quer.
• Escreva o texto que deve aparecer, literalmente, entre aspas, e acrescente uma frase como 「não inclua outro texto além do acima」.
• Use callback em vez de polling: no mesmo nível de input, adicione "callback": {"url": "https://your-app.example.com/hiapi/callback", "when": "final"} e deduplique por taskId.
• Inclua o cabeçalho Idempotency-Key; em retentativas, a mesma Key cria a tarefa apenas uma vez.
• Baixe o resultado imediatamente: output[0].url tem prazo de validade.

Perguntas frequentes

Qual é a diferença entre a versão padrão e o Pro?

Os parâmetros são iguais; o Pro tem mais detalhes visuais e maior densidade de layout, custa cerca de 39% mais em 1K e o dobro em 2K. O texto em chinês sai preciso nas duas faixas.

Quantas imagens posso enviar na edição de imagem?

De 1 a 3, em image_urls, sem custo extra.

Por que meu código antigo retorna 「model not available」?

O nome de modelo antigo qwen-image-3.0 foi descontinuado; use qwen-image-3.0/text-to-image; o parâmetro size também foi substituído por aspect_ratio e resolution.

Você também pode ir direto à página do modelo e testar um pôster em chinês.