Como usar a API Qwen Image 3.0: geração, edição e preços

TL;DR

Qwen Image 3.0 unifica a geração de imagens a partir de texto e a edição guiada por referência nas variantes Standard (qwen-image-3.0) e Pro (qwen-image-3.0-pro). Comece com um prompt de texto, escolha um tamanho de saída, envie uma solicitação de geração de imagem e salve rapidamente o resultado. Para edição, inclua de uma a três imagens de referência e uma instrução explícita de preservação. No CometAPI, verifique a rota real e o esquema de solicitação compatível antes de implantar as chamadas de exemplo.

Key Takeaways

• A API do Qwen Image 3.0 oferece geração de imagens a partir de texto e edição guiada por referência nas variantes Standard (qwen-image-3.0) e Pro (qwen-image-3.0-pro); a saída nativa é PNG.
• O acesso à API do Qwen Image 3.0 está disponível por meio do CometAPI. Os desenvolvedores podem obter uma chave de API, verificar o endpoint suportado e integrar a geração de imagens em seus aplicativos.
• A precificação da API do Qwen Image 3.0 começa em $0,024/solicitação no CometAPI, em comparação com as tarifas da Alibaba Cloud em Cingapura a partir de $0,030 por imagem de saída Standard e $0,040 por imagem de saída Pro 1K.
• A edição de imagem no Qwen Image 3.0 suporta até três imagens de referência pela API nativa da Alibaba Cloud, enquanto a geração suporta de uma a seis saídas por solicitação.
• A integração da API do Qwen Image 3.0 exige que os desenvolvedores verifiquem parâmetros específicos do provedor, autenticação, unidades de cobrança e URLs temporárias de imagem antes de implantar fluxos de trabalho em produção.

What Is the Qwen Image 3.0 API?

A API do Qwen Image 3.0 transforma instruções de texto em imagens e pode transformar fotografias fornecidas ou recursos de design. Cenários suportados incluem pôsteres multilíngues, fotografia de e-commerce, mockups de campanhas, substituição de fundo e edição de imagens compostas.

Qwen Image 3.0 Standard (qwen-image-3.0) é a base com foco em custo para geração de imagens a partir de texto e edição guiada por referência. Considere-o primeiro para fluxos de trabalho de alto volume, como variações de fundo para e-commerce, rascunhos visuais para redes sociais e exploração de conceitos de campanha. Por exemplo, use o Standard para produzir várias opções de fundo de produto, depois revise a fidelidade do produto e selecione as versões que valem a pena refinar.

Qwen Image 3.0 Pro (qwen-image-3.0-pro) oferece geração e edição guiada por referência, com um nível nativo de saída 2K de preço mais alto. Avalie-o para entregáveis sensíveis à qualidade, como imagens principais de campanha, composições detalhadas de produtos e pôsteres promocionais. Por exemplo, teste um conceito pré-selecionado com o Pro quando detalhes finos ou layout forem importantes e compare os resultados aceitos com o Standard antes de comprometer um orçamento maior.

Como escolher: Comece com o Standard para rascunhos e variações sensíveis a custo. Teste o Pro com o mesmo briefing para ativos finais exigentes; selecione-o quando a melhoria medida justificar o custo adicional. Nenhuma das designações substitui testes específicos de aplicação para tipografia, fidelidade do produto, contagem de objetos ou precisão do layout.

What Parameters Does Qwen Image 3.0 API Support?

Use estes parâmetros com a interface nativa compatível com OpenAI da Alibaba Cloud. Adicione opções específicas do provedor às solicitações do CometAPI apenas quando a rota selecionada as documentar.

Aplica-se a ambas as variantes: qwen-image-3.0 (Standard) e qwen-image-3.0-pro (Pro) suportam os mesmos parâmetros listados abaixo na interface nativa compatível da Alibaba Cloud. Selecione a variante com model; os controles de geração e edição são compartilhados. Isso não implica qualidade de saída ou preços idênticos, nem garante que toda rota do CometAPI exponha todos os parâmetros nativos.

Para solicitações nativas, a proporção da saída deve permanecer entre 1:8 e 8:1. As imagens de referência devem ter no máximo 10 MB, com cada lado entre 1 e 8.000 pixels e uma razão entre o lado mais longo e o mais curto não superior a 10:1. Use um data URI para entrada Base64. Thinking requer prompt_extend=true; agent enhancement suporta apenas text-to-image.

Uma solicitação de imagem compatível posiciona os campos de geração no nível superior do JSON e formata as dimensões como 1024x1024. O DashScope nativo usa input/parameters aninhados e normalmente escreve as dimensões como 1024*1024. Uma solicitação copiada entre esses endpoints sem conversão pode falhar.

How Do You Call Qwen Image 3.0 API with CometAPI?

Este passo a passo pressupõe Python 3, um terminal compatível com Bash, uma conta CometAPI com acesso ao modelo e saldo suficiente. A primeira solicitação usa apenas os campos model e prompt mostrados no exemplo do provedor. Documentação verificada em 16 de outubro de 2026; estes exemplos não foram executados em uma conta paga.

Create credentials

Crie uma chave de API no lado do servidor no seu painel do CometAPI. Nunca a inclua em um cliente web ou mobile.

export COMETAPI_KEY="your_api_key"python -m pip install requests

Submit a minimal generation request

Os desenvolvedores podem acessar a API do Qwen Image 3.0 no CometAPI usando a rota documentada de geração de imagens. Comece com a solicitação mínima abaixo antes de introduzir parâmetros opcionais.

curl --fail-with-body https://api.cometapi.com/v1/images/generations \  -H "Authorization: Bearer $COMETAPI_KEY" \  -H "Content-Type: application/json" \  -d '{"model":"qwen-image-3.0","prompt":"Premium skincare bottle on a stone pedestal, gentle studio lighting"}'

Save every returned image

Salve o script a seguir como generate.py e execute python generate.py. Ele envia uma solicitação, manipula resultados em URL ou Base64 e grava cada imagem localmente. Se a resposta contiver informações de tarefa em vez de um array data, ele para em vez de adivinhar um endpoint de polling; use o contrato assíncrono específico da conta para recuperar o resultado concluído.

import base64import osfrom pathlib import Pathimport requests​response = requests.post(    "https://api.cometapi.com/v1/images/generations",    headers={"Authorization": f"Bearer {os.environ['COMETAPI_KEY']}"},    json={"model": "qwen-image-3.0", "prompt": "A sunny bookstore cafe, editorial photograph"},    timeout=(15, 600),)response.raise_for_status()result = response.json()images = result.get("data")if not isinstance(images, list) or not images:    raise RuntimeError(f"No synchronous images; inspect task/error fields: {list(result)}")for index, item in enumerate(images, 1):    if item.get("url"):        download = requests.get(item["url"], timeout=(15, 120))        download.raise_for_status()        content = download.content    elif item.get("b64_json"):        content = base64.b64decode(item["b64_json"], validate=True)    else:        raise RuntimeError(f"Image {index} has no URL or Base64 payload")    path = Path(f"qwen_image_{index}.png")    path.write_bytes(content)    print(f"Saved {path}")

Uma execução bem-sucedida produz arquivos de imagem locais. Abra-os para confirmar que são legíveis e correspondem à cena solicitada. Preserve o identificador da solicitação e os campos de uso nos logs do seu servidor sem registrar credenciais.

How Do You Generate Multiple Images with Qwen Image 3.0?

Na interface nativa da Alibaba Cloud, defina n como dois a seis para variações criativas. Para o CometAPI, ative n somente após confirmar o suporte na rota selecionada. Valide cada ativo retornado separadamente; um n maior não garante que todos os resultados passarão na revisão downstream.

Você pode gerar até 6 imagens em uma única solicitação com o Qwen Image 3.0 definindo o parâmetro n. Isso funciona com qwen-image-3.0 e qwen-image-3.0-pro, tanto para geração a partir de texto quanto para edição de imagem. O padrão é apenas uma imagem.

Há duas maneiras principais de fazer isso: use uma interface gráfica se a sua plataforma expuser a opção ou chame a API diretamente.

Generate multiple images using the API

1. Abra a documentação da API.
2. Obtenha uma chave de API no console do QwenCloud/ CometAPI.
3. Selecione qwen-image-3.0 ou qwen-image-3.0-pro.
4. Defina n para o número de imagens desejadas, de 1 a 6.
5. Envie seu prompt e salve as imagens retornadas.

Por exemplo, defina "n": 4 para solicitar quatro variações do mesmo prompt.

Python example

Aqui está um exemplo pronto para adaptação usando a API compatível com OpenAI.

from openai import OpenAIimport requestsclient = OpenAI(    api_key="YOUR_QWEN_API_KEY",    base_url="https://maas.qwencloudapi.com/compatible-mode/v1")
result = client.images.generate(    model="qwen-image-3.0-pro",    
prompt=(        "A cozy Japanese cafe on a rainy evening, "        "warm glowing lights, cinematic photography, "        "rich details, realistic reflections"    ),    
n=4,    
size="1024x1024")# Save each generated image
for i, item in enumerate(result.data, start=1):    response = requests.get(item.url)    response.raise_for_status()    with open(f"qwen_image_{i}.png", "wb") 
as f:        
f.write(response.content)print("Finished generating images!")

Instale primeiro os pacotes necessários:

pip install openai requests

A API retorna um URL de imagem para cada resultado. Os URLs de imagens geradas são temporários, portanto, faça o download das imagens prontamente.

Important settings

O número máximo de saídas é seis por solicitação. Tenha em mente que solicitar mais imagens aumenta o custo de geração.

Uma distinção importante: n=4 solicita quatro variações de um único prompt. Se você quiser quatro prompts diferentes, faça solicitações separadas ou automatize um loop sobre seus prompts.

How Do You Edit Images with Qwen Image 3.0?

Uma edição combina de uma a três imagens de referência com instruções. Explique tanto a transformação desejada quanto o que não deve mudar — por exemplo, o rótulo do produto, a cor, o ângulo da câmera ou a geometria da embalagem.

O próximo exemplo usa credenciais da Alibaba Cloud e seu campo JSON de imagem para edição. Crie uma chave regional do Model Studio, obtenha o ID do seu workspace e configure o endpoint correspondente. Não substitua uma chave do CometAPI nesta solicitação.

export DASHSCOPE_API_KEY="your_model_studio_key"export ALIBABA_WORKSPACE_ID="your_workspace_id"export ALIBABA_IMAGE_ENDPOINT="https://${ALIBABA_WORKSPACE_ID}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1/images/generations"

A imagem de referência abaixo vem diretamente do exemplo oficial da API. É uma imagem de entrada, não um resultado gerado deste artigo.

import os, requests
endpoint = os.environ["ALIBABA_IMAGE_ENDPOINT"]  
# documented regional .../images/generations endpoint
payload = {
"model": "qwen-image-3.0", 
"prompt": "Change the outfit to a charcoal business suit in a cafe. Preserve the face and hairstyle.", 
"image": ["https://alidocs.oss-cn-zhangjiakou.aliyuncs.com/res/yBRq1ZPYEaXdyOdv/img/33a80a19-7ac7-4c64-b0fa-7d685b7046a0.png"], 
"size": "1024x1024", 
"n": 1}
r = requests.post(endpoint, headers={
"Authorization": f"Bearer {os.environ['DASHSCOPE_API_KEY']}"}, json=payload, timeout=(15, 600))
r.raise_for_status()
print(r.json())

O endpoint nativo compatível usa JSON em /images/generations, não uploads multipart em /images/edits. Ele não suporta máscaras nem streaming. Leia o array data retornado e salve cada URL usando o mesmo loop de download mostrado acima.

Para duas referências, inclua dois URLs no array image e especifique seus papéis no prompt (por exemplo, produto da imagem um, ambiente da imagem dois). A série Qwen Image 3.0 aceita no máximo três imagens de referência; use um modelo diferente ou um fluxo de pré-processamento para conjuntos maiores de fontes.

How Much Does Qwen Image 3.0 API Cost?

Os preços da API do Qwen Image 3.0 variam por variante do modelo, resolução de saída e provedor. A tabela abaixo complementa a comparação original da Alibaba Cloud em Cingapura com as tarifas do CometAPI exibidas na tabela de preços anexada pelo revisor. O anexo lista preços de saída em USD por imagem e um desconto de 20% para as quatro combinações de modelo/resolução. Essas tarifas fornecidas não foram revalidadas de forma independente contra a cobrança de uma conta ativa; confirme a tabela de tarifas aplicável antes do uso em produção.

*Os exemplos de volume acima cobrem apenas imagens de saída: 100 imagens Standard 1K custam $2,40 e 100 imagens Pro 1K custam $3,20; 1.000 imagens Standard 2K custam $24,00 e 1.000 imagens Pro 2K custam $60,00. Para edição, adicione $0,0024 por imagem de referência de entrada faturável. Regras para jobs com falha, impostos e ajustes específicos de conta estão excluídos.

Usando as tarifas fornecidas para imagens de entrada e saída, estime os encargos de imagem para qualquer provedor da seguinte forma:

Custo total = (imagens de referência faturáveis × preço por imagem de entrada) + (saídas bem-sucedidas × preço por imagem de saída).

Para um job faturado por duas imagens de referência de entrada e três saídas Standard 1K bem-sucedidas, os encargos de imagem da Alibaba Cloud são (2 × $0,0030) + (3 × $0,0300) = $0,0960. Os encargos de imagem correspondentes no CometAPI são (2 × $0,0024) + (3 × $0,0240) = $0,0768, com base nas tarifas fornecidas.

O CometAPI cobra $0,0024 por imagem de referência de entrada para ambas as variantes. Os preços de saída são $0,0240 por imagem Standard em 1K ou 2K, $0,0320 por imagem Pro em 1K e $0,0600 por imagem Pro em 2K. A tabela fornecida lista cada tarifa de entrada e saída com 20% abaixo da tarifa oficial correspondente. Para as mesmas contagens de imagens faturáveis, esses encargos de imagem são, portanto, 20% menores; taxas adicionais ou termos de conta podem alterar a fatura final.

Para orçamento de produção, verifique a variante selecionada, a resolução de imagem, os encargos por imagem de referência, o número de saídas por solicitação e os descontos aplicáveis da conta antes de estimar os custos totais de uso.

How Do You Handle Qwen Image 3.0 API Errors?

FAQ

Should I retry a Qwen Image 3.0 request after a timeout?

Um timeout no cliente não prova que a geração parou. Preserve qualquer identificador de solicitação ou tarefa, verifique o histórico de jobs do provedor ou a API de status documentada e determine se a saída já existe antes de reenviar. Repetições às cegas podem criar jobs duplicados e cobranças adicionais. Use tentativas limitadas para falhas transitórias e siga a orientação de idempotência do provedor quando disponível.

How can I use local reference images with Qwen Image 3.0?

Para a interface nativa compatível, leia o arquivo como bytes, codifique em Base64 e prefixe com um data URI como data:image/png;base64,. Coloque essa string completa em image. A entrada Base64 ainda deve atender aos limites de tamanho e dimensões da imagem; um caminho de sistema de arquivos local não é um URL que o serviço possa buscar.

How do I pass Qwen-specific options through an OpenAI SDK?

Mantenha os campos de imagem padrão em seus argumentos usuais do SDK e coloque os campos de extensão do Model Studio, como image e prompt_extend, dentro de extra_body. Solicitações HTTP brutas colocam esses campos diretamente no nível superior do JSON. Esta orientação se aplica à interface nativa compatível; verifique a rota selecionada do CometAPI antes de encaminhar opções específicas do provedor.

What should I do when Qwen Image 3.0 returns fewer images than requested?

Salve primeiro as saídas bem-sucedidas e registre a contagem real. Para a cobrança nativa da Alibaba Cloud, as cobranças de saída seguem as imagens geradas com sucesso. Se ativos adicionais forem necessários, solicite apenas a quantidade faltante após verificar a resposta e o registro de uso; a cobrança do CometAPI deve ser reconciliada com seus próprios termos de conta.

Conclusion

Qwen Image 3.0 é uma escolha prática para equipes que precisam de geração e edições orientadas por referência dentro de uma mesma família de modelos. Use o Standard como base orientada a custo, teste o Pro para tarefas 2K ou criativas mais exigentes e meça o custo por saída aceita em vez de julgar apenas pelo preço por solicitação. Comece com a chamada mínima de geração, persista as saídas e, em seguida, adicione edição ou múltiplas saídas pelo contrato apropriado do provedor. Mantenha credenciais e esquemas de solicitação separados, trate erros explicitamente e reconcilie o uso de imagens com a tabela de tarifas selecionada.