Utilize a Responses API compatível com OpenAI para chamar o modelo Qwen. Este tópico descreve os parâmetros de entrada e saída e fornece um exemplo de chamada.
Vantagens em relação à OpenAI Chat Completions API:- Ferramentas integradas: Obtenha melhores resultados em tarefas complexas com ferramentas nativas como busca na web, scraping da web, interpretador de código, texto para imagem, imagem para imagem e busca em base de conhecimento. Para mais informações, consulte tool calling.
- Entrada mais flexível: Aceita tanto strings diretas quanto arrays de mensagens no formato de chat.
- Gerenciamento simplificado de contexto: Evite construir manualmente um array de histórico de mensagens passando o
previous_response_idda última resposta. - Cache de contexto prático: Adicione
x-dashscope-session-cache: enable(valor padrão: disable) ao cabeçalho da requisição para ativar o cache automático do contexto de conversa no lado do servidor. Isso reduz a latência de inferência e os custos em conversas de múltiplas rodadas sem exigir alterações no código. Para detalhes, consulte session cache.
Compatibilidade e limitações
Esta API é compatível com a OpenAI para reduzir o custo de migração dos desenvolvedores, mas difere em seus parâmetros, funcionalidades e comportamento.
Princípio fundamental: Apenas os parâmetros listados explicitamente neste documento são processados. Quaisquer parâmetros da OpenAI não mencionados serão ignorados.
As principais diferenças abaixo ajudarão você a se adaptar rapidamente:
- Parâmetros não suportados: Esta API não aceita alguns parâmetros da API OpenAI, como o parâmetro de execução assíncrona
background. Atualmente, apenas chamadas síncronas são suportadas. - Controle do esforço de raciocínio: Utilize o parâmetro
reasoning.effortpara controlar o nível de raciocínio do modelo. Para detalhes de uso, consulte a descrição deste parâmetro.
Singapore
Para configurar a chamada do SDK, defina o base_url como https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1.
Endpoint da requisição HTTP: POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1/responses
China (Beijing)
Na configuração de chamada do SDK, utilize o base_url: https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1
Endpoint da requisição HTTP: POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1/responses
US (Virginia)
O base_url para configuração da chamada do SDK é: https://{WorkspaceId}.us-east-1.maas.aliyuncs.com/compatible-mode/v1
Endpoint da requisição HTTP: POST https://{WorkspaceId}.us-east-1.maas.aliyuncs.com/compatible-mode/v1/responses
Germany (Frankfurt)
Configure a chamada do SDK com o base_url: https://{WorkspaceId}.eu-central-1.maas.aliyuncs.com/compatible-mode/v1
Endpoint da requisição HTTP: POST https://{WorkspaceId}.eu-central-1.maas.aliyuncs.com/compatible-mode/v1/responses
China (Hong Kong)
Defina o base_url na configuração da chamada do SDK como: https://{WorkspaceId}.cn-hongkong.maas.aliyuncs.com/compatible-mode/v1
Endpoint da requisição HTTP: POST https://{WorkspaceId}.cn-hongkong.maas.aliyuncs.com/compatible-mode/v1/responses
Japan (Tokyo)
Configuração de chamada do SDK base_url: https://{WorkspaceId}.ap-northeast-1.maas.aliyuncs.com/compatible-mode/v1
Endpoint de requisição HTTP: POST https://{WorkspaceId}.ap-northeast-1.maas.aliyuncs.com/compatible-mode/v1/responses
Substitua {WorkspaceId} pelo seu workspace ID real.
ImportanteO Alibaba Cloud Model Studio lançou domínios específicos por workspace para as regiões China (Beijing), Singapore e China (Hong Kong). Os novos domínios dedicados oferecem desempenho superior e maior estabilidade para requisições de inferência. Recomendamos a migração para os novos domínios:
- China (Beijing): de
https://dashscope.aliyuncs.comparahttps://{WorkspaceId}.cn-beijing.maas.aliyuncs.com - Singapore: de
https://dashscope-intl.aliyuncs.comparahttps://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com - China (Hong Kong): de
https://cn-hongkong.dashscope.aliyuncs.comparahttps://{WorkspaceId}.cn-hongkong.maas.aliyuncs.com
O {WorkspaceId} corresponde ao ID do seu workspace, disponível na página Workspace Details no console do Alibaba Cloud Model Studio. O domínio existente permanece totalmente funcional.
ImportanteO caminho de URL legado /api/v2/apps/protocols/compatible-mode/v1/responses da Responses API compatível com OpenAI será descontinuado em breve. Migre para o novo caminho /compatible-mode/v1/responses o quanto antes.
Corpo da requisição | Chamada básicaSaída em streamConversa com múltiplas turnosFerramentas integradasFunction callingCompreensão de documentosCache de sessão |
model O ID do modelo a ser utilizado. Modelos suportados
ImportanteOs modelos de geração de texto que não constam na lista acima, mas disponíveis através do Alibaba Cloud Model Studio, suportam apenas funcionalidades básicas de compatibilidade. As capacidades de Agent (ferramentas integradas, etc.) são limitadas. |
input A entrada para o modelo. Os seguintes formatos são suportados:
Tipos de itens do array EasyInputMessage Um objeto com um Propriedades role A função do autor da mensagem. Valores válidos: content O conteúdo da mensagem. Os seguintes formatos são suportados:
Tipos de itens do array Um dos seguintes tipos: input_text Entrada de texto. Propriedades type Fixo como text O conteúdo de texto enviado ao modelo. input_image Entrada de imagem, apenas função Propriedades type Fixo como image_url A URL pública da imagem ou dados codificados em Base64. Para Base64, forneça um Data URI completo, por exemplo: input_file Entrada de arquivo, apenas função Propriedades type Fixo como file_url A URL pública do arquivo PDF. O arquivo pode ter até 100 MB. O limite de páginas do PDF depende de output_text Resposta do assistente, apenas função Propriedades type Fixo como text O conteúdo de texto da resposta do assistente. type Fixo como ResponseOutputMessage A mensagem de saída do modelo. Para continuar uma conversa, passe o objeto Propriedades type Fixo como id O identificador exclusivo da mensagem de saída, proveniente da resposta anterior. role Fixo como status O status da mensagem. Valores válidos: content Um array de conteúdo, onde os elementos são objetos Propriedades type Fixo como text O texto da resposta. annotations Informações de anotação. Function call Uma instrução estruturada gerada quando o modelo decide chamar uma ferramenta externa. Propriedades type Fixo como id O identificador exclusivo para a chamada de função, proveniente da resposta anterior. name O nome da função da ferramenta. arguments Os argumentos da chamada de ferramenta, no formato de string JSON. call_id O identificador para a chamada de ferramenta. Este deve corresponder ao status O status. Valores válidos: Function call output A saída de uma chamada de ferramenta. Na lista de mensagens, este objeto deve seguir imediatamente sua mensagem Propriedades type Fixo como id O identificador exclusivo para a saída da chamada de função. call_id O identificador da chamada de ferramenta deve corresponder ao output O resultado da execução da função da ferramenta. status O status. Valores válidos: Reasoning O processo de raciocínio do modelo. Passe o item Propriedades type Fixo como id O identificador exclusivo para o conteúdo de raciocínio, proveniente da resposta anterior. summary O conteúdo do resumo de raciocínio. Propriedades type Fixo como text O texto do resumo. status O status. Valores válidos: Web Search Call Um objeto de chamada de pesquisa na web. Passe o item web_search_call da saída da resposta anterior de volta para a entrada, fornecendo contexto de resultados de pesquisa em conversas de múltiplos turnos. Propriedades type Sempre id O identificador exclusivo da chamada de pesquisa, proveniente da resposta anterior. status O status da pesquisa. Valores válidos: action Os detalhes da ação de pesquisa. Apenas o tipo Propriedades type O tipo de pesquisa. Sempre queries Uma lista de consultas de pesquisa. Cada elemento é uma string. sources Uma lista de fontes de resultados de pesquisa. Propriedades type O tipo de fonte. Sempre url A URL da fonte. |
instructions Inserido no início do contexto como uma instrução do sistema. Quando |
previous_response_id O ID exclusivo da resposta anterior. O |
conversation A conversa à qual a resposta atual pertence (consulte Conversations API). O histórico da conversa é incluído automaticamente como contexto. A entrada e a saída desta solicitação são adicionadas à conversa após a conclusão. Não pode ser usado com |
stream Ativa a saída em stream. Se definido como |
store Especifica se a resposta do modelo gerada para esta sessão deve ser armazenada.
|
tools Um array de ferramentas que o modelo pode chamar ao gerar uma resposta. Há suporte tanto para ferramentas integradas quanto para ferramentas personalizadas do tipo
Propriedades Pesquisa na web Pesquisa informações atualizadas na internet. Documentação relacionada: Web Search Propriedades type Valor fixo: Exemplo: Acessa e extrai conteúdo de páginas da web. Deve ser usado junto com a ferramenta Propriedades type Valor fixo: Exemplo: Executa código em um ambiente isolado para realizar tarefas como análise de dados. Documentação relacionada: Code Interpreter Propriedades type Valor fixo: Exemplo: Busca imagens com base em uma descrição textual. Documentação relacionada: Text-to-Image Search Propriedades type Valor fixo: Exemplo: Encontra imagens semelhantes ou relacionadas com base em uma imagem de entrada. A entrada deve incluir a URL da imagem. Documentação relacionada: Image-to-Image Search Propriedades type Valor fixo: Exemplo: Realiza recuperação de conhecimento pesquisando em uma base de conhecimento especificada. Documentação relacionada: Knowledge Retrieval Propriedades type Valor fixo: vector_store_ids O ID da base de conhecimento a ser pesquisada. No momento, apenas um ID de base de conhecimento pode ser fornecido. Exemplo: Chama um service externo por meio do Model Context Protocol (MCP). Documentação relacionada: MCP Propriedades type Valor fixo: server_protocol O protocolo de comunicação com o service MCP, como server_label Um rótulo usado para identificar o service MCP. server_description Uma descrição do service. Ajuda o modelo a entender sua função e quando utilizá-lo. server_url A URL do endpoint do service MCP. headers Cabeçalhos da requisição, usados para transmitir informações como autenticação (por exemplo, Exemplo: Permite que o modelo chame uma função definida pelo desenvolvedor. Quando o modelo determina que uma ferramenta precisa ser chamada, a resposta retorna um item de saída do tipo Propriedades type Deve ser definido como name O nome da ferramenta. Pode conter apenas letras, dígitos, sublinhados ( description Uma descrição da ferramenta, que ajuda o modelo a decidir quando e como chamá-la. parameters A definição de parâmetros da ferramenta, que deve ser um objeto JSON Schema válido. Se
Exemplo: |
tool_choice Controla como o modelo seleciona e chama as ferramentas. Este parâmetro aceita dois formatos: modo string e modo object. Modo string
Restringe o modelo a um conjunto específico de ferramentas para seleção e chamada. Propriedades mode
tools Uma lista de definições de ferramentas que o modelo tem permissão para chamar. type O tipo de configuração da ferramenta. Valor fixo: |
parallel_tool_calls Define se a chamada paralela de ferramentas deve ser ativada. Para mais informações, consulte Chamada paralela de ferramentas.
Valores válidos:
|
temperature A temperatura de amostragem, que controla a diversidade do texto gerado. Valores mais altos tornam a saída mais aleatória e diversificada, enquanto valores mais baixos a tornam mais focada e determinística. Intervalo de valores: [0, 2) Tanto |
top_p O limiar de probabilidade para amostragem top-p, que controla a diversidade do texto gerado. Valores mais altos tornam a saída mais aleatória e diversificada, enquanto valores mais baixos a tornam mais focada e determinística. Intervalo de valores: (0, 1.0] Tanto |
enable_thinking Ativa ou desativa o modo de raciocínio. Quando ativado, o modelo executa uma etapa de raciocínio antes de responder. O processo de raciocínio é retornado como um item de saída do tipo Valores válidos:
Para valores padrão de diferentes modelos, consulte Supported models.
|
reasoning Controla o esforço de raciocínio do modelo. O modelo executa uma etapa de raciocínio antes de responder, e o processo de raciocínio é retornado por meio de um item de saída do tipo Para kimi-k3.1-pro (implantado no Alibaba Cloud Model Studio), Propriedades Os níveis e o valor padrão de kimi-k3.1-pro seguem a explicação acima. A descrição a seguir se aplica aos demais modelos. effort Aceita 7 níveis incrementais:
|
ocr_options Parâmetros de tarefas integradas de OCR. Aplicável apenas ao modelo Ao analisar arquivos PDF, o valor de
|
max_output_tokens
O valor mínimo é 16. Se a saída do modelo exceder esse valor, a geração é interrompida antecipadamente e o status é text Configuração da saída de texto do modelo. A saída pode ser texto simples ou dados JSON estruturados. Propriedades format O formato que o modelo deve produzir. Valor padrão: Um dos seguintes tipos: ResponseFormatText Formato padrão. Produz uma resposta em texto. Propriedades type Fixo como ResponseFormatTextJSONSchemaConfig Produz uma string JSON estritamente em conformidade com o JSON Schema especificado, o que permite controlar com precisão a estrutura da saída e os tipos dos campos. Compatível com a série qwen3.8, a série deepseek-v4, a série glm-5 e outros modelos; a série deepseek-v4.1 será compatível em breve. Com este tipo, o prompt não precisa conter a palavra-chave JSON. Propriedades type Fixo como json_schema A configuração do JSON Schema. Propriedades name O nome do schema. schema O objeto JSON Schema que descreve a estrutura da saída. Use strict Indica se a estrutura definida por ResponseFormatJSONObject Produz uma string formatada em JSON padrão. Compatível com a série qwen3.8, a série deepseek-v4, a série deepseek-v4.1, a série glm-5 e kimi-k3.1-pro (implantado no Alibaba Cloud Model Studio). Com este tipo, instrua explicitamente o modelo a gerar JSON no prompt, por exemplo: "Por favor, responda em formato JSON". Caso contrário, ocorrerá um erro. Propriedades type Fixo como |
Objeto de resposta (saída sem streaming) | |
id Identificador único desta resposta, no formato UUID. Este ID permanece válido por 7 dias e pode ser utilizado no parâmetro | |
created_at Timestamp Unix (em segundos) desta solicitação. | |
object Tipo do objeto, sempre definido como | |
status Status da geração da resposta. Valores válidos:
| |
model ID do modelo utilizado para gerar a resposta. | |
output Array de itens de saída gerados pelo modelo. O tipo e a ordem dos elementos dependem da resposta do modelo. Propriedades dos elementos do array type Tipo do item de saída. Valores válidos:
id Identificador único do item de saída. Todos os tipos de itens de saída contêm este campo. role A função da mensagem é sempre status Status do item de saída. Valores válidos: name Nome da ferramenta ou função. Este parâmetro está presente quando Para Para arguments Parâmetros da chamada de ferramenta, em formato de string JSON. Este parâmetro está presente quando
call_id ID único da chamada de função. Este parâmetro é incluído apenas quando content Array com o conteúdo da mensagem. Este parâmetro está presente apenas se Propriedades dos elementos do array type Tipo de conteúdo. O valor é fixo como text Contúdo de texto gerado pelo modelo. annotations Array de anotações de texto. Geralmente é um array vazio. summary Array de resumos de raciocínio. Este campo está presente apenas quando action Informações sobre a ação de pesquisa. Este parâmetro está presente apenas quando Propriedades query Palavras-chave da consulta de pesquisa. type Tipo de pesquisa. O valor é sempre sources Lista de fontes de pesquisa. Cada elemento contém os campos code Código gerado e executado pelo modelo. Existe apenas quando outputs Array de saída da execução de código. Presente apenas quando container_id Identificador do container do interpretador de código. Este parâmetro está presente apenas quando goal Descrição das informações a serem extraídas da página web. Disponível apenas quando output Saída da chamada de ferramenta. A saída é uma string.
urls Lista de URLs das páginas web extraídas. Disponível apenas quando server_label Rótulo do service MCP. Aparece apenas quando queries Lista de consultas para recuperação na base de conhecimento. Existe apenas quando results Array de resultados de pesquisa da base de conhecimento. Presente apenas quando Propriedades dos elementos do array file_id ID do arquivo do documento correspondente. filename Nome do arquivo do documento correspondente. score Pontuação de relevância da correspondência. O valor varia de 0 a 1. Um valor maior indica maior relevância. text Trecho de conteúdo do documento correspondente. | |
usage Informações sobre o consumo de tokens nesta solicitação. Propriedades input_tokens Número de tokens na entrada. Additional Notes output_tokens Quantidade de tokens na saída do modelo. total_tokens Total de tokens consumidos, correspondente à soma de input_tokens_details Classificação detalhada dos tokens de entrada. Propriedades cached_tokens Número de tokens que atingiram o cache. Para mais informações, consulte context caching. output_tokens_details Detalhamento dos tokens de saída. Propriedades reasoning_tokens Quantidade de tokens de raciocínio. x_details Array com detalhes de faturamento da solicitação. Fornece um detalhamento mais granular dos tokens multimodais do que o campo Propriedades input_tokens Número de tokens na entrada. Additional Notes output_tokens Quantidade de tokens na saída do modelo. total_tokens Total de tokens consumidos, correspondente à soma de x_billing_type Valor fixo definido como image_tokens Número de tokens para entrada de imagem. Este campo é retornado quando a entrada inclui uma imagem e equivale a input_tokens_details Detalhamento granular dos tokens de entrada. Retornado para entradas multimodais. Atualmente distingue apenas entre Propriedades text_tokens Quantidade de tokens para entrada de texto. image_tokens Número de tokens para entrada de imagem. output_tokens_details Detalhamento granular dos tokens de saída. Este campo possui um campo adicional Propriedades reasoning_tokens Quantidade de tokens utilizados no processo de raciocínio. text_tokens Número de tokens para saída de texto. Retornado para entradas multimodais. plugins Estatísticas de chamadas de ferramentas integradas. Retornado quando uma ferramenta integrada como Propriedades web_search Estatísticas das chamadas de pesquisa web. Propriedades count Número de vezes que a pesquisa web foi chamada nesta resposta. prompt_tokens_details Detalhes de cache para tokens de entrada. Retornado quando o cache de sessão está ativado. Pode retornar um objeto vazio se a entrada incluir uma imagem, mas resultar em cache miss. Propriedades cached_tokens Quantidade de tokens que atingiram o cache. cache_creation_input_tokens Número de tokens usados para criar um novo cache nesta solicitação. cache_creation Detalhes sobre a criação de cache. Propriedades ephemeral_5m_input_tokens Tokens utilizados para criar um novo cache efêmero de 5 minutos. cache_type Tipo de cache. Valor fixo definido como x_tools Estatísticas de uso de ferramentas. Contém o número de chamadas de cada ferramenta integrada. Exemplo: | |
error Um objeto de erro é retornado quando o modelo falha ao gerar uma resposta. Caso contrário, o valor é | |
tools Replica o conteúdo completo do parâmetro | |
tool_choice Repete o valor do parâmetro |
Objeto de fragmento de resposta (saída em streaming) | |
A saída em streaming retorna uma série de objetos JSON. Cada objeto inclui um campo | |
type Identificador do tipo de evento. Os valores possíveis incluem:
| |
sequence_number Número de sequência do evento, começando em 0 e incrementando a cada evento. Utilize este número para processar os eventos na ordem correta. | |
response Objeto de resposta. Presente nos eventos | |
item Objeto de item de saída. Aparece nos eventos Propriedades id Identificador exclusivo para o item de saída (por exemplo, type Tipo do item de saída. Valores possíveis: role Função da mensagem, que é sempre status Status de geração. Em um evento content Array de conteúdo da mensagem. No evento | |
part Objeto de parte de conteúdo. Presente nos eventos Propriedades type Tipo da parte de conteúdo, que é sempre text Conteúdo de texto. É uma string vazia no evento annotations Array de anotações de texto. Geralmente é um array vazio. logprobs Probabilidades logarítmicas de tokens. Atualmente, este campo sempre retorna | |
delta Segmento de texto incremental. Este campo aparece no evento | |
text Conteúdo de texto completo. Este campo aparece no evento | |
item_id Identificador exclusivo do item de saída. Utilize este ID para correlacionar eventos pertencentes ao mesmo item. | |
output_index Índice do item de saída no array | |
content_index Índice da parte de conteúdo no array |
Perguntas frequentes
P: Como passar o contexto em uma conversa de múltiplas turnos?R: Ao fazer uma nova solicitação de conversa, passe o id da resposta anterior bem-sucedida do modelo como o parâmetro previous_response_id.
R: O SDK oficial da OpenAI pode gerar campos adicionais definidos pelo protocolo da OpenAI. Nosso service não oferece suporte a esses campos, portanto, eles geralmente são null. Considere apenas os campos descritos neste tópico.