Skip to main content
Respostas compatíveis com OpenAI

Criar uma resposta

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_id da ú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.effort para controlar o nível de raciocínio do modelo. Para detalhes de uso, consulte a descrição deste parâmetro.
  • Singapore
  • China (Beijing)
  • US (Virginia)
  • Germany (Frankfurt)
  • China (Hong Kong)
  • Japan (Tokyo)
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
Substitua {WorkspaceId} pelo seu workspace ID real.
O 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.com para https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com
  • Singapore: de https://dashscope-intl.aliyuncs.com para https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com
  • China (Hong Kong): de https://cn-hongkong.dashscope.aliyuncs.com para https://{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.
O 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ásica
  • Saída em stream
  • Conversa com múltiplas turnos
  • Ferramentas integradas
  • Function calling
  • Compreensão de documentos
  • Cache de sessão
Python
import os
    from openai import OpenAI

    client = OpenAI(
        # If the environment variable is not set, replace with: api_key="sk-xxx"
        api_key=os.getenv("DASHSCOPE_API_KEY"),
        # Replace {WorkspaceId} with your actual workspace ID. URLs vary by region.    base_url="https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1",
    )

    response = client.responses.create(
        model="qwen3.8-max",
        input="What can you do?"
    )

    # Get the model's response
    print(response.output_text)
model string (obrigatório)O ID do modelo a ser utilizado.
qwen3.8-max, qwen3.8-flash, qwen3.7-max, qwen3.7-max-2026-05-20, qwen3.7-max-2026-06-08, qwen3.7-max-2026-05-17, qwen3.7-max-preview, qwen3-max, qwen3-max-2026-01-23, qwen3.7-plus, qwen3.7-plus-2026-05-26, qwen3.6-plus, qwen3.6-plus-2026-04-02, qwen3.5-plus, qwen3.5-plus-2026-04-20, qwen3.5-plus-2026-02-15, qwen3.7-flash, qwen3.7-flash-2026-07-15, qwen3.6-flash, qwen3.6-flash-2026-04-16, qwen3.5-flash, qwen3.5-flash-2026-02-23, qwen3.8-2.4t-a95b, qwen3.8-27b, qwen3.6-35b-a3b, qwen3.5-397b-a17b, qwen3.5-122b-a10b, qwen3.5-27b, qwen3.5-35b-a3b, deepseek-v4-pro, deepseek-v4-pro-0813, deepseek-v4-flash, deepseek-v4-flash-0731, glm-5.2, kimi-k3
Os 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 string ou array (obrigatório)A entrada para o modelo. Os seguintes formatos são suportados:
  • string: Texto simples, como "Hello".
  • array: Um array de mensagens, ordenado por turno de conversa.
EasyInputMessage objectUm objeto com um role para o autor da mensagem e content para o conteúdo da mensagem.
role string (obrigatório)A função do autor da mensagem. Valores válidos: user, assistant, system, developer.content string ou array (obrigatório)O conteúdo da mensagem. O conteúdo é uma string se a entrada for texto simples, ou um array se a entrada for um array de conteúdo estruturado. Quando o role é system ou developer, o tipo de elemento do array é input_text. Quando o role é user, o tipo de elemento do array é input_text, input_image ou input_file. Quando o role é assistant, o tipo de elemento do array é output_text.
A API Responses não suporta atualmente entrada de vídeo ou áudio. Para passar esses tipos de dados, use Chat Completions API ou DashScope API.
type string (obrigatório)Especifica o tipo de conteúdo. Os valores válidos são input_text, input_image (apenas função user), input_file (apenas função user, suporta PDF e imagens) e output_text (apenas função assistant).text stringO conteúdo de texto. Obrigatório quando type é input_text ou output_text.image_url stringSuporta uma URL ou dados codificados em Base64. Obrigatório quando type é input_image. Para Base64, forneça um Data URI completo, por exemplo: data:image/png;base64,iVBORw0KGgoAAAANSUhEUg....file_url stringA URL pública do arquivo. Obrigatória quando type é input_file. Suporta arquivos PDF (até 100 MB) e arquivos de imagem (até 20 MB). Atualmente suportado apenas por qwen3.5-ocr.O limite de páginas do PDF depende de task em ocr_options: até 50 páginas quando task é definido como document_parsing; até 10 páginas quando task não é definido ou é definido como outra tarefa.
type string (opcional)Fixo como message.
ResponseOutputMessage object (opcional)A mensagem de saída do modelo. Para continuar uma conversa, passe o objeto message do array output de uma resposta anterior de volta para o input. Diferente de EasyInputMessage, este objeto inclui a estrutura completa de saída, com id, status e content estruturado.
type string (obrigatório)Fixo como message.id string (obrigatório)O identificador exclusivo da mensagem de saída, proveniente da resposta anterior.role string (obrigatório)Fixo como assistant.status string (obrigatório)O status da mensagem. Valores válidos: in_progress, completed, incomplete.content array (obrigatório)Um array de conteúdo, onde os elementos são objetos output_text.
type string (obrigatório)Fixo como output_text.text string (obrigatório)O texto da resposta.annotations array (opcional)Informações de anotação.
Function call object (opcional)Uma instrução estruturada gerada quando o modelo decide chamar uma ferramenta externa.
type string (obrigatório)Fixo como function_call.id string (opcional)O identificador exclusivo para a chamada de função, proveniente da resposta anterior.name string (obrigatório)O nome da função da ferramenta.arguments string (obrigatório)Os argumentos da chamada de ferramenta, no formato de string JSON.call_id string (obrigatório)O identificador para a chamada de ferramenta. Este deve corresponder ao call_id retornado pelo modelo.status string (opcional)O status. Valores válidos: in_progress, completed, incomplete.
Function call output object (opcional)A saída de uma chamada de ferramenta. Na lista de mensagens, este objeto deve seguir imediatamente sua mensagem function_call correspondente para evitar falha na solicitação.
type string (obrigatório)Fixo como function_call_output.id string (opcional)O identificador exclusivo para a saída da chamada de função.call_id string (obrigatório)O identificador da chamada de ferramenta deve corresponder ao call_id retornado pelo modelo.output string (obrigatório)O resultado da execução da função da ferramenta.status string (opcional)O status. Valores válidos: in_progress, completed, incomplete.
Reasoning object (opcional)O processo de raciocínio do modelo. Passe o item reasoning do output de uma resposta anterior de volta para o input para continuar esse processo em um turno subsequente.
type string (obrigatório)Fixo como reasoning.id string (obrigatório)O identificador exclusivo para o conteúdo de raciocínio, proveniente da resposta anterior.summary array (obrigatório)O conteúdo do resumo de raciocínio.
type string (obrigatório)Fixo como summary_text.text string (obrigatório)O texto do resumo.
status string (opcional)O status. Valores válidos: in_progress, completed, incomplete.
Web Search Call object (opcional)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.
type string (obrigatório)Sempre web_search_call.id string (obrigatório)O identificador exclusivo da chamada de pesquisa, proveniente da resposta anterior.status string (obrigatório)O status da pesquisa. Valores válidos: in_progress, searching, completed, failed.action object (obrigatório)Os detalhes da ação de pesquisa. Apenas o tipo search é suportado.
type string (obrigatório)O tipo de pesquisa. Sempre search.queries array (opcional)Uma lista de consultas de pesquisa. Cada elemento é uma string.sources array (opcional)Uma lista de fontes de resultados de pesquisa.
type string (obrigatório)O tipo de fonte. Sempre url.url string (obrigatório)A URL da fonte.
instructionsstring (opcional)Inserido no início do contexto como uma instrução do sistema. Quando previous_response_id é utilizado, as instructions especificadas no turno anterior não são passadas para o contexto do turno atual.
previous_response_id string (opcional)O ID exclusivo da resposta anterior. O id de uma resposta é válido por 7 dias. Use este parâmetro para criar conversas de múltiplos turnos. O servidor recupera e combina automaticamente a entrada e a saída desse turno como contexto. Se você fornecer tanto o array de mensagens de input quanto o previous_response_id, as novas mensagens no input serão anexadas ao contexto histórico. Este parâmetro não pode ser usado com conversation.
conversation string (opcional)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 previous_response_id.
stream boolean (opcional) O padrão é falseAtiva a saída em stream. Se definido como true, o modelo transmite a resposta em tempo real.
store boolean (opcional) O padrão é trueEspecifica se a resposta do modelo gerada para esta sessão deve ser armazenada.
  • false: A resposta não é armazenada e não pode ser referenciada em chamadas subsequentes via previous_response_id.
  • true: A resposta é armazenada. A resposta atual do modelo pode ser referenciada por previous_response_id e chamadas de API subsequentes.
tools array (opcional)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 function, que podem ser usadas em conjunto.
Para obter os melhores resultados, ative as ferramentas code_interpreter, web_search e web_extractor.
Pesquisa na webPesquisa informações atualizadas na internet. Documentação relacionada: Web Search
type string (obrigatório)Valor fixo: web_search.Exemplo: [{"type": "web_search"}]
Extrator da webAcessa e extrai conteúdo de páginas da web. Deve ser usado junto com a ferramenta web_search. Para os modelos qwen3-max e qwen3-max-2026-01-23, também é necessário ativar o modo de raciocínio. Documentação relacionada: Web Extraction
type string (obrigatório)Valor fixo: web_extractor.Exemplo: [{"type": "web_search"}, {"type": "web_extractor"}]
Interpretador de códigoExecuta código em um ambiente isolado para realizar tarefas como análise de dados. Nos modelos qwen3-max e qwen3-max-2026-01-23, o modo de raciocínio também precisa estar ativado. Documentação relacionada: Code Interpreter
type string (obrigatório)Valor fixo: code_interpreter.Exemplo: [{"type": "code_interpreter"}]
Pesquisa de imagens na webBusca imagens com base em uma descrição textual. Documentação relacionada: Text-to-Image Search
type string (obrigatório)Valor fixo: web_search_image.Exemplo: [{"type": "web_search_image"}]
Pesquisa por imagemEncontra 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
type string (obrigatório)Valor fixo: image_search.Exemplo: [{"type": "image_search"}]
Pesquisa em arquivosRealiza recuperação de conhecimento pesquisando em uma base de conhecimento especificada. Documentação relacionada: Knowledge Retrieval
type string (obrigatório)Valor fixo: file_search.vector_store_ids array(obrigatório)O ID da base de conhecimento a ser pesquisada. No momento, apenas um ID de base de conhecimento pode ser fornecido.Exemplo: [{"type": "file_search", "vector_store_ids": ["your_knowledge_base_id"]}]
Invocação MCPChama um service externo por meio do Model Context Protocol (MCP). Documentação relacionada: MCP
type string (obrigatório)Valor fixo: mcp.server_protocol string (obrigatório)O protocolo de comunicação com o service MCP, como "sse".server_label string (obrigatório)Um rótulo usado para identificar o service MCP.server_description string (opcional)Uma descrição do service. Ajuda o modelo a entender sua função e quando utilizá-lo.server_url string (obrigatório)A URL do endpoint do service MCP.headers object (opcional)Cabeçalhos da requisição, usados para transmitir informações como autenticação (por exemplo, Authorization).Exemplo:
mcp_tool = {
    "type": "mcp",
    "server_protocol": "sse",
    "server_label": "amap-maps",
    "server_description": "The AMap MCP Server provides a full suite of geographic information services, covering 15 core APIs. These include custom map generation, navigation, ride-hailing, geocoding, reverse geocoding, IP-based location, weather queries, and planning for cycling, walking, driving, and public transit routes, along with distance measurement and various search functions.",
    "server_url": "https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/mcps/amap-maps/sse",
    "headers": {
        "Authorization": "Bearer <your-mcp-server-token>"
    }
}
Ferramenta personalizadafunctionPermite 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 function_call. Documentação relacionada: Function calling
type string (obrigatório)Deve ser definido como function.namestring(obrigatório)O nome da ferramenta. Pode conter apenas letras, dígitos, sublinhados (_) e hifens (-), com comprimento máximo de 64 tokens.descriptionstring(obrigatório)Uma descrição da ferramenta, que ajuda o modelo a decidir quando e como chamá-la.parameters object (opcional)A definição de parâmetros da ferramenta, que deve ser um objeto JSON Schema válido. Se parameters estiver vazio, a ferramenta não aceita argumentos (por exemplo, uma ferramenta de consulta de hora).
Para melhorar a precisão das chamadas de ferramentas, recomendamos definir parameters.
Exemplo:
[{
  "type": "function",
  "name": "get_weather",
  "description": "Get weather information for a specified city",
  "parameters": {
    "type": "object",
    "properties": {
      "city": {
        "type": "string",
        "description": "The name of the city"
      }
    },
    "required": ["city"]
  }
}]
tool_choice string ou object (opcional) O padrão é autoControla como o modelo seleciona e chama as ferramentas. Este parâmetro aceita dois formatos: modo string e modo object.Modo string
  • auto: O modelo decide se deve chamar uma ferramenta.
  • none: Impede que o modelo chame qualquer ferramenta.
  • required: Força o modelo a chamar uma ferramenta. Disponível apenas quando a lista tools contém exatamente uma ferramenta.
Modo objectRestringe o modelo a um conjunto específico de ferramentas para seleção e chamada.
mode string (obrigatório)
  • auto: O modelo decide automaticamente se chama uma ferramenta da lista fornecida.
  • required: Obriga o modelo a chamar uma ferramenta da lista fornecida. Disponível apenas quando a lista tools contém exatamente uma ferramenta.
tools array(obrigatório)Uma lista de definições de ferramentas que o modelo tem permissão para chamar.
[
  { "type": "function", "name": "get_weather" }
]
typestring (obrigatório)O tipo de configuração da ferramenta. Valor fixo: allowed_tools.
temperaturefloat(opcional)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 temperature quanto top_p controlam a diversidade do texto gerado. Recomendamos usar apenas um desses parâmetros por vez. Para mais informações, consulte Overview.
top_pfloat(opcional)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 temperature quanto top_p controlam a diversidade do texto gerado. Recomendamos usar apenas um desses parâmetros por vez. Para mais informações, consulte Overview.
enable_thinking boolean (opcional)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 reasoning. Ao ativar o modo de raciocínio, recomendamos também habilitar as ferramentas integradas para obter os melhores resultados em tarefas complexas.Valores válidos:
  • true: Ativa o modo de raciocínio.
  • false: Desativa o modo de raciocínio.
Para valores padrão de diferentes modelos, consulte Supported models.
Este parâmetro não é um parâmetro padrão da OpenAI. No SDK Python, passe-o usando extra_body={"enable_thinking": True}. No SDK Node.js e no curl, use enable_thinking: true como um parâmetro de nível superior. Recomendamos o uso de reasoning.effort em seu lugar, pois enable_thinking será descontinuado.
reasoning object (opcional)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 reasoning.
effort string (opcional): O nível de esforço de raciocínio. O padrão é xhigh.Aceita 7 níveis incrementais: none, minimal, low, medium, high, xhigh e max. Reduzir este valor acelera a velocidade de resposta e diminui o consumo de tokens de inferência.
Os níveis xhigh e max têm suporte apenas em China (Beijing) e Singapore.
reasoning.effort tem precedência sobre enable_thinking. Recomendamos o uso de reasoning.effort, pois enable_thinking será descontinuado.
ocr_options object (opcional)Parâmetros de tarefas integradas de OCR. Aplicável apenas ao modelo qwen3.5-ocr. Use este parâmetro para chamar tarefas integradas de OCR (como extração de informações e localização de texto). Os resultados das tarefas integradas são retornados no campo ocr_result da resposta.Ao analisar arquivos PDF, o valor de task determina o número de páginas suportadas: até 50 páginas quando definido como document_parsing; até 10 páginas quando task não é definido ou é definido como outra tarefa.
Este parâmetro não é um parâmetro padrão da OpenAI. No SDK Python, passe-o usando extra_body={"ocr_options": {...}}. No SDK Node.js e no curl, use ocr_options como um parâmetro de nível superior.
max_output_tokens integer (opcional)
  • Série Qwen3.8: o número máximo total de tokens combinando o conteúdo da resposta do modelo e o conteúdo da cadeia de pensamento.
  • Demais modelos: o número máximo de tokens no conteúdo da resposta do modelo.
O valor mínimo é 16. Se a saída do modelo exceder esse valor, a geração é interrompida antecipadamente e o status é incomplete.

Objeto de resposta (saída sem streaming)

{
        "created_at": 1771165900.0,
        "id": "f75c28fb-4064-48ed-90da-4d2cc4362xxx",
        "model": "qwen3.8-max",
        "object": "response",
        "output": [
            {
                "content": [
                    {
                        "annotations": [],
                        "text": "Hello! I am Qwen3.5, a large language model developed by Alibaba Cloud with knowledge up to 2026, designed to assist you with complex reasoning, creative tasks, and multilingual conversations.",
                        "type": "output_text"
                    }
                ],
                "id": "msg_89ad23e6-f128-4d4c-b7a1-a786e7880xxx",
                "role": "assistant",
                "status": "completed",
                "type": "message"
            }
        ],
        "parallel_tool_calls": false,
        "status": "completed",
        "tool_choice": "auto",
        "tools": [],
        "usage": {
            "input_tokens": 57,
            "input_tokens_details": {
                "cached_tokens": 0
            },
            "output_tokens": 44,
            "output_tokens_details": {
                "reasoning_tokens": 0
            },
            "total_tokens": 101,
            "x_details": [
                {
                    "input_tokens": 57,
                    "output_tokens": 44,
                    "total_tokens": 101,
                    "x_billing_type": "response_api"
                }
            ]
        }
    }
id stringIdentificador único desta resposta, no formato UUID. Este ID permanece válido por 7 dias e pode ser utilizado no parâmetro previous_response_id para criar uma conversa com múltiplas turnos.
created_at integerTimestamp Unix (em segundos) desta solicitação.
object stringTipo do objeto, sempre definido como response.
status stringStatus da geração da resposta. Valores válidos:
  • completed: Geração concluída.
  • failed: Falha na geração.
  • in_progress: Geração em andamento.
  • cancelled: Geração cancelada.
  • queued: Solicitação enfileirada.
  • incomplete: Geração incompleta.
model stringID do modelo utilizado para gerar a resposta.
output arrayArray de itens de saída gerados pelo modelo. O tipo e a ordem dos elementos dependem da resposta do modelo.
type stringTipo do item de saída. Valores válidos:
  • message: Item de mensagem contendo o conteúdo final da resposta do modelo.
  • reasoning: Tipo de raciocínio. Este parâmetro é retornado quando reasoning.effort possui um valor diferente de none ou quando o modo de raciocínio está ativado. Os tokens de raciocínio são contabilizados em output_tokens_details.reasoning_tokens e faturados como tokens de raciocínio.
  • function_call: Tipo de chamada de função. Retornado quando uma ferramenta function personalizada é utilizada. Processe a chamada de função e retorne o resultado.
  • web_search_call: Tipo de chamada de pesquisa. Retornado quando a ferramenta web_search é utilizada.
  • code_interpreter_call: Tipo de execução de código, retornado quando a ferramenta code_interpreter é utilizada.
  • web_extractor_call: Tipo de extração web. Retornado quando a ferramenta web_extractor é utilizada. Deve ser usado em conjunto com a ferramenta web_search.
  • web_search_image_call: Tipo de chamada para pesquisa de texto para imagem. Retornado ao utilizar a ferramenta web_search_image. Contém uma lista das imagens encontradas.
  • image_search_call: Tipo de chamada para pesquisa de imagem por similaridade. Retornado quando a ferramenta image_search é utilizada. Contém uma lista de imagens semelhantes.
  • mcp_call: Tipo de chamada MCP. Retornado ao utilizar a ferramenta mcp. Contém o resultado da chamada ao service MCP.
  • file_search_call: Tipo de chamada para pesquisa em base de conhecimento, retornado ao utilizar a ferramenta file_search. Contém a consulta de recuperação e os resultados da base de conhecimento.
id stringIdentificador único do item de saída. Todos os tipos de itens de saída contêm este campo.role stringA função da mensagem é sempre assistant. Este parâmetro está presente apenas quando type é message.status stringStatus do item de saída. Valores válidos: completed e in_progress. Este parâmetro está presente quando o parâmetro type não está definido como reasoning.name stringNome da ferramenta ou função. Este parâmetro está presente quando type é function_call, web_search_image_call, image_search_call ou mcp_call.Para web_search_image_call e image_search_call, os valores são fixos como "web_search_image" e "image_search", respectivamente.Para mcp_call, o valor corresponde ao nome da função específica chamada no service MCP, como amap-maps-maps_geo.arguments stringParâmetros da chamada de ferramenta, em formato de string JSON. Este parâmetro está presente quando type é function_call, web_search_image_call, image_search_call ou mcp_call. Faça o parse da string utilizando JSON.parse() antes de usar. O conteúdo dos argumentos para os diferentes tipos de ferramentas é o seguinte:
  • web_search_image_call: {"queries": ["Search Keyword 1", "Search Keyword 2"]}, onde queries é uma lista de palavras-chave de pesquisa geradas automaticamente pelo modelo com base na entrada do usuário.
  • image_search_call: {"img_idx": 0, "bbox": [0, 0, 1000, 1000]}, onde img_idx é o índice da imagem de entrada (começando em 0) e bbox representa as coordenadas da caixa delimitadora [x1, y1, x2, y2] da área de pesquisa. Os valores das coordenadas variam de 0 a 1000.
  • function_call: Objeto de parâmetros gerado a partir do schema de parâmetros da função definida pelo usuário.
  • mcp_call: Objeto de parâmetros da função chamada no service MCP.
call_id stringID único da chamada de função. Este parâmetro é incluído apenas quando type é function_call. É obrigatório incluir este ID no resultado da chamada de função para vincular a solicitação à resposta.content arrayArray com o conteúdo da mensagem. Este parâmetro está presente apenas se type estiver definido como message.
type stringTipo de conteúdo. O valor é fixo como output_text.text stringContúdo de texto gerado pelo modelo.annotations arrayArray de anotações de texto. Geralmente é um array vazio.
summary arrayArray de resumos de raciocínio. Este campo está presente apenas quando type é reasoning. Cada elemento contém o campo type (valor: summary_text) e o campo text (o texto do resumo).action objectInformações sobre a ação de pesquisa. Este parâmetro está presente apenas quando type é web_search_call.
query stringPalavras-chave da consulta de pesquisa.type stringTipo de pesquisa. O valor é sempre search.sources arrayLista de fontes de pesquisa. Cada elemento contém os campos type e url.
code stringCódigo gerado e executado pelo modelo. Existe apenas quando type é code_interpreter_call.outputs arrayArray de saída da execução de código. Presente apenas quando type é code_interpreter_call. Cada elemento possui um campo type (com valor logs) e um campo logs (os logs de execução do código).container_id stringIdentificador do container do interpretador de código. Este parâmetro está presente apenas quando type é code_interpreter_call. Este identificador associa múltiplas execuções de código dentro da mesma sessão.goal stringDescrição das informações a serem extraídas da página web. Disponível apenas quando type é web_extractor_call.output stringSaída da chamada de ferramenta. A saída é uma string.
  • Se type for web_extractor_call, trata-se de um resumo do conteúdo extraído da página web.
  • Caso type seja web_search_image_call ou image_search_call, será uma string JSON contendo um array de resultados de pesquisa de imagens. Cada elemento inclui os campos title, url e index.
  • Quando type é mcp_call, corresponde à string JSON de resultado retornada pelo service MCP.
urls arrayLista de URLs das páginas web extraídas. Disponível apenas quando type é web_extractor_call.server_label stringRótulo do service MCP. Aparece apenas quando type é mcp_call. Indica qual service MCP foi utilizado na chamada.queries arrayLista de consultas para recuperação na base de conhecimento. Existe apenas quando type é file_search_call. O array contém strings, sendo cada uma delas uma consulta de pesquisa gerada pelo modelo.results arrayArray de resultados de pesquisa da base de conhecimento. Presente apenas quando type é file_search_call.
file_id stringID do arquivo do documento correspondente.filename stringNome do arquivo do documento correspondente.score floatPontuação de relevância da correspondência. O valor varia de 0 a 1. Um valor maior indica maior relevância.text stringTrecho de conteúdo do documento correspondente.
usage objectInformações sobre o consumo de tokens nesta solicitação.
input_tokens integerNúmero de tokens na entrada. Additional Notesoutput_tokens integerQuantidade de tokens na saída do modelo.total_tokens integerTotal de tokens consumidos, correspondente à soma de input_tokens e output_tokens.input_tokens_details objectClassificação detalhada dos tokens de entrada.
cached_tokens integerNúmero de tokens que atingiram o cache. Para mais informações, consulte context caching.
output_tokens_details objectDetalhamento dos tokens de saída.
reasoning_tokens integerQuantidade de tokens de raciocínio.
x_details arrayArray com detalhes de faturamento da solicitação. Fornece um detalhamento mais granular dos tokens multimodais do que o campo usage de nível superior.
input_tokens integerNúmero de tokens na entrada. Additional Notesoutput_tokens integerQuantidade de tokens na saída do modelo.total_tokens integerTotal de tokens consumidos, correspondente à soma de input_tokens e output_tokens.x_billing_type stringValor fixo definido como response_api.image_tokens integerNúmero de tokens para entrada de imagem. Este campo é retornado quando a entrada inclui uma imagem e equivale a input_tokens_details.image_tokens.input_tokens_details objectDetalhamento granular dos tokens de entrada. Retornado para entradas multimodais. Atualmente distingue apenas entre text_tokens e image_tokens. Não fornece detalhamento para tokens de vídeo ou áudio.
text_tokens integerQuantidade de tokens para entrada de texto.image_tokens integerNúmero de tokens para entrada de imagem.
output_tokens_details objectDetalhamento granular dos tokens de saída. Este campo possui um campo adicional text_tokens em comparação com o output_tokens_details de nível superior. O campo text_tokens é retornado para entradas multimodais.
reasoning_tokens integerQuantidade de tokens utilizados no processo de raciocínio.text_tokens integerNúmero de tokens para saída de texto. Retornado para entradas multimodais.
plugins objectEstatísticas de chamadas de ferramentas integradas. Retornado quando uma ferramenta integrada como web_search é utilizada. Seu conteúdo é idêntico ao campo x_tools de nível superior.
web_search objectEstatísticas das chamadas de pesquisa web.
count integerNúmero de vezes que a pesquisa web foi chamada nesta resposta.
prompt_tokens_details objectDetalhes 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.
cached_tokens integerQuantidade de tokens que atingiram o cache.cache_creation_input_tokens integerNúmero de tokens usados para criar um novo cache nesta solicitação.cache_creation objectDetalhes sobre a criação de cache.
ephemeral_5m_input_tokens integerTokens utilizados para criar um novo cache efêmero de 5 minutos.
cache_type stringTipo de cache. Valor fixo definido como ephemeral.
x_tools objectEstatísticas de uso de ferramentas. Contém o número de chamadas de cada ferramenta integrada.Exemplo: {"web_search": {"count": 1}}
error objectUm objeto de erro é retornado quando o modelo falha ao gerar uma resposta. Caso contrário, o valor é null.
tools arrayReplica o conteúdo completo do parâmetro tools da solicitação, mantendo a mesma estrutura do parâmetro tools no corpo da requisição.
tool_choice stringRepete o valor do parâmetro tool_choice da solicitação. Os valores válidos são auto, none e required.

Objeto de fragmento de resposta (saída em streaming)

// response.created: The response is created and queued.
{"response":{"id":"428c90e9-9cd6-90a6-9726-c02b08ebexxx","created_at":1769082930,"object":"response","status":"queued",...},"sequence_number":0,"type":"response.created"}

// response.in_progress: Processing begins.
{"response":{"id":"428c90e9-9cd6-90a6-9726-c02b08ebexxx","status":"in_progress",...},"sequence_number":1,"type":"response.in_progress"}

// response.output_item.added: A new output item is added.
{"item":{"id":"msg_bcb45d66-fc34-46a2-bb56-714a51e8exxx","content":[],"role":"assistant","status":"in_progress","type":"message"},"output_index":0,"sequence_number":2,"type":"response.output_item.added"}

// response.content_part.added: A new content part is added.
{"content_index":0,"item_id":"msg_bcb45d66-fc34-46a2-bb56-714a51e8exxx","output_index":0,"part":{"annotations":[],"text":"","type":"output_text","logprobs":null},"sequence_number":3,"type":"response.content_part.added"}

// response.output_text.delta: Incremental text (can be triggered multiple times).
{"content_index":0,"delta":"Artificial Intelligence","item_id":"msg_bcb45d66-fc34-46a2-bb56-714a51e8exxx","logprobs":[],"output_index":0,"sequence_number":4,"type":"response.output_text.delta"}
{"content_index":0,"delta":" (AI) refers to the technology","item_id":"msg_bcb45d66-fc34-46a2-bb56-714a51e8exxx","logprobs":[],"output_index":0,"sequence_number":6,"type":"response.output_text.delta"}

// response.output_text.done: Text generation for a content part is complete.
{"content_index":0,"item_id":"msg_bcb45d66-fc34-46a2-bb56-714a51e8exxx","logprobs":[],"output_index":0,"sequence_number":53,"text":"Artificial Intelligence (AI) refers to the technology and science that enables computer systems to simulate human intelligent behaviors...","type":"response.output_text.done"}

// response.content_part.done: The content part is complete.
{"content_index":0,"item_id":"msg_bcb45d66-fc34-46a2-bb56-714a51e8exxx","output_index":0,"part":{"annotations":[],"text":"...full text...","type":"output_text","logprobs":null},"sequence_number":54,"type":"response.content_part.done"}

// response.output_item.done: The output item is complete.
{"item":{"id":"msg_bcb45d66-fc34-46a2-bb56-714a51e8exxx","content":[{"annotations":[],"text":"...full text...","type":"output_text","logprobs":null}],"role":"assistant","status":"completed","type":"message"},"output_index":0,"sequence_number":55,"type":"response.output_item.done"}

// response.completed: The response is complete (includes full response and usage).
{"response":{"id":"428c90e9-9cd6-90a6-9726-c02b08ebexxx","created_at":1769082930,"model":"qwen3.7-max","object":"response","output":[...],"status":"completed","usage":{"input_tokens":37,"output_tokens":243,"total_tokens":280,...}},"sequence_number":56,"type":"response.completed"}
A saída em streaming retorna uma série de objetos JSON. Cada objeto inclui um campo type para especificar o tipo de evento e um campo sequence_number para indicar a ordem dos eventos. O evento response.completed marca o fim do stream.
type stringIdentificador do tipo de evento. Os valores possíveis incluem:
  • response.created: A resposta é criada com status queued.
  • response.in_progress: O processamento da resposta começa e o status muda para in_progress.
  • response.output_item.added: Um novo item de saída (por exemplo, uma mensagem ou um web_extractor_call) é adicionado ao array de saída. Quando item.type é web_extractor_call, isso indica o início de uma chamada de ferramenta de extração web.
  • response.content_part.added: Uma nova parte de conteúdo é adicionada ao array content de um item de saída.
  • response.output_text.delta: Um segmento de texto incremental é gerado. Este evento é acionado várias vezes, e o campo delta contém o novo segmento de texto.
  • response.output_text.done: A geração de texto para uma parte de conteúdo foi concluída. O campo text contém o texto completo.
  • response.content_part.done: Uma parte de conteúdo está completa. O objeto part contém a parte de conteúdo completa.
  • response.output_item.done: Um item de saída está completo. O objeto item contém o item de saída completo. Quando item.type é web_extractor_call, isso indica a conclusão de uma chamada de ferramenta de extração web.
  • response.reasoning_text.delta: (No modo de raciocínio) Fornece uma atualização incremental para o resumo de raciocínio. O campo delta contém o novo segmento.
  • response.reasoning_text.done: (No modo de raciocínio) O resumo de raciocínio está completo. O campo text contém o resumo completo.
  • response.custom_tool_call_input.delta: Fornece uma atualização incremental para a entrada da chamada de ferramenta personalizada. O campo delta contém o segmento recém-gerado.
  • response.custom_tool_call_input.done: A entrada da chamada de ferramenta personalizada está completa. O campo input contém a entrada completa.
  • response.web_search_call.in_progress / searching / completed: Evento que indica alteração no status da busca ao utilizar a ferramenta web_search.
  • response.code_interpreter_call.in_progress / interpreting / completed: Evento referente à mudança no status de execução de código (ao usar a ferramenta code_interpreter).
  • Nota: A ferramenta web_extractor não possui um identificador de tipo de evento dedicado. Suas chamadas são transmitidas pelos eventos gerais response.output_item.added e response.output_item.done, sendo identificadas pelo campo item.type com valor web_extractor_call.
  • response.mcp_call_arguments.delta / response.mcp_call_arguments.done: Estes eventos fornecem o delta e o status de conclusão para os argumentos da chamada MCP.
  • response.mcp_call.in_progress: A chamada de service MCP está em andamento.
  • response.mcp_call.completed: A chamada de service MCP foi concluída.
  • response.file_search_call.in_progress / searching / completed: Eventos de mudança de status para busca em base de conhecimento (ao usar a ferramenta file_search).
  • Nota: Ao utilizar as ferramentas web_search_image e image_search, não há eventos dedicados de estado intermediário. As chamadas de ferramenta são comunicadas através dos eventos response.output_item.added (início da chamada) e response.output_item.done (chamada concluída).
  • response.completed: A geração da resposta foi concluída. O objeto response contém a resposta completa, incluindo o uso. Este evento marca o fim do stream.
  • response.incomplete: A resposta terminou antecipadamente devido a limites como max_output_tokens.
sequence_number integerNú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 objectObjeto de resposta. Presente nos eventos response.created, response.in_progress e response.completed. No evento response.completed, ele contém os dados completos da resposta (incluindo output e usage), e sua estrutura é idêntica à do objeto Response não-streaming.
item objectObjeto de item de saída. Aparece nos eventos response.output_item.added e response.output_item.done. No evento added, trata-se de um esqueleto inicial onde o content é um array vazio. No evento done, é um objeto completo.
id stringIdentificador exclusivo para o item de saída (por exemplo, msg_xxx).type stringTipo do item de saída. Valores possíveis: message, reasoning, web_search_call, web_search_image_call (busca de texto para imagem), image_search_call (busca de imagem para imagem), mcp_call (chamada MCP), file_search_call (busca em base de conhecimento).role stringFunção da mensagem, que é sempre assistant. Presente apenas quando type é message.status stringStatus de geração. Em um evento added, o status é in_progress; em um evento done, é completed.content arrayArray de conteúdo da mensagem. No evento added, o array está vazio []. No evento done, contém objetos completos de partes de conteúdo cuja estrutura é igual à do objeto part.
part objectObjeto de parte de conteúdo. Presente nos eventos response.content_part.added e response.content_part.done.
type stringTipo da parte de conteúdo, que é sempre output_text.text stringConteúdo de texto. É uma string vazia no evento added e o texto completo no evento done.annotations arrayArray de anotações de texto. Geralmente é um array vazio.logprobs object | nullProbabilidades logarítmicas de tokens. Atualmente, este campo sempre retorna null.
delta stringSegmento de texto incremental. Este campo aparece no evento response.output_text.delta e contém o segmento de texto recém-adicionado. Concatene todos os valores de delta para reconstruir o texto completo.
text stringConteúdo de texto completo. Este campo aparece no evento response.output_text.done. Use-o para validar o texto reconstruído a partir dos fragmentos delta.
item_id stringIdentificador exclusivo do item de saída. Utilize este ID para correlacionar eventos pertencentes ao mesmo item.
output_index integerÍndice do item de saída no array output.
content_index integerÍndice da parte de conteúdo no array content.

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. P: Por que alguns campos no exemplo de resposta não estão descritos neste tópico? 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.
Geração de Imagens
  • FAQ
Geração de Vídeo
Áudio
API em tempo real
Incorporação de Texto
Produção de Modelos