Todos os produtos
Search
Central de documentação

Alibaba Cloud Model Studio:Criar uma resposta

Última atualização: Nov 05, 2026

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

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.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.

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ásica

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)
import OpenAI from "openai";

    const openai = new OpenAI({
        // If the environment variable is not set, replace with: apiKey: "sk-xxx"
        apiKey: process.env.DASHSCOPE_API_KEY,
        // Replace {WorkspaceId} with your actual workspace ID. URLs vary by region.
        baseURL: "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1"
    });

    async function main() {
        const response = await openai.responses.create({
            model: "qwen3.8-max",
            input: "What can you do?"
        });

        // Get the model's response
        console.log(response.output_text);
    }

    main();
curl -X POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1/responses \
    -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
        "model": "qwen3.8-max",
        "input": "What can you do?"
    }'

Saída em stream

import os
    from openai import OpenAI

    client = OpenAI(
        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",
    )

    stream = client.responses.create(
        model="qwen3.8-max",
        input="Briefly introduce artificial intelligence.",
        stream=True
    )

    print("Receiving stream output:")
    for event in stream:
        if event.type == 'response.output_text.delta':
            print(event.delta, end='', flush=True)
        elif event.type == 'response.completed':
            print("\nStream completed")
            print(f"Total tokens: {event.response.usage.total_tokens}")
import OpenAI from "openai";

    const openai = new OpenAI({
        apiKey: process.env.DASHSCOPE_API_KEY,
        // Replace {WorkspaceId} with your actual workspace ID. URLs vary by region.
        baseURL: "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1"
    });

    async function main() {
        const stream = await openai.responses.create({
            model: "qwen3.8-max",
            input: "Briefly introduce artificial intelligence.",
            stream: true
        });

        console.log("Receiving stream output:");
        for await (const event of stream) {
            if (event.type === 'response.output_text.delta') {
                process.stdout.write(event.delta);
            } else if (event.type === 'response.completed') {
                console.log("\nStream completed");
                console.log(`Total tokens: ${event.response.usage.total_tokens}`);
            }
        }
    }

    main();
curl -X POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1/responses \
    -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
    -H "Content-Type: application/json" \
    --no-buffer \
    -d '{
        "model": "qwen3.8-max",
        "input": "Briefly introduce artificial intelligence.",
        "stream": true
    }'

Conversa com múltiplas turnos

import os
    from openai import OpenAI

    client = OpenAI(
        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",
    )

    # First turn
    response1 = client.responses.create(
        model="qwen3.8-max",
        input="My name is John. Please remember it."
    )
    print(f"First response: {response1.output_text}")

    # Second turn - use previous_response_id to link context. The response ID is valid for 7 days.
    response2 = client.responses.create(
        model="qwen3.8-max",
        input="Do you remember my name?",
        previous_response_id=response1.id
    )
    print(f"Second response: {response2.output_text}")
import OpenAI from "openai";

    const openai = new OpenAI({
        apiKey: process.env.DASHSCOPE_API_KEY,
        // Replace {WorkspaceId} with your actual workspace ID. URLs vary by region.
        baseURL: "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1"
    });

    async function main() {
        // First turn
        const response1 = await openai.responses.create({
            model: "qwen3.8-max",
            input: "My name is John. Please remember it."
        });
        console.log(`First response: ${response1.output_text}`);

        // Second turn - use previous_response_id to link context. The response ID is valid for 7 days.
        const response2 = await openai.responses.create({
            model: "qwen3.8-max",
            input: "Do you remember my name?",
            previous_response_id: response1.id
        });
        console.log(`Second response: ${response2.output_text}`);
    }

    main();

Ferramentas integradas

import os
    from openai import OpenAI

    client = OpenAI(
        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="Find the Alibaba Cloud official website and extract key information from its homepage.",
        # For best results, we recommend enabling the built-in tools.
        tools=[
            {"type": "web_search"},
            {"type": "code_interpreter"},
            {"type": "web_extractor"}
        ],
    )

    # Uncomment the following line to view the intermediate output.
    # print(response.output)
    print(response.output_text)
import OpenAI from "openai";

    const openai = new OpenAI({
        apiKey: process.env.DASHSCOPE_API_KEY,
        // Replace {WorkspaceId} with your actual workspace ID. URLs vary by region.
        baseURL: "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1"
    });

    async function main() {
        const response = await openai.responses.create({
            model: "qwen3.8-max",
            input: "Find the Alibaba Cloud official website and extract key information from its homepage.",
            tools: [
                { type: "web_search" },
                { type: "code_interpreter" },
                { type: "web_extractor" }
            ]
        });

        for (const item of response.output) {
            if (item.type === "reasoning") {
                console.log("Model is thinking...");
            } else if (item.type === "web_search_call") {
                console.log(`Search query: ${item.action.query}`);
            } else if (item.type === "web_extractor_call") {
                console.log("Extracting web content...");
            } else if (item.type === "message") {
                console.log(`Response content: ${item.content[0].text}`);
            }
        }
    }

    main();
curl -X POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1/responses \
    -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
        "model": "qwen3.8-max",
        "input": "Find the Alibaba Cloud official website and extract key information from its homepage.",
        "tools": [
            {
                "type": "web_search"
            },
            {
                "type": "code_interpreter"
            },
            {
                "type": "web_extractor"
            }
        ]
    }'

Function calling

from openai import OpenAI
    import json
    import os
    import random

    # Initialize the client.
    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",
    )
    # Simulate a user question.
    USER_QUESTION = "What's the weather like in Beijing?"
    # Define the list of tools.
    tools = [
        {
            "type": "function",
            "name": "get_current_weather",
            "description": "Useful for getting the weather in a specific city.",
            "parameters": {
                "type": "object",
                "properties": {
                    "location": {
                        "type": "string",
                        "description": "The city or district, such as Beijing or Hangzhou.",
                    }
                },
                "required": ["location"],
            },
        }
    ]

    # Simulate the weather query tool.
    def get_current_weather(arguments):
        weather_conditions = ["sunny", "cloudy", "rainy"]
        random_weather = random.choice(weather_conditions)
        location = arguments["location"]
        return f"Today in {location} it is {random_weather}."

    # Wrap the model response function.
    def get_response(input_data):
        response = client.responses.create(
            model="qwen3.8-max",
            input=input_data,
            tools=tools,
        )
        return response

    # Maintain the conversation context.
    conversation = [{"role": "user", "content": USER_QUESTION}]

    response = get_response(conversation)
    function_calls = [item for item in response.output if item.type == "function_call"]
    # If no tool call is needed, output the content directly.
    if not function_calls:
        print(f"Final assistant response: {response.output_text}")
    else:
        # Enter the tool-calling loop.
        while function_calls:
            for fc in function_calls:
                func_name = fc.name
                arguments = json.loads(fc.arguments)
                print(f"Calling tool [{func_name}] with arguments: {arguments}")
                # Execute the tool.
                tool_result = get_current_weather(arguments)
                print(f"Tool returned: {tool_result}")
                # Append the tool call and its result to the context as a pair.
                conversation.append(
                    {
                        "type": "function_call",
                        "name": fc.name,
                        "arguments": fc.arguments,
                        "call_id": fc.call_id,
                    }
                )
                conversation.append(
                    {
                        "type": "function_call_output",
                        "call_id": fc.call_id,
                        "output": tool_result,
                    }
                )
            # Call the model again with the full context.
            response = get_response(conversation)
            function_calls = [
                item for item in response.output if item.type == "function_call"
            ]
        print(f"Final assistant response: {response.output_text}")
import OpenAI from "openai";

    // Initialize the client.
    const openai = new OpenAI({
      // If the environment variable is not set, replace with: apiKey: "sk-xxx"
      apiKey: process.env.DASHSCOPE_API_KEY,
      // Replace {WorkspaceId} with your actual workspace ID. URLs vary by region.
      baseURL:
        "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1",
    });

    // Define the list of tools.
    const tools = [
      {
        type: "function",
        name: "get_current_weather",
        description: "Useful for getting the weather in a specific city.",
        parameters: {
          type: "object",
          properties: {
            location: {
              type: "string",
              description: "The city or district, such as Beijing or Hangzhou.",
            },
          },
          required: ["location"],
        },
      },
    ];

    // Simulate the weather query tool.
    const getCurrentWeather = (args) => {
      const weatherConditions = ["sunny", "cloudy", "rainy"];
      const randomWeather =
        weatherConditions[Math.floor(Math.random() * weatherConditions.length)];
      const location = args.location;
      return `Today in ${location} it is ${randomWeather}.`;
    };

    // Wrap the model response function.
    const getResponse = async (inputData) => {
      const response = await openai.responses.create({
        model: "qwen3.8-max",
        input: inputData,
        tools: tools,
      });
      return response;
    };

    const main = async () => {
      const userQuestion = "What's the weather like in Beijing?";

      // Maintain the conversation context.
      const conversation = [{ role: "user", content: userQuestion }];

      let response = await getResponse(conversation);
      let functionCalls = response.output.filter(
        (item) => item.type === "function_call"
      );
      // If no tool call is needed, output the content directly.
      if (functionCalls.length === 0) {
        console.log(`Final assistant response: ${response.output_text}`);
      } else {
        // Enter the tool-calling loop.
        while (functionCalls.length > 0) {
          for (const fc of functionCalls) {
            const funcName = fc.name;
            const args = JSON.parse(fc.arguments);
            console.log(`Calling tool [${funcName}] with arguments:`, args);
            // Execute the tool.
            const toolResult = getCurrentWeather(args);
            console.log(`Tool returned: ${toolResult}`);
            // Append the tool call and its result to the context as a pair.
            conversation.push({
              type: "function_call",
              name: fc.name,
              arguments: fc.arguments,
              call_id: fc.call_id,
            });
            conversation.push({
              type: "function_call_output",
              call_id: fc.call_id,
              output: toolResult,
            });
          }
          // Call the model again with the full context.
          response = await getResponse(conversation);
          functionCalls = response.output.filter(
            (item) => item.type === "function_call"
          );
        }
        console.log(`Final assistant response: ${response.output_text}`);
      }
    };

    // Start the program.
    main().catch(console.error);

Compreensão de documentos

import os
from openai import OpenAI

client = OpenAI(
    # If you have not configured an environment variable, replace the next line with: api_key="sk-xxx"
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    base_url="https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1",
)

response = client.responses.create(
    model="qwen3.5-ocr",
    input=[
        {
            "role": "user",
            "content": [
                {
                    "type": "input_file",
                    "file_url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260616/qmycjl/1506.02640v5.pdf",
                },
                {
                    "type": "input_text",
                    "text": "Read all the text in the file.",
                },
            ],
        }
    ],
    extra_body={
        "ocr_options": {"task": "document_parsing"}
    },
)

print(response.output_text)
import OpenAI from 'openai';

const client = new OpenAI({
    // If you have not configured an environment variable, replace the next line with: apiKey: "sk-xxx"
    apiKey: process.env.DASHSCOPE_API_KEY,
    baseURL: "https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1",
});

async function main() {
    const response = await client.responses.create({
        model: "qwen3.5-ocr",
        input: [{
            role: "user",
            content: [{
                type: "input_file",
                file_url: "https://example.com/your-document.pdf"
            }]
        }],
        ocr_options: { task: "document_parsing" }
    });

    // Get the custom task result
    console.log(response.output[0].content[0].ocr_result);
}

main();
curl -X POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1/responses \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
    "model": "qwen3.5-ocr",
    "input": [
        {
            "role": "user",
            "content": [
                {
                    "type": "input_file",
                    "file_url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260616/qmycjl/1506.02640v5.pdf"
                },
                {
                    "type": "input_text",
                    "text": "Read all the text in the file."
                }
            ]
        }
    ],
    "ocr_options": {"task": "document_parsing"}
}'

Cache de sessão

import os
    from openai import OpenAI

    client = OpenAI(
        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",
        # Enable the session cache via default_headers.
        default_headers={"x-dashscope-session-cache": "enable"}
    )

    # Construct a long text over 1024 tokens to trigger cache creation.
    # If not, caching is triggered when the cumulative context exceeds 1024 tokens.
    long_context = "Artificial intelligence (AI) is a major branch of computer science, dedicated to researching and developing theories, methods, technologies, and application systems that can simulate, extend, and expand human intelligence." * 50

    # First turn
    response1 = client.responses.create(
        model="qwen3.8-max",
        input=long_context + "\n\nBased on this context, briefly introduce the Random Forest algorithm in machine learning.",
    )
    print(f"First response: {response1.output_text}")

    # Second turn: Link context using previous_response_id. The cache is handled automatically by the server.
    response2 = client.responses.create(
        model="qwen3.8-max",
        input="What are the main differences between it and GBDT?",
        extra_body={"previous_response_id": response1.id}
    )
    print(f"Second response: {response2.output_text}")

    # Check the cache hit status.
    usage = response2.usage
    print(f"Input tokens: {usage.input_tokens}")
    print(f"Cached tokens: {usage.prompt_tokens_details.cached_tokens}")
import OpenAI from "openai";

    const openai = new OpenAI({
        apiKey: process.env.DASHSCOPE_API_KEY,
        // Replace {WorkspaceId} with your actual workspace ID. URLs vary by region.
        baseURL: "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1",
        // Enable the session cache via defaultHeaders.
        defaultHeaders: {"x-dashscope-session-cache": "enable"}
    });

    // Construct a long text over 1024 tokens to trigger cache creation.
    // If not, caching is triggered when the cumulative context exceeds 1024 tokens.
    const longContext = "Artificial intelligence (AI) is a major branch of computer science, dedicated to researching and developing theories, methods, technologies, and application systems that can simulate, extend, and expand human intelligence.".repeat(50);

    async function main() {
        // First turn
        const response1 = await openai.responses.create({
            model: "qwen3.8-max",
            input: longContext + "\n\nBased on this context, briefly introduce the Random Forest algorithm in machine learning, including its basic principles and applications."
        });
        console.log(`First response: ${response1.output_text}`);

        // Second turn: Link context using previous_response_id. The cache is handled automatically by the server.
        const response2 = await openai.responses.create({
            model: "qwen3.8-max",
            input: "What are the main differences between it and GBDT?",
            extra_body: { previous_response_id: response1.id }
        } as any);
        console.log(`Second response: ${response2.output_text}`);

        // Check the cache hit status.
        console.log(`Input tokens: ${response2.usage.input_tokens}`);
        console.log(`Cached tokens: ${response2.usage.prompt_tokens_details.cached_tokens}`);
    }

    main();
# First turn
    # Repeat the long text 50 times to ensure it exceeds 1024 tokens and triggers cache creation.
    curl -X POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1/responses \
    -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
    -H "Content-Type: application/json" \
    -H "x-dashscope-session-cache: enable" \
    -d '{
        "model": "qwen3.8-max",
        "input": "Artificial intelligence (AI) is a major branch of computer science..."
    }'

    # Second turn - use the ID from the previous response as previous_response_id.
    curl -X POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1/responses \
    -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
    -H "Content-Type: application/json" \
    -H "x-dashscope-session-cache: enable" \
    -d '{
        "model": "qwen3.8-max",
        "input": "What are the main differences between it and GBDT?",
        "previous_response_id": ""
    }'

model string (obrigatório)

O ID do modelo a ser utilizado.

Modelos suportados

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.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.1-flash-1017, deepseek-v4-pro, deepseek-v4-pro-0813, deepseek-v4-flash-0731, glm-5.2, kimi-k3.1-pro, kimi-k3

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 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.

Tipos de itens do array

EasyInputMessage object

Um objeto com um role para o autor da mensagem e content para o conteúdo da mensagem.

Propriedades

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. Os seguintes formatos são suportados:

  • string: Entrada de texto simples.
  • array: Um array de conteúdo com um ou mais itens de conteúdo, que podem misturar tipos diferentes. Quando o role é system ou developer, o tipo de elemento do array é input_text. 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.

Tipos de itens do array

Um dos seguintes tipos:

input_text { type, text }

Entrada de texto.

Propriedades

type string (obrigatório)

Fixo como input_text.

text string (obrigatório)

O conteúdo de texto enviado ao modelo.

input_image { type, image_url }

Entrada de imagem, apenas função user.

Propriedades

type string (obrigatório)

Fixo como input_image.

image_url string (obrigatório)

A URL pública da imagem ou dados codificados em Base64. Para Base64, forneça um Data URI completo, por exemplo: data:image/png;base64,iVBORw0KGgoAAAANSUhEUg....

input_file { type, file_url }

Entrada de arquivo, apenas função user. Atualmente suportado por qwen3.8-flash, qwen3.8-max e qwen3.5-ocr.

Propriedades

type string (obrigatório)

Fixo como input_file.

file_url string (obrigatório)

A URL pública do arquivo PDF. O arquivo pode ter até 100 MB.

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.

output_text { type, text }

Resposta do assistente, apenas função assistant.

Propriedades

type string (obrigatório)

Fixo como output_text.

text string (obrigatório)

O conteúdo de texto da resposta do assistente.

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.

Propriedades

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.

Propriedades

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.

Propriedades

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.

Propriedades

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.

Propriedades

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.

Propriedades

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.

Propriedades

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.

Propriedades

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.

Propriedades

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 é false

Ativa a saída em stream. Se definido como true, o modelo transmite a resposta em tempo real.

store boolean (opcional) O padrão é true

Especifica 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.

kimi-k3.1-pro (implantado no Alibaba Cloud Model Studio) suporta as ferramentas integradas web_search, web_extractor e code_interpreter em Pequim, Singapura, EUA (Virgínia), Alemanha (Frankfurt), Japão (Tóquio) e China (Hong Kong).

deepseek-v4.1-flash-1017 oferece suporte às três ferramentas integradas web_search, web_extractor e code_interpreter.

Para obter os melhores resultados, ative as ferramentas code_interpreter, web_search e web_extractor.

Propriedades

Pesquisa na web

Pesquisa informações atualizadas na internet. Documentação relacionada: Web Search

Propriedades

type string (obrigatório)

Valor fixo: web_search.

Exemplo: [{"type": "web_search"}]

Extrator da web

Acessa e extrai conteúdo de páginas da web. Deve ser usado junto com a ferramenta web_search. Documentação relacionada: Web Extraction

Propriedades

type string (obrigatório)

Valor fixo: web_extractor.

Exemplo: [{"type": "web_search"}, {"type": "web_extractor"}]

Interpretador de código

Executa código em um ambiente isolado para realizar tarefas como análise de dados. Documentação relacionada: Code Interpreter

Propriedades

type string (obrigatório)

Valor fixo: code_interpreter.

Exemplo: [{"type": "code_interpreter"}]

Pesquisa de imagens na web

Busca imagens com base em uma descrição textual. Documentação relacionada: Text-to-Image Search

Propriedades

type string (obrigatório)

Valor fixo: web_search_image.

Exemplo: [{"type": "web_search_image"}]

Pesquisa por imagem

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 string (obrigatório)

Valor fixo: image_search.

Exemplo: [{"type": "image_search"}]

Pesquisa em arquivos

Realiza recuperação de conhecimento pesquisando em uma base de conhecimento especificada. Documentação relacionada: Knowledge Retrieval

Propriedades

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 MCP

Chama um service externo por meio do Model Context Protocol (MCP). Documentação relacionada: MCP

Propriedades

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 personalizadafunction

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 function_call. Documentação relacionada: Function calling

Propriedades

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 é auto

Controla 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 object

Restringe o modelo a um conjunto específico de ferramentas para seleção e chamada.

Propriedades

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.

parallel_tool_calls boolean (opcional) O padrão é true

Define se a chamada paralela de ferramentas deve ser ativada. Para mais informações, consulte Chamada paralela de ferramentas.

O kimi-k3 não suporta controlar o paralelismo das chamadas de ferramentas por meio deste parâmetro. Defini-lo como false não garante chamadas sequenciais, e o modelo ainda pode retornar vários itens function_call em uma mesma resposta. Processe as chamadas de ferramentas conforme retornadas.

Valores válidos:

  • true: Ativar
  • false: Desativar

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.

Para kimi-k3.1-pro (implantado no Alibaba Cloud Model Studio), reasoning.effort tem o valor padrão max. Os valores suportados são max (raciocínio profundo), high (raciocínio aprimorado), medium (raciocínio moderado) e low (raciocínio leve). Recomendamos manter a configuração padrão de pensamento, pois desativá-lo afeta significativamente a qualidade da saída.

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 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.

text object (opcional)

Configuração da saída de texto do modelo. A saída pode ser texto simples ou dados JSON estruturados.

Propriedades

format object (opcional)

O formato que o modelo deve produzir. Valor padrão: {"type": "text"}.

Um dos seguintes tipos:

ResponseFormatText { type }

Formato padrão. Produz uma resposta em texto.

Propriedades

type string (obrigatório)

Fixo como text.

ResponseFormatTextJSONSchemaConfig { type, json_schema }

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 string (obrigatório)

Fixo como json_schema.

json_schema object (obrigatório)

A configuração do JSON Schema.

Propriedades

name string (obrigatório)

O nome do schema.

schema object (obrigatório)

O objeto JSON Schema que descreve a estrutura da saída. Use properties para definir a estrutura dos campos, required para listar os campos obrigatórios e additionalProperties para controlar se campos não definidos no schema podem ser retornados (recomendamos definir como false para que apenas os campos definidos sejam retornados). Tipos de dados compatíveis: string, number, integer, boolean, object, array e enum. Para mais informações, consulte Guia de configuração.

strict boolean (opcional)

Indica se a estrutura definida por schema deve ser seguida estritamente. Recomendamos definir este parâmetro como true.

ResponseFormatJSONObject { type }

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 string (obrigatório)

Fixo como json_object.

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 string

Identificador ú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 integer

Timestamp Unix (em segundos) desta solicitação.

object string

Tipo do objeto, sempre definido como response.

status string

Status 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 string

ID do modelo utilizado para gerar a resposta.

output array

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 string

Tipo 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 string

Identificador único do item de saída. Todos os tipos de itens de saída contêm este campo.

role string

A função da mensagem é sempre assistant. Este parâmetro está presente apenas quando type é message.

status string

Status 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 string

Nome 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 string

Parâ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 string

ID ú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 array

Array com o conteúdo da mensagem. Este parâmetro está presente apenas se type estiver definido como message.

Propriedades dos elementos do array

type string

Tipo de conteúdo. O valor é fixo como output_text.

text string

Contúdo de texto gerado pelo modelo.

annotations array

Array de anotações de texto. Geralmente é um array vazio.

summary array

Array 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 object

Informações sobre a ação de pesquisa. Este parâmetro está presente apenas quando type é web_search_call.

Propriedades

query string

Palavras-chave da consulta de pesquisa.

type string

Tipo de pesquisa. O valor é sempre search.

sources array

Lista de fontes de pesquisa. Cada elemento contém os campos type e url.

code string

Código gerado e executado pelo modelo. Existe apenas quando type é code_interpreter_call.

outputs array

Array 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 string

Identificador 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 string

Descrição das informações a serem extraídas da página web. Disponível apenas quando type é web_extractor_call.

output string

Saí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 array

Lista de URLs das páginas web extraídas. Disponível apenas quando type é web_extractor_call.

server_label string

Rótulo do service MCP. Aparece apenas quando type é mcp_call. Indica qual service MCP foi utilizado na chamada.

queries array

Lista 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 array

Array de resultados de pesquisa da base de conhecimento. Presente apenas quando type é file_search_call.

Propriedades dos elementos do array

file_id string

ID do arquivo do documento correspondente.

filename string

Nome do arquivo do documento correspondente.

score float

Pontuação de relevância da correspondência. O valor varia de 0 a 1. Um valor maior indica maior relevância.

text string

Trecho de conteúdo do documento correspondente.

usage object

Informações sobre o consumo de tokens nesta solicitação.

Propriedades

input_tokens integer

Número de tokens na entrada. Additional Notes

output_tokens integer

Quantidade de tokens na saída do modelo.

total_tokens integer

Total de tokens consumidos, correspondente à soma de input_tokens e output_tokens.

input_tokens_details object

Classificação detalhada dos tokens de entrada.

Propriedades

cached_tokens integer

Número de tokens que atingiram o cache. Para mais informações, consulte context caching.

output_tokens_details object

Detalhamento dos tokens de saída.

Propriedades

reasoning_tokens integer

Quantidade de tokens de raciocínio.

x_details array

Array com detalhes de faturamento da solicitação. Fornece um detalhamento mais granular dos tokens multimodais do que o campo usage de nível superior.

Propriedades

input_tokens integer

Número de tokens na entrada. Additional Notes

output_tokens integer

Quantidade de tokens na saída do modelo.

total_tokens integer

Total de tokens consumidos, correspondente à soma de input_tokens e output_tokens.

x_billing_type string

Valor fixo definido como response_api.

image_tokens integer

Nú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 object

Detalhamento 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.

Propriedades

text_tokens integer

Quantidade de tokens para entrada de texto.

image_tokens integer

Número de tokens para entrada de imagem.

output_tokens_details object

Detalhamento 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.

Propriedades

reasoning_tokens integer

Quantidade de tokens utilizados no processo de raciocínio.

text_tokens integer

Número de tokens para saída de texto. Retornado para entradas multimodais.

plugins object

Estatí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.

Propriedades

web_search object

Estatísticas das chamadas de pesquisa web.

Propriedades

count integer

Número de vezes que a pesquisa web foi chamada nesta resposta.

prompt_tokens_details object

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 integer

Quantidade de tokens que atingiram o cache.

cache_creation_input_tokens integer

Número de tokens usados para criar um novo cache nesta solicitação.

cache_creation object

Detalhes sobre a criação de cache.

Propriedades

ephemeral_5m_input_tokens integer

Tokens utilizados para criar um novo cache efêmero de 5 minutos.

cache_type string

Tipo de cache. Valor fixo definido como ephemeral.

x_tools object

Estatísticas de uso de ferramentas. Contém o número de chamadas de cada ferramenta integrada.

Exemplo: {"web_search": {"count": 1}}

error object

Um objeto de erro é retornado quando o modelo falha ao gerar uma resposta. Caso contrário, o valor é null.

tools array

Replica 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 string

Repete 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"}
id:1
event:response.created
:HTTP_STATUS/200
data:{"sequence_number":0,"type":"response.created","response":{"output":[],"parallel_tool_calls":false,"created_at":1769435906,"tool_choice":"auto","model":"","id":"863df8d9-cb29-4239-a54f-3e15a2427xxx","tools":[],"object":"response","status":"queued"}}

id:2
event:response.in_progress
:HTTP_STATUS/200
data:{"sequence_number":1,"type":"response.in_progress","response":{"output":[],"parallel_tool_calls":false,"created_at":1769435906,"tool_choice":"auto","model":"","id":"863df8d9-cb29-4239-a54f-3e15a2427xxx","tools":[],"object":"response","status":"in_progress"}}

id:3
event:response.output_item.added
:HTTP_STATUS/200
data:{"sequence_number":2,"item":{"summary":[],"type":"reasoning","id":"msg_5bd0c6df-19b8-4a04-bc00-8042a224exxx"},"output_index":0,"type":"response.output_item.added"}

id:4
event:response.reasoning_text.delta
:HTTP_STATUS/200
data:{"delta":"The user wants me to:\n1. Search for the Alibaba Cloud official website.\n2. Extract key information from the homepage.\n\nI need to first search for the URL of the Alibaba Cloud official website, and then use the web_extractor tool to access the website and extract key information.","sequence_number":3,"output_index":0,"type":"response.reasoning_text.delta","item_id":"msg_5bd0c6df-19b8-4a04-bc00-8042a224exxx"}

id:14
event:response.reasoning_text.done
:HTTP_STATUS/200
data:{"sequence_number":13,"text":"The user wants me to:\n1. Search for the Alibaba Cloud official website.\n2. Extract key information from the homepage.\n\nI need to first search for the URL of the Alibaba Cloud official website, and then use the web_extractor tool to access the website and extract key information.","output_index":0,"type":"response.reasoning_text.done","item_id":"msg_5bd0c6df-19b8-4a04-bc00-8042a224exxx"}

id:15
event:response.output_item.done
:HTTP_STATUS/200
data:{"sequence_number":14,"item":{"summary":[{"type":"summary_text","text":"The user wants me to:\n1. Search for the Alibaba Cloud official website.\n2. Extract key information from the homepage.\n\nI need to first search for the URL of the Alibaba Cloud official website, and then use the web_extractor tool to access the website and extract key information."}],"type":"reasoning","id":"msg_5bd0c6df-19b8-4a04-bc00-8042a224exxx"},"output_index":1,"type":"response.output_item.done"}

id:16
event:response.output_item.added
:HTTP_STATUS/200
data:{"sequence_number":15,"item":{"action":{"type":"search","query":"Web search"},"id":"msg_a8a686b1-0a57-40e1-bb55-049a89cd4xxx","type":"web_search_call","status":"in_progress"},"output_index":1,"type":"response.output_item.added"}

id:17
event:response.web_search_call.in_progress
:HTTP_STATUS/200
data:{"sequence_number":16,"output_index":1,"type":"response.web_search_call.in_progress","item_id":"msg_a8a686b1-0a57-40e1-bb55-049a89cd4xxx"}

id:19
event:response.web_search_call.completed
:HTTP_STATUS/200
data:{"sequence_number":18,"output_index":1,"type":"response.web_search_call.completed","item_id":"msg_a8a686b1-0a57-40e1-bb55-049a89cd4xxx"}

id:20
event:response.output_item.done
:HTTP_STATUS/200
data:{"sequence_number":19,"item":{"action":{"sources":[{"type":"url","url":"https://cn.aliyun.com/"},{"type":"url","url":"https://www.aliyun.com/"}],"type":"search","query":"Web search"},"id":"msg_a8a686b1-0a57-40e1-bb55-049a89cd4xxx","type":"web_search_call","status":"completed"},"output_index":1,"type":"response.output_item.done"}

id:33
event:response.output_item.added
:HTTP_STATUS/200
data:{"sequence_number":32,"item":{"urls":["https://cn.aliyun.com/"],"goal":"Extract key information from the Alibaba Cloud homepage, including: company positioning/overview, core products and services, main business segments, key features/solutions, latest news/events, free trial/discount information, and navigation menu structure.","id":"msg_8c2cf651-48a5-460c-aa7a-bea5b09b4xxx","type":"web_extractor_call","status":"in_progress"},"output_index":3,"type":"response.output_item.added"}

id:34
event:response.output_item.done
:HTTP_STATUS/200
data:{"sequence_number":33,"item":{"output":"The useful information in https://cn.aliyun.com/ for user goal 'Extract key information from the Alibaba Cloud homepage, including: company positioning/overview, core products and services, main business segments, key features/solutions, latest news/events, free trial/discount information, and navigation menu structure' is as follows: \n\nEvidence in page: \n## Tongyi large model, the first choice for enterprises in the AI era\n\n## A complete product system, building a cloud for enterprise technological innovation\n\nAll cloud products## Making AI accessible through the synergistic development of large models and cloud computing\n\nAll AI solutions\n\nSummary: \nAlibaba Cloud positions itself as a leading enterprise AI solution provider centered around the Tongyi large model...","urls":["https://cn.aliyun.com/"],"goal":"Extract key information from the Alibaba Cloud homepage, including: company positioning/overview, core products and services, main business segments, key features/solutions, latest news/events, free trial/discount information, and navigation menu structure.","id":"msg_8c2cf651-48a5-460c-aa7a-bea5b09b4xxx","type":"web_extractor_call","status":"completed"},"output_index":3,"type":"response.output_item.done"}

id:50
event:response.output_item.added
:HTTP_STATUS/200
data:{"sequence_number":50,"item":{"content":[{"type":"text","text":""}],"type":"message","id":"msg_final","role":"assistant"},"output_index":5,"type":"response.output_item.added"}

id:51
event:response.output_text.delta
:HTTP_STATUS/200
data:{"delta":"I have found the Alibaba Cloud website and extracted the key information from its homepage:\n\n","sequence_number":51,"output_index":5,"type":"response.output_text.delta"}

id:60
event:response.completed
:HTTP_STATUS/200
data:{"type":"response.completed","response":{"id":"863df8d9-cb29-4239-a54f-3e15a2427xxx","status":"completed","usage":{"input_tokens":45,"output_tokens":320,"total_tokens":365}}}
// 1. response.created: The response is created.
id:1
event:response.created
data:{"sequence_number":0,"type":"response.created","response":{"output":[],"status":"queued",...}}

// 2. response.in_progress: The response is being processed.
id:2
event:response.in_progress
data:{"sequence_number":1,"type":"response.in_progress","response":{"status":"in_progress",...}}

// 3. response.output_item.added: Reasoning starts.
id:3
event:response.output_item.added
data:{"sequence_number":2,"item":{"summary":[],"type":"reasoning","id":"msg_xxx"},"output_index":0,"type":"response.output_item.added"}

// 4. response.reasoning_text.delta: Reasoning summary delta.
id:4
event:response.reasoning_text.delta
data:{"delta":"The user wants to find a picture of a cat. I need to use the web_search_image tool to search...","sequence_number":3,"output_index":0,"type":"response.reasoning_text.delta","item_id":"msg_xxx"}

// 5. response.reasoning_text.done: Reasoning summary is complete.
id:10
event:response.reasoning_text.done
data:{"sequence_number":9,"text":"The user wants to find a picture of a cat. I need to use the web_search_image tool to search for cat pictures.","output_index":0,"type":"response.reasoning_text.done","item_id":"msg_xxx"}

// 6. response.output_item.done: The reasoning item is complete.
id:11
event:response.output_item.done
data:{"sequence_number":10,"item":{"summary":[{"type":"summary_text","text":"..."}],"type":"reasoning","id":"msg_xxx"},"output_index":0,"type":"response.output_item.done"}

// 7. response.output_item.added: Text-to-image search tool call starts (status: in_progress; includes name and arguments).
id:12
event:response.output_item.added
data:{"sequence_number":11,"item":{"name":"web_search_image","arguments":"{\"queries\": [\"cat pictures\", \"cute cat\"]}","id":"msg_xxx","type":"web_search_image_call","status":"in_progress"},"output_index":1,"type":"response.output_item.added"}

// 8. response.output_item.done: Text-to-image search tool call is complete (includes the full 'output' search results).
id:13
event:response.output_item.done
data:{"sequence_number":12,"item":{"name":"web_search_image","output":"[{\"title\": \"Cute little cat...\", \"url\": \"https://example.com/cat.jpg\", \"index\": 1}, ...]","arguments":"{\"queries\": [\"cat pictures\", \"cute cat\"]}","id":"msg_xxx","type":"web_search_image_call","status":"completed"},"output_index":1,"type":"response.output_item.done"}

// 9-12. Subsequent reasoning and message output events follow, similar to the basic call flow.
// response.output_item.added (reasoning) → reasoning_summary_text.delta/done → response.output_item.done (reasoning)
// response.output_item.added (message) → response.content_part.added → response.output_text.delta → response.output_text.done → response.content_part.done → response.output_item.done (message)

// 13. response.completed: The response is complete.
id:118
event:response.completed
data:{"sequence_number":117,"type":"response.completed","response":{"output":[...],"status":"completed","usage":{"input_tokens":7895,"output_tokens":318,"total_tokens":8213,"x_tools":{"web_search_image":{"count":1}}}}}
// 1-6. The reasoning phase is the same as in the text-to-image search flow.

// 7. response.output_item.added: Image-to-image search tool call starts.
// Note: arguments includes img_idx (image index) and bbox (bounding box).
id:29
event:response.output_item.added
data:{"sequence_number":29,"item":{"name":"image_search","arguments":"{\"img_idx\": 0, \"bbox\": [0, 0, 1000, 1000]}","id":"msg_xxx","type":"image_search_call","status":"in_progress"},"output_index":1,"type":"response.output_item.added"}

// 8. response.output_item.done: Image-to-image search tool call is complete.
id:30
event:response.output_item.done
data:{"sequence_number":30,"item":{"name":"image_search","output":"[{\"title\": \"Ink wash mountain background...\", \"url\": \"https://example.com/landscape.jpg\", \"index\": 1}, ...]","arguments":"{\"img_idx\": 0, \"bbox\": [0, 0, 1000, 1000]}","id":"msg_xxx","type":"image_search_call","status":"completed"},"output_index":1,"type":"response.output_item.done"}

// 9-12. Second round of reasoning + final message output (same as basic call).

// 13. response.completed
id:408
event:response.completed
data:{"sequence_number":407,"type":"response.completed","response":{"output":[...],"status":"completed","usage":{"input_tokens":8371,"output_tokens":417,"total_tokens":8788,"x_tools":{"image_search":{"count":1}}}}}
// 1-6. Reasoning phase (same as other tools).

// 7. response.mcp_call_arguments.delta: MCP arguments delta (MCP-specific event).
id:27
event:response.mcp_call_arguments.delta
data:{"delta":"{\"city\": \"Beijing\"}","sequence_number":26,"output_index":1,"type":"response.mcp_call_arguments.delta","item_id":"msg_xxx"}

// 8. response.mcp_call_arguments.done: MCP arguments are complete (MCP-specific event).
id:28
event:response.mcp_call_arguments.done
data:{"sequence_number":27,"arguments":"{\"city\": \"Beijing\"}","output_index":1,"type":"response.mcp_call_arguments.done","item_id":"msg_xxx"}

// 9. response.output_item.added: MCP tool call starts (includes name, server_label, arguments).
id:29
event:response.output_item.added
data:{"sequence_number":28,"item":{"name":"amap-maps-maps_weather","server_label":"MCP Server","arguments":"{\"city\": \"Beijing\"}","id":"msg_xxx","type":"mcp_call","status":"in_progress"},"output_index":1,"type":"response.output_item.added"}

// 10. response.mcp_call.completed: MCP call is complete (MCP-specific event).
id:30
event:response.mcp_call.completed
data:{"sequence_number":29,"output_index":1,"type":"response.mcp_call.completed","item_id":"msg_xxx"}

// 11. response.output_item.done: The MCP output item is complete (includes the full 'output').
id:31
event:response.output_item.done
data:{"sequence_number":30,"item":{"output":"{\"city\":\"Beijing\",\"forecasts\":[...]}","name":"amap-maps-maps_weather","server_label":"MCP Server","arguments":"{\"city\": \"Beijing\"}","id":"msg_xxx","type":"mcp_call","status":"completed"},"output_index":1,"type":"response.output_item.done"}

// 12-15. Second round of reasoning + final message output.

// 16. response.completed
id:172
event:response.completed
data:{"sequence_number":171,"type":"response.completed","response":{"output":[...],"status":"completed","usage":{"input_tokens":5019,"output_tokens":539,"total_tokens":5558}}}
// 1-6. Reasoning phase (same as other tools).

// 7. response.output_item.added: Knowledge base search starts (includes queries, no results).
id:19
event:response.output_item.added
data:{"sequence_number":18,"item":{"id":"msg_xxx","type":"file_search_call","queries":["Alibaba Cloud Model Studio X1 phone","Alibaba Cloud Model Studio X1 phone","Model Studio X1"],"status":"in_progress"},"output_index":1,"type":"response.output_item.added"}

// 8. response.file_search_call.in_progress: Search is in progress (file_search-specific event).
id:20
event:response.file_search_call.in_progress
data:{"sequence_number":19,"output_index":1,"type":"response.file_search_call.in_progress","item_id":"msg_xxx"}

// 9. response.file_search_call.searching: Searching (file_search-specific event).
id:21
event:response.file_search_call.searching
data:{"sequence_number":20,"output_index":1,"type":"response.file_search_call.searching","item_id":"msg_xxx"}

// 10. response.file_search_call.completed: Search is complete (file_search-specific event).
id:22
event:response.file_search_call.completed
data:{"sequence_number":21,"output_index":1,"type":"response.file_search_call.completed","item_id":"msg_xxx"}

// 11. response.output_item.done: Provides the complete output item, including queries and results.
id:23
event:response.output_item.done
data:{"sequence_number":22,"item":{"id":"msg_xxx","type":"file_search_call","queries":["Alibaba Cloud Model Studio X1 phone","Alibaba Cloud Model Studio X1 phone","Model Studio X1"],"results":[{"score":0.7519,"filename":"Alibaba Cloud Model Studio Series Phone Product Introduction","text":"Alibaba Cloud Model Studio X1 — Enjoy the ultimate visual experience...","file_id":"file_xxx"}],"status":"completed"},"output_index":1,"type":"response.output_item.done"}

// 12-15. Second round of reasoning + final message output.

// 16. response.completed
id:146
event:response.completed
data:{"sequence_number":145,"type":"response.completed","response":{"output":[...],"status":"completed","usage":{"input_tokens":1576,"output_tokens":722,"total_tokens":2298,"x_tools":{"file_search":{"count":1}}}}}

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 string

Identificador 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 integer

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 object

Objeto 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 object

Objeto 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.

Propriedades

id string

Identificador exclusivo para o item de saída (por exemplo, msg_xxx).

type string

Tipo 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 string

Função da mensagem, que é sempre assistant. Presente apenas quando type é message.

status string

Status de geração. Em um evento added, o status é in_progress; em um evento done, é completed.

content array

Array 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 object

Objeto de parte de conteúdo. Presente nos eventos response.content_part.added e response.content_part.done.

Propriedades

type string

Tipo da parte de conteúdo, que é sempre output_text.

text string

Conteúdo de texto. É uma string vazia no evento added e o texto completo no evento done.

annotations array

Array de anotações de texto. Geralmente é um array vazio.

logprobs object | null

Probabilidades logarítmicas de tokens. Atualmente, este campo sempre retorna null.

delta string

Segmento 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 string

Conteú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 string

Identificador 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.