Integração com a API do Qwen Image 3.0 Pro: curl, Python e todos os parâmetros

O Qwen Image 3.0 Pro (通义千问图像 3.0 Pro) tem duas entradas na HiAPI: texto para imagem qwen-image-3.0-pro/text-to-image e imagem para imagem qwen-image-3.0-pro/image-to-image. Ele custa mais que a versão padrão, mas entrega detalhes e materiais mais ricos, e continua escrevendo texto em chinês e inglês com precisão. Este artigo traz exemplos de curl e Python prontos para executar, todos os parâmetros atuais e alguns pontos de atenção antes de ir para produção.

Os nomes de modelo antigos qwen-image-3.0-pro e o campo size não funcionam mais: o nome antigo retorna MODEL_UNAVAILABLE e o size é rejeitado como campo desconhecido. Use os dois nomes de modelo acima, junto com aspect_ratio e resolution.

Preços primeiro

	1K (padrão)	2K
Pro texto para imagem / imagem para imagem	$0.0497	$0.0993
Versão padrão texto para imagem / imagem para imagem (comparação)	$0.0358	$0.0358

Preços atuais da HiAPI, verificados em 18 de outubro de 2026.

O Pro 1K custa cerca de 39% mais que a versão padrão, e o 2K custa cerca de 2,8 vezes o valor da versão padrão. As 1–3 imagens de referência do imagem para imagem não custam a mais. Falhas não são cobradas.

Uma imagem real gerada

16:9. A placa de latão sobre a mesa com “深海来信” e a linha menor abaixo, “LETTERS FROM THE DEEP”, foram escritas corretamente palavra por palavra:

High-end cinematic architectural editorial photograph inside a futuristic underwater restaurant at midnight. A vast curved observation window fills the background with deep cobalt water and luminous translucent jellyfish drifting outside. On the right, a sculptural dining table of black stone, hand-blown glass and restrained brushed brass catches a narrow beam of warm light. A small refined brass menu plaque on the table is naturally photographed and contains only the exact Chinese characters “深海来信”; directly below, the exact English words “LETTERS FROM THE DEEP”. The left third remains calm dark-blue negative space with volumetric light rays. No poster layout; this must feel like an expensive real location photographed for an architecture magazine. cinematic composition, dramatic directional lighting, rich cohesive cobalt-and-gold color grade, ultra-detailed, premium commercial finish, subtle film grain, shallow depth of field, high dynamic range, 16:9 hero composition

Gerar com este prompt →

qwen-image-3.0-pro/text-to-image, 16:9, imagem de exemplo da página do modelo.

Gerando a primeira imagem

Preparação: crie uma API Key no console. Novos usuários ganham 200 créditos ao se registrar.

curl

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen-image-3.0-pro/text-to-image",
    "input": {
      "prompt": "一只青瓷茶壶放在胡桃木桌上，清晨的侧光，茶壶旁的小卡片上写着「雨前龙井」",
      "aspect_ratio": "4:3",
      "resolution": "1K",
      "prompt_extend": false
    }
  }'

Após receber o taskId, consulte o resultado:

curl -s https://api.hiapi.ai/v1/tasks/tk-hiapi-... \
  -H "Authorization: Bearer $HIAPI_KEY"

Quando data.status for success, a imagem estará em data.output[0].url. Esse é um link temporário; baixe e armazene assim que o receber.

Python

import os, time, requests

KEY = os.environ["HIAPI_KEY"]
BASE = "https://api.hiapi.ai/v1"
H = {"Authorization": f"Bearer {KEY}", "Content-Type": "application/json"}

r = requests.post(f"{BASE}/tasks", headers=H, json={
    "model": "qwen-image-3.0-pro/text-to-image",
    "input": {
        "prompt": "一只青瓷茶壶放在胡桃木桌上，清晨的侧光，茶壶旁的小卡片上写着「雨前龙井」",
        "aspect_ratio": "4:3",
        "resolution": "1K",
        "prompt_extend": False,
    },
})
task_id = r.json()["data"]["taskId"]

while True:
    d = requests.get(f"{BASE}/tasks/{task_id}", headers=H).json()["data"]
    if d["status"] in ("success", "fail"):
        break
    time.sleep(5)

if d["status"] == "success":
    open("result.png", "wb").write(requests.get(d["output"][0]["url"]).content)
else:
    print(d)

Todos os parâmetros

Campo	Obrigatório	Valores	Descrição
prompt	Sim	Até 18000 caracteres	Conteúdo, estilo e composição da imagem; escreva entre aspas o texto que deve aparecer
image_urls	Obrigatório para imagem para imagem	1–3 imagens	JPEG/PNG/WEBP/BMP/GIF/TIFF, ≤10MB por imagem, SVG não suportado
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	Define o preço
output_format	Não	png (padrão) / jpeg
prompt_extend	Não	Booleano, padrão true	Reescreve automaticamente o prompt; defina como false quando precisar que o texto saia exatamente igual
negative_prompt	Não	Até 500 caracteres	O que você não quer que apareça
seed	Não	0–2147483647	Fixo para facilitar a reprodução

Exemplo de imagem para imagem:

{
  "model": "qwen-image-3.0-pro/image-to-image",
  "input": {
    "prompt": "把这张产品图修成高端杂志风格，保留瓶身形状和标签上的文字",
    "image_urls": ["https://example.com/product.jpg"],
    "aspect_ratio": "1:1",
    "resolution": "2K",
    "prompt_extend": false
  }
}

Erros comuns

Todos retornam HTTP 400 de forma síncrona no momento do envio, sem criar tarefa e sem cobrança:

• MODEL_UNAVAILABLE: foi usado o nome de modelo antigo qwen-image-3.0-pro; altere para o nome com /text-to-image ou /image-to-image.
• additional properties 'size' not allowed: o size não é mais aceito; use aspect_ratio com resolution.
• resolution: value must be one of '1K', '2K': o Pro não tem 4K.
• image_urls: minItems: got 0, want 1: imagem para imagem exige pelo menos 1 imagem de referência.

Atenção antes de ir para produção

• Desative prompt_extend ao escrever texto: a reescrita automática pode alterar os caracteres que você deseja.
• Use callback em vez de polling: adicione no nível superior do corpo da requisição "callback": {"url": "https://seu-dominio/hiapi/callback", "when": "final"} e deduplique por taskId.
• Evite cobrança duplicada: inclua o cabeçalho Idempotency-Key no envio e reutilize a mesma key nas retentativas por timeout.
• Armazene a tempo: os links de saída expiram.

Perguntas frequentes

Como escolher entre o Pro e a versão padrão?

Comece testando a versão padrão, $0.0358 por imagem, com o mesmo preço para 1K e 2K. Se os detalhes da versão padrão não forem suficientes, mude para o Pro. Para a integração da versão padrão, veja Integração com a API do Qwen Image 3.0.

É possível gerar em 4K?

Não, apenas 1K e 2K.

Qual é o número máximo de imagens de referência?

3 imagens, sem custo adicional.

Você também pode copiar diretamente o prompt do restaurante subaquático acima e gerar na página do modelo.