Tutorial
Como usar o qwen-image-2.0-pro pela API HiAPI: curl, Python e uma requisição funcional
Um exercício prático de integração para desenvolvedores: primeira chamada bem-sucedida, análise da estrutura da requisição e diagnóstico de falhas
Nesta página
O que o qwen-image-2.0-pro oferece aos usuários da API
qwen-image-2.0-pro é um modelo de geração de imagens chamado via HTTP. Do ponto de vista do seu código, ele se comporta como um endpoint de chat completions: você envia um payload JSON descrevendo a imagem desejada e recebe uma resposta JSON contendo a imagem gerada.
A vantagem de acessá-lo pela API HiAPI está na consistência. Uma chave de API, uma URL base e uma estrutura de requisição servem para vários modelos. Se depois você trocar o identificador do modelo ou ajustar parâmetros, o código ao redor permanece inalterado. Você não precisa aprender um novo SDK nem gerenciar vários conjuntos de credenciais para cada modelo de imagem que experimentar.
Este tutorial primeiro faz uma chamada inicial completa com curl, depois a porta para Python, mostra como ler a imagem a partir da resposta e, por fim, apresenta uma lista de verificação para diagnóstico e um pequeno wrapper reutilizável. Todos os exemplos usam o mesmo payload e a mesma variável de ambiente da chave, de modo que o que funciona no terminal roda sem alterações no script.
Pré-requisitos e preparação da chave
Antes de escrever qualquer código, certifique-se de que estas três coisas estão prontas.
1. Conta HiAPI e chave de API
Crie uma conta e gere uma chave de API no painel. A chave é confidencial; trate-a como uma senha. Não a cole em arquivos de código-fonte que serão enviados ao controle de versão.
2. Exporte a chave como variável de ambiente
Os exemplos a seguir leem a chave de HIAPI_API_KEY, então os mesmos comandos e scripts funcionam localmente e em CI sem modificações.
export HIAPI_API_KEY="your_key_here"
No Windows PowerShell, use $env:HIAPI_API_KEY = "your_key_here". Em CI, defina-a como variável de ambiente secreta na configuração do pipeline.
3. Ferramenta para fazer requisições HTTP
O curl normalmente já vem instalado. Para Python, você precisa do Python 3 e da biblioteca requests:
pip install requests
Antes de continuar, confirme que o shell consegue ver a chave:
# macOS / Linux
echo "${HIAPI_API_KEY:0:4}..."
Se não houver saída, a variável não está definida e todas as requisições falharão com erro de autenticação. Resolva isso primeiro.
Requisição mínima funcional com curl
A forma mais rápida de confirmar a conectividade é fazer uma chamada curl lendo a chave da variável de ambiente. O payload é um objeto JSON contendo o campo model e um array messages no estilo chat completions.
curl -sS https://api.hiapi.ai/v1/chat/completions \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "qwen-image-2.0-pro",
"messages": [
{
"role": "user",
"content": "A small ceramic mug on a wooden table, soft morning light, product photo"
}
]
}'
Três detalhes são importantes aqui. O cabeçalho Authorization usa o esquema Bearer. O valor de model deve corresponder exatamente ao identificador do modelo. content é uma string simples com o prompt que descreve a imagem.
Se a requisição for bem-sucedida, você verá a resposta JSON impressa no terminal. Se falhar, verá o código de status HTTP e a mensagem de erro. Verifique o código de status antes de ler o corpo da resposta: 401 indica chave incorreta ou ausente, 400 geralmente indica payload malformado, e 404 ou erro de modelo não encontrado indica identificador de modelo incorreto.
Assim que este comando retornar uma resposta de sucesso, a conectividade está confirmada e você pode seguir para o código.
A mesma requisição em Python
Ao portar a chamada para Python, mantenha o payload exatamente igual. A única diferença está na forma de ler a variável de ambiente e serializar a requisição.
import json
import os
import requests
api_key = os.environ["HIAPI_API_KEY"]
payload = {
"model": "qwen-image-2.0-pro",
"messages": [
{
"role": "user",
"content": "A small ceramic mug on a wooden table, soft morning light, product photo",
}
],
}
response = requests.post(
"https://api.hiapi.ai/v1/chat/completions",
headers={
"Authorization": f"Bearer {api_key}",
"Content-Type": "application/json",
},
json=payload,
timeout=120,
)
response.raise_for_status()
data = response.json()
print(json.dumps(data, indent=2))
Observe que json=payload faz o requests definir automaticamente o cabeçalho Content-Type e serializar o corpo da requisição. O timeout é importante, pois a geração de imagens pode levar mais tempo do que um chat completion típico; 120 segundos é um ponto de partida razoável. raise_for_status() converte códigos de status de erro em exceções, então uma falha não passa silenciosamente.
Execute este script e você deverá obter o mesmo JSON que viu no curl. Se não, seu ambiente difere do shell onde o curl funcionou; o mais comum é a variável da chave.
Ler a resposta e processar a saída da imagem
A resposta segue a estrutura de chat completions, então a imagem gerada é obtida pelo mesmo caminho que você usaria para uma resposta de texto. Primeiro inspecione o JSON impresso; a estrutura será familiar:
{
"choices": [
{
"message": {
"role": "assistant",
"content": "..."
}
}
]
}
A imagem gerada aparece no conteúdo da mensagem do assistente, normalmente como uma URL ou um payload codificado em base64, dependendo de como o modelo retorna a mídia. Não presuma qual dos dois; leia o valor e ramifique pelo prefixo:
content = data["choices"][0]["message"]["content"]
if isinstance(content, str) and content.startswith("http"):
image_url = content
# Download and save if you want a local copy
image_bytes = requests.get(image_url, timeout=60).content
with open("output.png", "wb") as f:
f.write(image_bytes)
print("saved output.png from URL")
else:
# Treat as base64-encoded image data
import base64
image_bytes = base64.b64decode(content)
with open("output.png", "wb") as f:
f.write(image_bytes)
print("saved output.png from base64")
Duas observações práticas. Se o conteúdo for uma URL, trate-a como um link temporário e baixe-a o quanto antes, em vez de vinculá-la diretamente no produto. Se for base64, isole a decodificação para que payloads malformados gerem um erro capturável. Antes de analisar, sempre grave a resposta bruta em um arquivo de log, assim você pode depurar sem repetir uma requisição possivelmente lenta.
Lista de verificação para requisições com falha
Quando uma requisição falhar, não se apresse em reescrever a chamada inteira. Faça as verificações a seguir em ordem e pare na primeira que falhar. Cada verificação isola uma variável.
1. Autenticação
Verifique primeiro o código de status. 401 indica chave ausente, expirada ou malformada. Confirme que a variável de ambiente está definida no shell atual, que você usou o prefixo Bearer e que o cabeçalho não tem espaços no final.
2. Identificador do modelo
Um erro de modelo não encontrado indica que o valor de model não corresponde exatamente a um modelo disponível. Maiúsculas/minúsculas e sufixos importam. Compare seu valor caractere por caractere com a página de documentação do modelo.
3. Estrutura do payload
400 normalmente vem de um corpo de requisição malformado. Confirme que messages é um array, que cada mensagem contém role e content, e que o JSON é válido. Processar o payload com jq ou python -m json.tool antes de enviar pode capturar erros de sintaxe.
4. Tratamento da resposta
Se a requisição for bem-sucedida mas o script travar, o problema está no código de análise, não na API. Registre o corpo bruto da resposta antes de fatiá-lo e confirme que o caminho que você lê realmente existe. A imagem pode vir como URL em uma chamada e como base64 em outra, então ramifique pelo conteúdo em vez de presumir.
5. Timeouts e novas tentativas
A geração de imagens pode ser lenta. Se ocorrer timeout, aumente o tempo limite do cliente e tente novamente uma vez. Evite repetir erros 4xx, pois eles falharão da mesma forma novamente.
Um hábito útil: guarde uma cópia de uma requisição comprovadamente boa e compare a requisição com falha com ela. A maioria das falhas difere em apenas um campo.
Encapsular em um cliente reutilizável
Depois que a chamada funcionar, encapsule-a em uma pequena função para que mudanças de modelo e parâmetros fiquem concentradas em um só lugar. Este wrapper centraliza a busca da chave, os cabeçalhos e o tratamento de erros:
import base64
import os
import requests
HIAPI_BASE = "https://api.hiapi.ai/v1"
DEFAULT_MODEL = "qwen-image-2.0-pro"
def generate_image(prompt: str, model: str = DEFAULT_MODEL) -> bytes:
"""Generate an image and return its raw bytes."""
api_key = os.environ["HIAPI_API_KEY"]
payload = {
"model": model,
"messages": [{"role": "user", "content": prompt}],
}
response = requests.post(
f"{HIAPI_BASE}/chat/completions",
headers={"Authorization": f"Bearer {api_key}"},
json=payload,
timeout=120,
)
response.raise_for_status()
content = response.json()["choices"][0]["message"]["content"]
if isinstance(content, str) and content.startswith("http"):
return requests.get(content, timeout=60).content
return base64.b64decode(content)
O código de chamada vira uma linha: open("out.png", "wb").write(generate_image("A ceramic mug on a wooden table")). Se depois você trocar para outro modelo de imagem ou adicionar parâmetros, basta alterar esta função. O identificador do modelo e quaisquer detalhes de parâmetros ficam na página do modelo; você pode consultar os detalhes do modelo qwen-image-2.0-pro antes de integrar.
Comece com a chamada curl, depois o script Python e por fim o encapsulamento. Cada etapa confirma uma parte menor antes de você construir a próxima camada.
Artigos relacionados
Ver todos os artigos →-
Tutorial
kling-image-4.0 cenários de aplicação na prática: 5 usos de alto valor e pontos de integração
-
Tutorial
Como chamar o gemini-omni-1.1-flash pela API HiAPI: guia com curl e Python
-
Tutorial
Como chamar a API de texto para vídeo veo-3.1: exemplos em curl e Python
Guia prático de integração para desenvolvedores