Como usar a API Qwen Image 2.1 Turbo: curl, Python e uma requisição testada na prática

Qwen Image 2.1 Turbo (qwen-image-2.1-turbo) é o nível rápido e barato da série de imagens 2.1 da Alibaba no hiapi. Ele recebe um prompt de texto, opcionalmente 0–10 imagens de referência, e retorna um PNG de 2048×2048. Este guia apresenta uma requisição pronta para executar, o schema de entrada que a API realmente aplica, uma chamada de edição e os resultados que observamos ao testar a alegação de "PNG transparente".

Você precisa de uma chave de API do hiapi, obtida no console. As chamadas passam pela API unificada de tarefas assíncronas, portanto não há resposta síncrona de imagem.

Requisição mínima: texto para imagem

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": "ilustração em estilo de adesivo: um shiba inu de chapéu de palha sentado em uma prancha de surfe, cores chapadas, contornos grossos, laranja coral e azul-marinho",
      "aspect_ratio": "1:1",
      "seed": 42
    }
  }'
# {"code":200,"data":{"taskId":"tk-hiapi-..."},"message":"success"}

Em seguida, faça polling em GET /v1/tasks/<taskId> até que data.status seja success e leia 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"]          # atenção: o campo é taskId, não 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)                          # erro de rede temporário: continue o polling do mesmo 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)

Baixe o arquivo imediatamente. A URL de saída fica em temp.hiapi.ai e traz um timestamp expireAt (cerca de sete dias após a criação, na nossa execução); se precisar mantê-lo por mais tempo, salve os bytes do arquivo por conta própria.

Schema de entrada (as regras que a API realmente aplica)

O conteúdo a seguir vem dos erros de validação retornados quando enviamos requisições inválidas de propósito, portanto reflete o comportamento real do endpoint em produção, e não uma paráfrase da documentação:

Campo	Regra
prompt	string obrigatória (o formulário da página do modelo limita a 4500 caracteres)
aspect_ratio	um dos valores 1:1, 16:9, 9:16, 4:3, 3:4
image_urls	array de URLs de imagens de referência, com 0–10 itens; passar uma string diretamente é rejeitado com image_urls must be an array
prompt_extend	booleano, chave de otimização do prompt
seed	inteiro, de 0 a 2147483647

Dois pontos diferem de outros modelos Qwen da mesma série. Aqui não há campo resolution: enviá-lo retorna additional properties 'resolution' not allowed. Para 1:1, a saída é uma tela fixa de 2048×2048, o que verificamos na prática. Além disso, campos desconhecidos em geral são rejeitados em vez de ignorados. Um aspect_ratio inválido retorna HTTP 400 com error_code: INVALID_REQUEST e lista os valores permitidos em message.

Edição com imagens de referência

Edição e repintura de estilo usam o mesmo id de modelo. Coloque as imagens de origem em image_urls e descreva a alteração no prompt:

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": "recolorir o chapéu de palha em roxo-escuro, mantendo o resto inalterado",
      "image_urls": ["https://temp.hiapi.ai/.../source.png"],
      "aspect_ratio": "1:1",
      "seed": 42
    }
  }'

O que observamos em execuções reais

Executamos uma chamada de texto para imagem e uma chamada de edição em 2026-10-24, ambas com seed: 42 e aspect_ratio: "1:1".

• Latência: a geração de texto para imagem atingiu success cerca de 29 segundos após a criação (timestamps de created a completed da tarefa); a edição levou cerca de 22 segundos. O status passa por archiving em alguns ciclos de polling antes de entrar em success, então não trate estados não finais como erro. São apenas duas amostras, não um benchmark.
• Saída: ambas retornaram PNG de 2048×2048, e o resultado do texto para imagem tinha cerca de 3,9 MB.
• Comportamento da edição: reinserimos a primeira saída e pedimos para deixar o chapéu roxo. O resultado preservou o cachorro, a pose, as ondas e o layout, e puxou a fita e o laço do chapéu para o roxo; a parte trançada do chapéu permaneceu basicamente na cor de palha. Para mudanças de cor em objetos com textura, o cumprimento de instruções da edição pode ser apenas parcial; o prompt deve ser específico (por exemplo, "recolorir a fita do chapéu") em vez de uma descrição genérica.
• Fundo transparente: o canal alfa é totalmente opaco. A página do modelo anuncia saída em PNG com fundo transparente, e incluímos no prompt "fundo totalmente transparente, mantendo apenas o sujeito e os respingos". O arquivo retornado era RGBA, mas o alfa de cada pixel era 255 (zero pixels transparentes), com os cantos em cinza-esbranquiçado claro (por exemplo, (241, 243, 248, 255)). Ao examinar a imagem, o modelo desenhou um fundo sutil em estilo de tabuleiro de xadrez nos pixels, em vez de deixá-los transparentes. A saída da edição se comportou da mesma forma (alfa mínimo de 241). Assim, nas nossas execuções, apenas com o prompt não obtivemos um recorte pronto para colocar em uma página colorida. Esse resultado corresponde apenas a uma forma de escrever o prompt; não encontramos um campo de requisição para alternar a transparência (transparent é rejeitado como propriedade desconhecida). Se você precisa de um canal alfa real, planeje uma etapa de remoção de fundo, como o guia do removedor de fundo 851-labs, e valide antes de ir para produção com uma verificação de pixels como Image.open(f).getchannel("A").getextrema().

Considerações para produção

• Use callback em vez de polling sob alta concorrência: adicione "callback": {"url": "https://your.app/hook", "when": "final"} ao corpo da requisição da tarefa, trate o callback como um aviso e confirme o resultado com GET /v1/tasks/<taskId>.
• Guarde o taskId: se o polling falhar por erro de rede, faça polling novamente do mesmo id em vez de reenviar. Reenviar cria e cobra uma segunda tarefa.
• Fixe o seed para obter saídas comparáveis ao ajustar o prompt; trate isso como melhor esforço, não como garantia rígida.
• Valide antes de cobrar: erros de schema (HTTP 400, INVALID_REQUEST) são retornados na criação, quando nenhuma imagem foi gerada ainda.

Qual nível escolher

A mesma série também tem o Qwen Image 2.1 Pro, com preço por imagem mais alto que o Turbo na página de preços. Ambos são descritos como compatíveis com texto para imagem, edição e 0–10 imagens de referência; executamos apenas o Turbo, então não fazemos nenhuma afirmação sobre a qualidade relativa das imagens. A vantagem do Turbo está no preço menor e na velocidade de 8 passos; se a qualidade da saída for mais importante para o seu material, execute os dois com o mesmo prompt e seed e compare. Para a geração mais recente Qwen 3.0, consulte o Guia da API Qwen Image 3.0 e o Guia do Qwen Image 3.0 Pro.

Conteúdo relacionado

• Página do modelo Qwen Image 2.1 Turbo
• Preços
• Guia da API Qwen Image 3.0
• Documentação

Perguntas frequentes

Qual é o id do modelo? qwen-image-2.1-turbo, enviado via POST /v1/tasks.

É possível escolher a resolução de saída? Neste schema, não: não há campo resolution. Escolha um aspect_ratio entre os cinco valores permitidos.

Há suporte a edição? Sim: passe de 1 a 10 imagens de origem em image_urls junto com um prompt de instrução. Nos nossos testes, a edição de cor em áreas com textura funcionou apenas parcialmente.

Ele retorna PNG transparente? Nos nossos testes, não: o arquivo é do modo RGBA, mas o canal alfa é totalmente opaco e há um fundo desenhado. Verifique o alfa por conta própria e, se precisar de transparência real, adicione uma etapa de remoção de fundo.

Qual é o preço? Consulte a página de preços; no momento em que este texto foi escrito, é o mais barato dos dois níveis 2.1.