Skip to main content

Qwen-Image API reference

O Qwen-Image é um modelo de geração de imagens de uso geral que oferece suporte a diversos estilos artísticos e se destaca na renderização complexa de texto . Ele processa layouts com várias linhas, gera textos no nível de parágrafo e renderiza detalhes refinados.

Acesso rápido: Guia do usuário

Experimente online(Singapore

Beijing)**

** Blog técnico (mais exemplos)

Exemplos

Prompt

Imagem gerada

Um pôster desenhado à mão em estilo terapêutico, mostrando três filhotes brincando com uma bola sobre uma grama verde exuberante, adornado com elementos decorativos como pássaros e estrelas. O título principal “Venha Brincar de Bola!” aparece em destaque no topo, com uma fonte cartoon azul e em negrito. Abaixo dele, o subtítulo “Venha [Mostrar Suas Habilidades]!” surge em fonte verde. Um balão de fala adiciona um charme lúdico com o texto: “Hehe, veja só como vou impressionar meus amiguinhos agora!” Na parte inferior, um texto complementar diz: “Que bom jogar bola com nossos amigos de novo!” A paleta de cores gira em torno de verdes e azuis frescos, com toques de rosa e amarelo vibrantes para ressaltar uma atmosfera alegre e infantil.

image

Visão geral do modelo

ModeloDescriçãoEspecificações da imagem de saída
qwen-image-2.0-pro Recomendado
Mesmas capacidades do qwen-image-2.0-pro-2026-04-22
Série Qwen Pro para geração e edição de imagens. Oferece renderização de texto mais robusta, textura realista e maior aderência semântica.
Para edição de imagens, consulte Edição do Qwen-Image.
Resolução: Defina largura e altura livremente. O total de pixels deve ficar entre 512×512 e 2048×2048. A resolução padrão é 2048×2048.Formato: PNGNúmero de imagens: 1–6
qwen-image-2.0-pro-2026-06-22 Recomendado
qwen-image-2.0-pro-2026-04-22
qwen-image-2.0-pro-2026-03-03
qwen-image-2.0 Recomendado
Mesmas capacidades do qwen-image-2.0-2026-03-03
Série acelerada Qwen para geração e edição de imagens. Equilibra qualidade e velocidade de resposta.
Para edição de imagens, consulte Edição do Qwen-Image.
qwen-image-2.0-2026-03-03 Recomendado
Antes de chamar a API, verifique a lista de modelos suportados para sua região.

Pré-requisitos

Antes de fazer uma chamada, obtenha uma chave de API e exporte a chave de API como uma variável de ambiente. Para realizar chamadas com o SDK, instale o DashScope SDK.
As regiões China (Beijing) e Singapore possuem chaves de API e endpoints de solicitação separados. Não é possível usá-las de forma intercambiável. Chamadas entre regiões causam falhas de autenticação ou erros de service.

API síncrona

HTTP

Chamadas síncronas retornam os resultados em uma única requisição. Singapore: POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation China (Beijing): POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation Substitua {WorkspaceId} pelo seu ID do workspace real.

Parâmetros da requisição

  • Text-to-image
curl --location 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation' \
--header 'Content-Type: application/json' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--data '{
    "model": "qwen-image-2.0-pro",
    "input": {
      "messages": [
        {
          "role": "user",
          "content": [
            {
              "text": "Healing-style hand-drawn poster featuring three puppies playing with a ball on lush green grass, adorned with decorative elements such as birds and stars. The main title “Come Play Ball!” is prominently displayed at the top in bold, blue cartoon font. Below it, the subtitle “Come [Show Off Your Skills]!” appears in green font. A speech bubble adds playful charm with the text: “Hehe, watch me amaze my little friends next!” At the bottom, supplementary text reads: “We get to play ball with our friends again!” The color palette centers on fresh greens and blues, accented with bright pink and yellow tones to highlight a cheerful, childlike atmosphere."
            }
          ]
        }
      ]
    },
    "parameters": {
      "negative_prompt": "Low resolution, low quality, distorted limbs, malformed fingers, oversaturated colors, wax-figure appearance, lack of facial detail, excessive smoothness, AI-looking artifacts, chaotic composition, blurry or warped text.",
      "prompt_extend": true,
      "watermark": false,
      "size": "2048*2048"
    }
}'
Cabeçalhos da requisição
Content-Type string (Obrigatório)O tipo de conteúdo da requisição. Deve ser application/json.
Authorization string (Obrigatório)Autentica a requisição com uma chave de API do Model Studio. Exemplo: Bearer sk-xxxx.
Corpo da requisição
model string (obrigatório)Nome do modelo. Exemplo: qwen-image-2.0-pro.
input object (obrigatório)Informações de entrada.

Propriedades

messages array (obrigatório)Array de objetos de mensagem. Apenas conversas de turno único são suportadas, portanto o array deve conter exatamente um elemento.

Propriedades

rolestring (obrigatório)Função da mensagem. Defina como user.contentarray (obrigatório)Array de objetos de conteúdo da mensagem.

Propriedades

textstring(obrigatório)Um prompt positivo descrevendo o conteúdo, estilo e composição desejados para a imagem.Suporta chinês e inglês. A série qwen-image-2.0 aceita até 1.300 tokens. Outros modelos aceitam até 800 tokens. O sistema trunca os tokens excedentes.Nota: Apenas um campo de texto é permitido. Omiti-lo ou fornecer mais de um retorna um erro.
parameters object (opcional)Parâmetros de processamento de imagem.

Propriedades

negative_prompt string (opcional)Um prompt negativo descrevendo o que você não deseja na imagem.Suporta chinês e inglês. O comprimento máximo é de 500 caracteres. Caracteres excedentes são truncados automaticamente.Exemplo: Baixa resolução, baixa qualidade, membros distorcidos, dedos malformados, cores supersaturadas, aparência de cera, sem detalhes faciais, superfícies excessivamente lisas, aparência gerada por IA. Composição caótica. Texto borrado ou distorcido.size string (opcional)Resolução da imagem de saída, formatada como largura*altura.Modelos da série qwen-image-2.0: O total de pixels deve estar entre 512×512 e 2048×2048. A resolução padrão é 2048×2048. Resoluções recomendadas:
  • 2688*1536: 16:9
  • 1536*2688: 9:16
  • 2048*2048 (padrão): 1:1
  • 2368*1728: 4:3
  • 1728*2368: 3:4
prompt_extend bool (opcional)Ativa a reescrita inteligente de prompts. O modelo otimiza o prompt positivo. Não afeta o prompt negativo.
  • true: Padrão. Ativa a reescrita. Use esta opção para obter conteúdo de imagem mais diversificado; o modelo adiciona detalhes.
  • false: Desativa a reescrita. Use esta opção para ter controle mais preciso sobre os detalhes da imagem. Para melhores resultados, otimize seus prompts com base no Guia de prompts text-to-image.
Prompt original (orig_prompt): Um gato ruivo sentado com expressão alegre, parecendo vivaz, adorável e incrivelmente realista.Prompt real (actual_prompt): Retrato fotorrealista de vida selvagem: Um gato ruivo sentado com pelagem exuberante beijada pelo sol e uma expressão vibrante e alegre, olhos brilhando com curiosidade e calor. A cabeça do gato está levemente inclinada, orelhas erguidas para frente, boca gentilmente aberta em uma pose contente e vivaz — exalando charme adorável e detalhes incrivelmente realistas. A iluminação natural suave realça a textura de cada bigode e fio de pelo individual, com reflexos sutis no focinho e parte interna das orelhas. Fundo: um jardim de outono suavemente desfocado na hora dourada — tons quentes de folhas âmbar, luz solar filtrada através das árvores e leves indícios de degraus de pedra musgosos. A composição enfatiza o gato como ponto focal central, capturado em foco nítido com rasa profundidade de campo. Estilo: fotografia ultrarrealista, nível de detalhe National Geographic, resolução 8K, Canon EOS R5, abertura f/1.2, iluminação cinematográfica, color grading fiel à vida, pós-processamento mínimo. Sem texto ou sobreposições.
watermark bool (opcional)Adiciona uma marca d'água “Qwen-Image” no canto inferior direito da imagem. Padrão: false. Estilo da marca d'água: 1seed integer (opcional)Semente de número aleatório. Intervalo válido: [0,2147483647].Usar a mesma seed gera saídas semelhantes. Se omitida, o algoritmo usa uma semente aleatória.Nota: A geração de imagens é probabilística. Mesmo com a mesma seed, os resultados podem variar.

Parâmetros da resposta

  • Tarefa concluída com sucesso
  • Falha na tarefa
As URLs das imagens são válidas apenas por 24 horas e depois são removidas automaticamente. Salve as imagens geradas prontamente.
{
    "output": {
        "choices": [
            {
                "finish_reason": "stop",
                "message": {
                    "content": [
                        {
                            "image": "https://dashscope-result-sh.oss-cn-shanghai.aliyuncs.com/xxx.png?Expires=xxx"
                        }
                    ],
                    "role": "assistant"
                }
            }
        ]
    },
    "usage": {
        "height": 2048,
        "image_count": 1,
        "width": 2048
    },
    "request_id": "d0250a3d-b07f-49e1-bdc8-6793f4929xxx"
}
output objectInformações de saída da tarefa.

Propriedades

choices arraySaída do modelo. Este array contém exatamente um elemento.

Propriedades

finish_reason stringMotivo pelo qual a tarefa parou. O valor é stop para paradas naturais.message objectMensagem de resposta do modelo.

Propriedades

rolestringFunção da mensagem. Valor fixo: assistant.contentarray

Propriedades

image stringURL da imagem gerada (formato PNG). Expira após 24 horas. Baixe e salve-a prontamente.
task_metric objectEstatísticas do resultado da tarefa. Não retornado para modelos da série qwen-image-2.0.

Propriedades

TOTAL integerNúmero total de tarefas.SUCCEEDED integerNúmero de tarefas bem-sucedidas.FAILED integerNúmero de tarefas com falha.
usage object
Chamadas síncronas do SDK ImageSynthesis não retornam este campo.
Estatísticas de saída. Conta apenas resultados bem-sucedidos.

Propriedades

image_count integerNúmero de imagens geradas. Para modelos da série qwen-image-2.0, isso equivale ao n solicitado (1–6).width integerLargura da imagem gerada, em pixels.height integerAltura da imagem gerada, em pixels.
request_id stringIdentificador único da requisição para rastreamento e solução de problemas.
code stringCódigo de erro. Retornado apenas para requisições com falha. Consulte Códigos de erro.
message stringMensagem de erro detalhada. Retornada apenas para requisições com falha. Consulte Códigos de erro.

Chamada via DashScope SDK

O DashScope SDK suporta Python e Java. Os nomes dos parâmetros no SDK correspondem closely aos parâmetros HTTP, e as estruturas dos parâmetros seguem convenções específicas da linguagem. Para parâmetros de chamada síncrona, consulte HTTP.
  • Python
  • Java
Instale a versão mais recente do DashScope Python SDK para evitar erros de execução: Instalar SDK.
Exemplo de requisição
import json
import os
import dashscope
from dashscope import MultiModalConversation

# Singapore region. Replace {WorkspaceId} with your actual workspace ID. URLs vary by region.
dashscope.base_http_api_url = 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1'

messages = [
    {
        "role": "user",
        "content": [
            {"text": "Healing-style hand-drawn poster featuring three puppies playing with a ball on lush green grass, adorned with decorative elements such as birds and stars. The main title “Come Play Ball!” is prominently displayed at the top in bold, blue cartoon font. Below it, the subtitle “Come [Show Off Your Skills]!” appears in green font. A speech bubble adds playful charm with the text: “Hehe, watch me amaze my little friends next!” At the bottom, supplementary text reads: “We get to play ball with our friends again!” The color palette centers on fresh greens and blues, accented with bright pink and yellow tones to highlight a cheerful, childlike atmosphere."}
        ]
    }
]

# API keys differ between Beijing and Singapore regions. Get your API key: https://www.alibabacloud.com/help/en/model-studio/get-api-key
# If you haven't set the environment variable, replace the line below with: api_key="sk-xxx"
api_key = os.getenv("DASHSCOPE_API_KEY")

response = MultiModalConversation.call(
    api_key=api_key,
    model="qwen-image-2.0-pro",
    messages=messages,
    result_format='message',
    stream=False,
    watermark=False,
    prompt_extend=True,
    negative_prompt="Low resolution, low quality, distorted limbs, malformed fingers, oversaturated colors, wax-figure appearance, lack of facial detail, excessive smoothness, AI-looking artifacts, chaotic composition, blurry or warped text.",
    size='2048*2048'
)

if response.status_code == 200:
    print(json.dumps(response, ensure_ascii=False))
else:
    print(f"HTTP status code: {response.status_code}")
    print(f"Error code: {response.code}")
    print(f"Error message: {response.message}")
    print("See documentation: https://www.alibabacloud.com/help/en/model-studio/error-code")
Exemplo de resposta
As URLs das imagens expiram após 24 horas. Baixe as imagens prontamente.
{
    "status_code": 200,
    "request_id": "d2d1a8c0-325f-9b9d-8b90-xxxxxx",
    "code": "",
    "message": "",
    "output": {
        "text": null,
        "finish_reason": null,
        "choices": [
            {
                "finish_reason": "stop",
                "message": {
                    "role": "assistant",
                    "content": [
                        {
                            "image": "https://dashscope-result-wlcb.oss-cn-wulanchabu.aliyuncs.com/xxx.png?Expires=xxx"
                        }
                    ]
                }
            }
        ]
    }
}

Uso com o OpenAI Agents SDK

Modelos de geração de imagens como o Qwen-Image são chamados por meio da API nativa do DashScope e não suportam o modo compatível com OpenAI (compatible-mode). Portanto, não é possível usá-los diretamente como modelo de raciocínio de um Agent no OpenAI Agents SDK. Em frameworks de agentes como o OpenAI Agents SDK, você pode encapsular a geração de imagens como uma ferramenta (function tool) e utilizar um modelo de chat de texto compatível com o modo OpenAI (como o qwen-plus) como núcleo de raciocínio do Agent para orquestrá-la. Por exemplo: Antes de executar, instale as dependências: pip install openai-agents dashscope.
import os
import asyncio
import dashscope
from openai import AsyncOpenAI
from dashscope import MultiModalConversation
from agents import Agent, Runner, function_tool, OpenAIChatCompletionsModel

# Read the Model Studio API Key from an environment variable
# (or replace with api_key="sk-xxx")
API_KEY = os.getenv("DASHSCOPE_API_KEY")

# Singapore region. Replace {WorkspaceId} with your actual workspace ID. URLs vary by region.
dashscope.base_http_api_url = "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1"
# The text chat model (the Agent's reasoning core) is accessed via OpenAI-compatible mode
client = AsyncOpenAI(api_key=API_KEY, base_url="https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1")

# Wrap image generation as a function tool for the Agent to call
@function_tool
def generate_image(prompt: str) -> str:
    """Generate an image from a text description and return its URL. prompt: the text description of the image."""
    rsp = MultiModalConversation.call(
        api_key=API_KEY,
        model="qwen-image-2.0-pro",
        messages=[{"role": "user", "content": [{"text": prompt}]}],
        result_format="message",
    )
    if rsp.status_code != 200:
        return f"Generation failed: {rsp.code} {rsp.message}"
    return rsp.output.choices[0].message.content[0]["image"]

agent = Agent(
    name="Image Assistant",
    instructions="You are an image generation assistant. When the user wants an image, call the generate_image tool and return the image URL to the user.",
    model=OpenAIChatCompletionsModel(model="qwen-plus", openai_client=client),
    tools=[generate_image],
)

async def main():
    result = await Runner.run(agent, "Draw a corgi running on the grass")
    print(result.final_output)

if __name__ == "__main__":
    asyncio.run(main())

Faturamento e limitação de taxa

  • Para cotas gratuitas e preços, consulte Preços dos modelos.
  • Para limites de taxa, consulte Qwen-Image.
  • Detalhes do faturamento: Cada imagem gerada com sucesso é cobrada. Chamadas com falha ou erros de processamento não geram cobranças nem consomem sua cota gratuita para novos usuários.

Códigos de erro

Se a chamada do modelo falhar e retornar uma mensagem de erro, consulte Códigos de erro para resolução.

Perguntas frequentes

P: Devo ativar ou desativar o parâmetro prompt_extend?

R: Ative esta opção (padrão) se desejar um conteúdo de imagem mais diversificado e permitir que o modelo adicione detalhes. Desative-a caso precise de controle mais rigoroso sobre os detalhes da imagem e otimize seus prompts usando o Guia de prompts de texto para imagem.

P: Quais são as diferenças entre os modelos da série qwen-image-2.0?

R:
  • Modelos combinados de geração e edição de imagens: Suportam tanto texto para imagem quanto edição de imagens.
    • qwen-image-2.0-pro e qwen-image-2.0-pro-2026-03-03: Mesmas capacidades. A série Pro oferece renderização de texto mais profissional, texturas realistas mais refinadas, cenas realistas detalhadas e maior aderência semântica. Suporta apenas chamadas síncronas.
    • qwen-image-2.0 e qwen-image-2.0-2026-03-03: Mesmas capacidades. A versão acelerada equilibra desempenho e qualidade do modelo. Suporta apenas chamadas síncronas.

P: Como obtenho a lista de permissões de nomes de domínio para armazenamento de imagens?

R: As imagens geradas pelos modelos são armazenadas no OSS. A API retorna uma URL pública temporária. Para configurar uma lista de permissões de firewall para essa URL de download, observe o seguinte: O armazenamento subjacente pode mudar dinamicamente. Este tópico não fornece uma lista fixa de nomes de domínio do OSS para evitar problemas de acesso causados por informações desatualizadas. Se você tiver requisitos de controle de segurança, entre em contato com seu gerente de conta para obter a lista mais recente de nomes de domínio do OSS.