Partilhar via

Azure OpenAI Answers API

A API de Respostas é uma nova API "stateful" do Azure OpenAI. Ele reúne os melhores recursos da API de conclusão de bate-papo e assistentes em uma experiência unificada. A API de respostas também adiciona suporte para o novo computer-use-preview modelo que alimenta a capacidade de uso do computador .

API de Respostas

Suporte de API

Disponibilidade de Regiões

A API de respostas está atualmente disponível nas seguintes regiões:

  • australiaeast
  • Brasil Sul
  • CanadáCentral
  • Canadá Leste
  • eastus
  • eastus2
  • francecentral
  • Alemanha Oeste Central
  • ItáliaNorte
  • japaneast
  • Coreia Central
  • northcentralus
  • norwayeast
  • polandcentral
  • southafricanorth
  • southcentralus
  • southeastasia
  • southindia
  • spaincentral
  • swedencentral
  • switzerlandnorth
  • uaenorth
  • uksouth
  • westus
  • westus3

Suporte ao modelo

  • gpt-5.1-codex-max (Versão: 2025-12-04)
  • gpt-5.1 (Versão: 2025-11-13)
  • gpt-5.1-chat (Versão: 2025-11-13)
  • gpt-5.1-codex (Versão: 2025-11-13)
  • gpt-5.1-codex-mini (Versão: 2025-11-13)
  • gpt-5-pro (Versão: 2025-10-06)
  • gpt-5-codex (Versão: 2025-09-11)
  • gpt-5 (Versão: 2025-08-07)
  • gpt-5-mini (Versão: 2025-08-07)
  • gpt-5-nano (Versão: 2025-08-07)
  • gpt-5-chat (Versão: 2025-08-07)
  • gpt-5-chat (Versão: 2025-10-03)
  • gpt-5-codex (Versão: 2025-09-15)
  • gpt-4o (Versões: 2024-11-20, 2024-08-06, 2024-05-13)
  • gpt-4o-mini (Versão: 2024-07-18)
  • computer-use-preview
  • gpt-4.1 (Versão: 2025-04-14)
  • gpt-4.1-nano (Versão: 2025-04-14)
  • gpt-4.1-mini (Versão: 2025-04-14)
  • gpt-image-1 (Versão: 2025-04-15)
  • gpt-image-1-mini (Versão: 2025-10-06)
  • o1 (Versão: 2024-12-17)
  • o3-mini (Versão: 2025-01-31)
  • o3 (Versão: 2025-04-16)
  • o4-mini (Versão: 2025-04-16)

Nem todos os modelos estão disponíveis nas regiões suportadas pela API de respostas. Verifique a disponibilidade da região do modelo na página de modelos.

Note

Não suportado atualmente:

  • Compactação com /responses/compact
  • Geração de imagem usando edições múltiplas e streaming.
  • As imagens não podem ser carregadas como um arquivo e, em seguida, referenciadas como entrada.

Há um problema conhecido com o seguinte:

  • O PDF como arquivo de entrada agora é suportado, mas a configuração da finalidade de upload do arquivo como user_data não é suportada no momento.
  • Problemas de desempenho quando o modo em segundo plano é usado com streaming. Espera-se que a questão seja resolvida em breve.

Documentação de referência

Introdução à API de respostas

Para acessar os comandos da API de respostas, você precisa atualizar sua versão da biblioteca OpenAI.

pip install --upgrade openai

Gerar uma resposta de texto

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.getenv("AZURE_OPENAI_API_KEY"),
    base_url="https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/",
)

response = client.responses.create(   
  model="gpt-4.1-nano", # Replace with your model deployment name 
  input="This is a test.",
)

print(response.model_dump_json(indent=2))

Important

Use chaves de API com cuidado. Não inclua a chave da API diretamente no seu código e nunca a publique publicamente. Se você usar uma chave de API, armazene-a com segurança no Cofre de Chaves do Azure. Para obter mais informações sobre como usar chaves de API com segurança em seus aplicativos, consulte Chaves de API com o Cofre de Chaves do Azure.

Para obter mais informações sobre segurança de serviços de IA, consulte Autenticar solicitações para serviços de IA do Azure.

Recuperar uma resposta

Para recuperar uma resposta de uma chamada anterior para a API de respostas.

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.getenv("AZURE_OPENAI_API_KEY"),
    base_url="https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/",
)

response = client.responses.retrieve("resp_67cb61fa3a448190bcf2c42d96f0d1a8")

Important

Use chaves de API com cuidado. Não inclua a chave da API diretamente no seu código e nunca a publique publicamente. Se você usar uma chave de API, armazene-a com segurança no Cofre de Chaves do Azure. Para obter mais informações sobre como usar chaves de API com segurança em seus aplicativos, consulte Chaves de API com o Cofre de Chaves do Azure.

Para obter mais informações sobre segurança de serviços de IA, consulte Autenticar solicitações para serviços de IA do Azure.

Excluir resposta

Por padrão, os dados de resposta são retidos por 30 dias. Para excluir uma resposta, você pode usar response.delete ("{response_id}")

import os
from openai import OpenAI

client = OpenAI(  
  base_url = "https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/",
  api_key=os.getenv("AZURE_OPENAI_API_KEY")  
)

response = client.responses.delete("resp_67cb61fa3a448190bcf2c42d96f0d1a8")

print(response)

Encadeamento de respostas

Você pode encadear respostas juntas passando a response.id resposta anterior para o previous_response_id parâmetro.

import os
from openai import OpenAI

client = OpenAI(  
  base_url = "https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/",
  api_key=os.getenv("AZURE_OPENAI_API_KEY")  
)

response = client.responses.create(
    model="gpt-4o",  # replace with your model deployment name
    input="Define and explain the concept of catastrophic forgetting?"
)

second_response = client.responses.create(
    model="gpt-4o",  # replace with your model deployment name
    previous_response_id=response.id,
    input=[{"role": "user", "content": "Explain this at a level that could be understood by a college freshman"}]
)
print(second_response.model_dump_json(indent=2))

Observe na saída que, embora nunca tenhamos compartilhado a primeira pergunta de entrada com a second_response chamada de API, ao passar o previous_response_id, o modelo tem o contexto completo da pergunta e resposta anteriores para responder à nova pergunta.

Output:

{
  "id": "resp_67cbc9705fc08190bbe455c5ba3d6daf",
  "created_at": 1741408624.0,
  "error": null,
  "incomplete_details": null,
  "instructions": null,
  "metadata": {},
  "model": "gpt-4o-2024-08-06",
  "object": "response",
  "output": [
    {
      "id": "msg_67cbc970fd0881908353a4298996b3f6",
      "content": [
        {
          "annotations": [],
          "text": "Sure! Imagine you are studying for exams in different subjects like math, history, and biology. You spend a lot of time studying math first and get really good at it. But then, you switch to studying history. If you spend all your time and focus on history, you might forget some of the math concepts you learned earlier because your brain fills up with all the new history facts. \n\nIn the world of artificial intelligence (AI) and machine learning, a similar thing can happen with computers. We use special programs called neural networks to help computers learn things, sort of like how our brain works. But when a neural network learns a new task, it can forget what it learned before. This is what we call \"catastrophic forgetting.\"\n\nSo, if a neural network learned how to recognize cats in pictures, and then you teach it how to recognize dogs, it might get really good at recognizing dogs but suddenly become worse at recognizing cats. This happens because the process of learning new information can overwrite or mess with the old information in its \"memory.\"\n\nScientists and engineers are working on ways to help computers remember everything they learn, even as they keep learning new things, just like students have to remember math, history, and biology all at the same time for their exams. They use different techniques to make sure the neural network doesn’t forget the important stuff it learned before, even when it gets new information.",
          "type": "output_text"
        }
      ],
      "role": "assistant",
      "status": null,
      "type": "message"
    }
  ],
  "parallel_tool_calls": null,
  "temperature": 1.0,
  "tool_choice": null,
  "tools": [],
  "top_p": 1.0,
  "max_output_tokens": null,
  "previous_response_id": "resp_67cbc96babbc8190b0f69aedc655f173",
  "reasoning": null,
  "status": "completed",
  "text": null,
  "truncation": null,
  "usage": {
    "input_tokens": 405,
    "output_tokens": 285,
    "output_tokens_details": {
      "reasoning_tokens": 0
    },
    "total_tokens": 690
  },
  "user": null,
  "reasoning_effort": null
}

Encadeamento manual de respostas

Como alternativa, você pode encadear manualmente as respostas usando o método abaixo:

import os
from openai import OpenAI

client = OpenAI(  
  base_url = "https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/",
  api_key=os.getenv("AZURE_OPENAI_API_KEY")  
)


inputs = [{"type": "message", "role": "user", "content": "Define and explain the concept of catastrophic forgetting?"}] 
  
response = client.responses.create(  
    model="gpt-4o",  # replace with your model deployment name  
    input=inputs  
)  
  
inputs += response.output

inputs.append({"role": "user", "type": "message", "content": "Explain this at a level that could be understood by a college freshman"}) 
               

second_response = client.responses.create(  
    model="gpt-4o",  
    input=inputs
)  
      
print(second_response.model_dump_json(indent=2))

Streaming

import os
from openai import OpenAI

client = OpenAI(  
  base_url = "https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/",
  api_key=os.getenv("AZURE_OPENAI_API_KEY")  
)

response = client.responses.create(
    input = "This is a test",
    model = "o4-mini", # replace with model deployment name
    stream = True
)

for event in response:
    if event.type == 'response.output_text.delta':
        print(event.delta, end='')

Chamada de função

A API de respostas suporta a invocação de funções.

import os
from openai import OpenAI

client = OpenAI(  
  base_url = "https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/",
  api_key=os.getenv("AZURE_OPENAI_API_KEY")  
)

response = client.responses.create(  
    model="gpt-4o",  # replace with your model deployment name  
    tools=[  
        {  
            "type": "function",  
            "name": "get_weather",  
            "description": "Get the weather for a location",  
            "parameters": {  
                "type": "object",  
                "properties": {  
                    "location": {"type": "string"},  
                },  
                "required": ["location"],  
            },  
        }  
    ],  
    input=[{"role": "user", "content": "What's the weather in San Francisco?"}],  
)  

print(response.model_dump_json(indent=2))  
  
# To provide output to tools, add a response for each tool call to an array passed  
# to the next response as `input`  
input = []  
for output in response.output:  
    if output.type == "function_call":  
        match output.name:  
            case "get_weather":  
                input.append(  
                    {  
                        "type": "function_call_output",  
                        "call_id": output.call_id,  
                        "output": '{"temperature": "70 degrees"}',  
                    }  
                )  
            case _:  
                raise ValueError(f"Unknown function call: {output.name}")  
  
second_response = client.responses.create(  
    model="gpt-4o",  
    previous_response_id=response.id,  
    input=input  
)  

print(second_response.model_dump_json(indent=2))

Intérprete de código

A ferramenta Code Interpreter permite que os modelos escrevam e executem código Python em um ambiente seguro e em área restrita. Suporta uma série de tarefas avançadas, incluindo:

  • Processamento de ficheiros com formatos e estruturas de dados variados
  • Geração de arquivos que incluem dados e visualizações (por exemplo, gráficos)
  • Escrever e executar código de forma iterativa para resolver problemas — os modelos podem depurar e repetir o código até serem bem-sucedidos
  • Melhorar o raciocínio visual em modelos suportados (por exemplo, o3, o4-mini) permitindo transformações de imagem, como corte, zoom e rotação
  • Esta ferramenta é especialmente útil para cenários que envolvem análise de dados, computação matemática e geração de código.
curl https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/responses?api-version=preview \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AZURE_OPENAI_AUTH_TOKEN" \
  -d '{
        "model": "gpt-4.1",
        "tools": [
            { "type": "code_interpreter", "container": {"type": "auto"} }
        ],
        "instructions": "You are a personal math tutor. When asked a math question, write and run code using the python tool to answer the question.",
        "input": "I need to solve the equation 3x + 11 = 14. Can you help me?"
    }'

import os
from openai import OpenAI

client = OpenAI(  
  base_url = "https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/",
  api_key=os.getenv("AZURE_OPENAI_API_KEY")  
)

instructions = "You are a personal math tutor. When asked a math question, write and run code using the python tool to answer the question."

response = client.responses.create(
    model="gpt-4.1",
    tools=[
        {
            "type": "code_interpreter",
            "container": {"type": "auto"}
        }
    ],
    instructions=instructions,
    input="I need to solve the equation 3x + 11 = 14. Can you help me?",
)

print(response.output)

Contentores

Important

O Interpretador de Código tem custos adicionais além das taxas baseadas no token de utilização do Azure OpenAI. Se sua API de respostas chamar o Interpretador de código simultaneamente em dois threads diferentes, duas sessões de interpretador de código serão criadas. Cada sessão fica ativa por padrão por 1 hora com um tempo limite ocioso de 20 minutos.

A ferramenta Code Interpreter requer um contêiner — uma máquina virtual totalmente em área restrita onde o modelo pode executar código Python. Os contêineres podem incluir arquivos carregados ou gerados durante a execução.

Para criar um contêiner, especifique "container": { "type": "auto", "file_ids": ["file-1", "file-2"] } na configuração da ferramenta ao criar um novo objeto Response. Isso cria automaticamente um novo contentor ou reutiliza um contentor ativo de uma chamada do intérprete de código anterior no contexto do modelo. O code_interpreter_call na saída da API conterá o container_id que foi gerado. Este recipiente expira se não for utilizado durante 20 minutos.

Entradas e saídas de ficheiros

Ao executar o Interpretador de Código, o modelo pode criar seus próprios arquivos. Por exemplo, se você pedir para construir um gráfico ou criar um CSV, ele criará essas imagens diretamente em seu contêiner. Ele citará esses arquivos nas anotações de sua próxima mensagem.

Todos os arquivos na entrada do modelo são automaticamente carregados para o contêiner. Não é necessário carregá-lo explicitamente para o contêiner.

Ficheiros suportados

Formato de ficheiro tipo de MIME
.c text/x-c
.cs text/x-csharp
.cpp text/x-c++
.csv texto/csv
.doc application/msword
.docx application/vnd.openxmlformats-officedocument.wordprocessingml.document
.html text/html
.java text/x-java
.json application/json
.md text/markdown
.pdf application/pdf
.php text/x-php
.pptx application/vnd.openxmlformats-officedocument.presentationml.presentation
.py text/x-python
.py text/x-script.python
.rb text/x-ruby
.tex text/x-tex
.txt text/plain
.css text/css
.js texto/JavaScript
.sh application/x-sh
.ts aplicativo/TypeScript
.csv application/csv
.jpeg image/jpeg
.jpg image/jpeg
.gif image/gif
.pkl application/octet-stream
.png image/png
.tar application/x-tar
.xlsx application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
.xml application/xml ou "texto/xml"
.zip application/zip

Listar itens de entrada

import os
from openai import OpenAI

client = OpenAI(  
  base_url = "https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/",
  api_key=os.getenv("AZURE_OPENAI_API_KEY")  
)

response = client.responses.input_items.list("resp_67d856fcfba0819081fd3cffee2aa1c0")

print(response.model_dump_json(indent=2))

Output:

{
  "data": [
    {
      "id": "msg_67d856fcfc1c8190ad3102fc01994c5f",
      "content": [
        {
          "text": "This is a test.",
          "type": "input_text"
        }
      ],
      "role": "user",
      "status": "completed",
      "type": "message"
    }
  ],
  "has_more": false,
  "object": "list",
  "first_id": "msg_67d856fcfc1c8190ad3102fc01994c5f",
  "last_id": "msg_67d856fcfc1c8190ad3102fc01994c5f"
}

Entrada de imagem

Para modelos com visão, são suportadas imagens em PNG (.png), JPEG (.jpeg e .jpg), WEBP (.webp).

URL da imagem

import os
from openai import OpenAI

client = OpenAI(  
  base_url = "https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/",
  api_key=os.getenv("AZURE_OPENAI_API_KEY")  
)

response = client.responses.create(
    model="gpt-4o",
    input=[
        {
            "role": "user",
            "content": [
                { "type": "input_text", "text": "what is in this image?" },
                {
                    "type": "input_image",
                    "image_url": "<image_URL>"
                }
            ]
        }
    ]
)

print(response)

Imagem codificada em Base64

import base64
import os
from openai import OpenAI

client = OpenAI(  
  base_url = "https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/",
  api_key=os.getenv("AZURE_OPENAI_API_KEY")  
)

def encode_image(image_path):
    with open(image_path, "rb") as image_file:
        return base64.b64encode(image_file.read()).decode("utf-8")

# Path to your image
image_path = "path_to_your_image.jpg"

# Getting the Base64 string
base64_image = encode_image(image_path)

response = client.responses.create(
    model="gpt-4o",
    input=[
        {
            "role": "user",
            "content": [
                { "type": "input_text", "text": "what is in this image?" },
                {
                    "type": "input_image",
                    "image_url": f"data:image/jpeg;base64,{base64_image}"
                }
            ]
        }
    ]
)

print(response)

Entrada de arquivo

Os modelos com capacidades de visão suportam a entrada de PDF. Os arquivos PDF podem ser fornecidos como dados codificados em Base64 ou como IDs de arquivo. Para ajudar os modelos a interpretar o conteúdo PDF, o texto extraído e uma imagem de cada página são incluídos no contexto do modelo. Isto é útil quando a informação chave é transmitida através de diagramas ou conteúdo não textual.

Note

  • Todos os textos e imagens extraídos são colocados no contexto do modelo. Certifique-se de entender as implicações nos preços e na utilização de tokens ao usar PDFs como dados de entrada.

  • Em uma única solicitação de API, o tamanho do conteúdo carregado em várias entradas (arquivos) deve estar dentro do comprimento de contexto do modelo.

  • Somente modelos que suportam entradas de texto e imagem podem aceitar arquivos PDF como entrada.

  • Atualmente, a purpose de user_data não é suportada. Como solução temporária, você precisará definir o propósito para assistants.

Converta PDF para Base64 e analise

import base64
import os
from openai import OpenAI

client = OpenAI(  
  base_url = "https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/",
  api_key=os.getenv("AZURE_OPENAI_API_KEY")  
)

with open("PDF-FILE-NAME.pdf", "rb") as f: # assumes PDF is in the same directory as the executing script
    data = f.read()

base64_string = base64.b64encode(data).decode("utf-8")

response = client.responses.create(
    model="gpt-4o-mini", # model deployment name
    input=[
        {
            "role": "user",
            "content": [
                {
                    "type": "input_file",
                    "filename": "PDF-FILE-NAME.pdf",
                    "file_data": f"data:application/pdf;base64,{base64_string}",
                },
                {
                    "type": "input_text",
                    "text": "Summarize this PDF",
                },
            ],
        },
    ]
)

print(response.output_text)

Carregue PDF e analise

Carregue o ficheiro PDF. Atualmente, a purpose de user_data não é suportada. Como solução alternativa, você precisará definir o propósito para assistants.

import os
from openai import OpenAI

client = OpenAI(  
  base_url = "https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/",
  api_key=os.getenv("AZURE_OPENAI_API_KEY")  
)


# Upload a file with a purpose of "assistants"
file = client.files.create(
  file=open("nucleus_sampling.pdf", "rb"), # This assumes a .pdf file in the same directory as the executing script
  purpose="assistants"
)

print(file.model_dump_json(indent=2))
file_id = file.id

Output:

{
  "id": "assistant-KaVLJQTiWEvdz8yJQHHkqJ",
  "bytes": 4691115,
  "created_at": 1752174469,
  "filename": "nucleus_sampling.pdf",
  "object": "file",
  "purpose": "assistants",
  "status": "processed",
  "expires_at": null,
  "status_details": null
}

Em seguida, você pegará o valor do id e o passará para um modelo para processamento em file_id:

import os
from openai import OpenAI

client = OpenAI(  
  base_url = "https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/",
  api_key=os.getenv("AZURE_OPENAI_API_KEY")  
)

response = client.responses.create(
    model="gpt-4o-mini",
    input=[
        {
            "role": "user",
            "content": [
                {
                    "type": "input_file",
                    "file_id":"assistant-KaVLJQTiWEvdz8yJQHHkqJ"
                },
                {
                    "type": "input_text",
                    "text": "Summarize this PDF",
                },
            ],
        },
    ]
)

print(response.output_text)

curl https://YOUR-RESOURCE-NAME.openai.azure.com/openai/files \
  -H "Authorization: Bearer $AZURE_OPENAI_AUTH_TOKEN" \
  -F purpose="assistants" \
  -F file="@your_file.pdf" \

curl https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AZURE_OPENAI_AUTH_TOKEN" \
  -d '{
        "model": "gpt-4.1",
        "input": [
            {
                "role": "user",
                "content": [
                    {
                        "type": "input_file",
                        "file_id": "assistant-123456789"
                    },
                    {
                        "type": "input_text",
                        "text": "ASK SOME QUESTION RELATED TO UPLOADED PDF"
                    }
                ]
            }
        ]
    }'

Usando servidores MCP remotos

Você pode estender os recursos do seu modelo conectando-o a ferramentas hospedadas em servidores MCP (Model Context Protocol) remotos. Esses servidores são mantidos por desenvolvedores e organizações e expõem ferramentas que podem ser acessadas por clientes compatíveis com MCP, como a API de respostas.

O MCP (Model Context Protocol ) é um padrão aberto que define como os aplicativos fornecem ferramentas e dados contextuais para grandes modelos de linguagem (LLMs). Ele permite a integração consistente e escalável de ferramentas externas em fluxos de trabalho de modelo.

O exemplo a seguir demonstra como usar o servidor MCP fictício para consultar informações sobre a API REST do Azure. Isso permite que o modelo recupere e raciocine sobre o conteúdo do repositório em tempo real.

curl https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AZURE_OPENAI_AUTH_TOKEN" \
  -d '{
  "model": "gpt-4.1",
  "tools": [
    {
      "type": "mcp",
      "server_label": "github",
      "server_url": "https://contoso.com/Azure/azure-rest-api-specs",
      "require_approval": "never"
    }
  ],
  "input": "What is this repo in 100 words?"
}'

import os
from openai import OpenAI

client = OpenAI(  
  base_url = "https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/",
  api_key=os.getenv("AZURE_OPENAI_API_KEY")  
)
response = client.responses.create(
    model="gpt-4.1", # replace with your model deployment name 
    tools=[
        {
            "type": "mcp",
            "server_label": "github",
            "server_url": "https://contoso.com/Azure/azure-rest-api-specs",
            "require_approval": "never"
        },
    ],
    input="What transport protocols are supported in the 2025-03-26 version of the MCP spec?",
)

print(response.output_text)

A ferramenta MCP funciona apenas na API de respostas e está disponível em todos os modelos mais recentes (gpt-4o, gpt-4.1 e nossos modelos de raciocínio). Ao usar a ferramenta MCP, você paga apenas por tokens usados ao importar definições de ferramentas ou fazer chamadas de ferramentas — não há taxas adicionais envolvidas.

Approvals

Por padrão, a API de respostas requer aprovação explícita antes que qualquer dado seja compartilhado com um servidor MCP remoto. Esta etapa de aprovação ajuda a garantir a transparência e oferece controle sobre quais informações são enviadas externamente.

Recomendamos revisar todos os dados que estão sendo compartilhados com servidores MCP remotos e, opcionalmente, registrá-los para fins de auditoria.

Quando uma aprovação é necessária, o modelo retorna um mcp_approval_request item na saída da resposta. Este objeto contém os detalhes da solicitação pendente e permite que você inspecione ou modifique os dados antes de prosseguir.

{
  "id": "mcpr_682bd9cd428c8198b170dc6b549d66fc016e86a03f4cc828",
  "type": "mcp_approval_request",
  "arguments": {},
  "name": "fetch_azure_rest_api_docs",
  "server_label": "github"
}

Para prosseguir com a chamada MCP remota, você deve responder à solicitação de aprovação criando um novo objeto de resposta que inclua um item mcp_approval_response. Este objeto confirma sua intenção de permitir que o modelo envie os dados especificados para o servidor MCP remoto.

curl https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AZURE_OPENAI_AUTH_TOKEN" \
  -d '{
  "model": "gpt-4.1",
  "tools": [
    {
      "type": "mcp",
      "server_label": "github",
      "server_url": "https://contoso.com/Azure/azure-rest-api-specs",
      "require_approval": "never"
    }
  ],
  "previous_response_id": "resp_682f750c5f9c8198aee5b480980b5cf60351aee697a7cd77",
  "input": [{
    "type": "mcp_approval_response",
    "approve": true,
    "approval_request_id": "mcpr_682bd9cd428c8198b170dc6b549d66fc016e86a03f4cc828"
  }]
}'

import os
from openai import OpenAI

client = OpenAI(  
  base_url = "https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/",
  api_key=os.getenv("AZURE_OPENAI_API_KEY")  
)

response = client.responses.create(
    model="gpt-4.1", # replace with your model deployment name 
    tools=[
        {
            "type": "mcp",
            "server_label": "github",
            "server_url": "https://contoso.com/Azure/azure-rest-api-specs",
            "require_approval": "never"
        },
    ],
    previous_response_id="resp_682f750c5f9c8198aee5b480980b5cf60351aee697a7cd77",
    input=[{
        "type": "mcp_approval_response",
        "approve": True,
        "approval_request_id": "mcpr_682bd9cd428c8198b170dc6b549d66fc016e86a03f4cc828"
    }],
)

Authentication

Important

  • O cliente MCP dentro da API Respostas requer TLS 1.2 ou superior.
  • TLS mútuo (mTLS) atualmente não é suportado.
  • As etiquetas de serviço Azure não são atualmente suportadas para tráfego de clientes MCP.

Ao contrário do servidor MCP do GitHub, a maioria dos servidores MCP remotos requer autenticação. A ferramenta MCP na API de respostas oferece suporte a cabeçalhos personalizados, permitindo que você se conecte com segurança a esses servidores usando o esquema de autenticação necessário.

Você pode especificar cabeçalhos como chaves de API, tokens de acesso OAuth ou outras credenciais diretamente em sua solicitação. O cabeçalho mais usado é o Authorization cabeçalho.

curl https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AZURE_OPENAI_AUTH_TOKEN" \
  -d '{
        "model": "gpt-4.1",
        "input": "What is this repo in 100 words?"
        "tools": [
            {
                "type": "mcp",
                "server_label": "github",
                "server_url": "https://contoso.com/Azure/azure-rest-api-specs",
                "headers": {
                    "Authorization": "Bearer $YOUR_API_KEY"
            }
        ]
    }'

import os
from openai import OpenAI

client = OpenAI(  
  base_url = "https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/",
  api_key=os.getenv("AZURE_OPENAI_API_KEY")  
)

response = client.responses.create(
    model="gpt-4.1",
    input="What is this repo in 100 words?",
    tools=[
        {
            "type": "mcp",
            "server_label": "github",
            "server_url": "https://gitmcp.io/Azure/azure-rest-api-specs",
            "headers": {
                "Authorization": "Bearer $YOUR_API_KEY"
        }
    ]
)

print(response.output_text)

Tarefas em segundo plano

O modo em segundo plano permite executar tarefas de longa duração de forma assíncrona usando modelos como o3 e o1-pro. Isso é especialmente útil para tarefas de raciocínio complexas que podem levar vários minutos para serem concluídas, como aquelas manipuladas por agentes como Codex ou Deep Research.

Ao ativar o modo em segundo plano, você pode evitar tempos limite e manter a confiabilidade durante operações estendidas. Quando uma solicitação é enviada com "background": true, a tarefa é processada de forma assíncrona, e pode consultar o seu status ao longo do tempo.

Para iniciar uma tarefa em segundo plano, defina o parâmetro background como true na sua solicitação:

curl https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AZURE_OPENAI_AUTH_TOKEN" \
  -d '{
    "model": "o3",
    "input": "Write me a very long story",
    "background": true
  }'

import os
from openai import OpenAI

client = OpenAI(  
  base_url = "https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/",
  api_key=os.getenv("AZURE_OPENAI_API_KEY")  
)

response = client.responses.create(
    model = "o3",
    input = "Write me a very long story",
    background = True
)

print(response.status)

Use o endpoint GET para verificar o estado de uma resposta em segundo plano. Continue a sondagem enquanto o status está na fila ou in_progress. Assim que a resposta atingir um estado final (terminal), estará disponível para consulta.

curl GET https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/responses/resp_1234567890 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AZURE_OPENAI_AUTH_TOKEN"

from time import sleep
import os
from openai import OpenAI

client = OpenAI(  
  base_url = "https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/",
  api_key=os.getenv("AZURE_OPENAI_API_KEY")  
)

response = client.responses.create(
    model = "o3",
    input = "Write me a very long story",
    background = True
)

while response.status in {"queued", "in_progress"}:
    print(f"Current status: {response.status}")
    sleep(2)
    response = client.responses.retrieve(response.id)

print(f"Final status: {response.status}\nOutput:\n{response.output_text}")

Você pode cancelar uma tarefa em segundo plano em andamento usando o cancel endpoint. O cancelamento é idempotente — as chamadas subsequentes retornarão o objeto de resposta final.

curl -X POST https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/responses/resp_1234567890/cancel \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AZURE_OPENAI_AUTH_TOKEN"

import os
from openai import OpenAI

client = OpenAI(  
  base_url = "https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/",
  api_key=os.getenv("AZURE_OPENAI_API_KEY")  
)

response = client.responses.cancel("resp_1234567890")

print(response.status)

Transmitir uma resposta em segundo plano

Para transmitir uma resposta em segundo plano, defina ambas background e stream como true. Isso é útil se você quiser retomar o streaming mais tarde em caso de queda de conexão. Use o número de sequência de cada evento para acompanhar a sua posição.

curl https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AZURE_OPENAI_AUTH_TOKEN" \
  -d '{
    "model": "o3",
    "input": "Write me a very long story",
    "background": true,
    "stream": true
  }'


import os
from openai import OpenAI

client = OpenAI(  
  base_url = "https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/",
  api_key=os.getenv("AZURE_OPENAI_API_KEY")  
)

# Fire off an async response but also start streaming immediately
stream = client.responses.create(
    model="o3",
    input="Write me a very long story",
    background=True,
    stream=True,
)

cursor = None
for event in stream:
    print(event)
    cursor = event["sequence_number"]

Note

Atualmente, as respostas em segundo plano têm uma latência de tempo até o primeiro token maior do que as respostas síncronas. Estão em curso melhorias para reduzir esta diferença.

Limitations

  • O modo de segundo plano requer store=true. Solicitações sem estado não são suportadas.
  • Você só pode retomar o streaming se a solicitação original estiver incluída stream=true.
  • Para cancelar uma resposta síncrona, encerre a conexão diretamente.

Retomar o streaming a partir de um ponto específico

curl https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/responses/resp_1234567890?stream=true&starting_after=42 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AZURE_OPENAI_AUTH_TOKEN"

Itens de raciocínio criptografados

Ao usar a API de respostas no modo sem estado — seja ao definir store como false ou quando a sua organização está inscrita em retenção zero de dados — você ainda deve preservar o contexto de raciocínio ao longo dos turnos de conversa. Para fazer isso, inclua itens de raciocínio criptografados em suas solicitações de API.

Para reter itens de raciocínio em turnos, adicione reasoning.encrypted_content ao include parâmetro em sua solicitação. Isso garante que a resposta inclua uma versão criptografada do rastreamento de raciocínio, que pode ser transmitida em solicitações futuras.

curl https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AZURE_OPENAI_AUTH_TOKEN" \
  -d '{
    "model": "o4-mini",
    "reasoning": {"effort": "medium"},
    "input": "What is the weather like today?",
    "tools": [<YOUR_FUNCTION GOES HERE>],
    "include": ["reasoning.encrypted_content"]
  }'

Geração de imagens (pré-visualização)

A API de respostas permite a geração de imagens como parte de conversas e fluxos de trabalho de várias etapas. Ele suporta entradas e saídas de imagem dentro do contexto e inclui ferramentas integradas para gerar e editar imagens.

Em comparação com a API de imagem autônoma, a API de respostas oferece várias vantagens:

  • Streaming: Exiba saídas parciais de imagem durante a geração para melhorar a latência percebida.
  • Entradas flexíveis: aceite IDs de arquivo de imagem como entradas, além de bytes de imagem brutos.

Note

A ferramenta de geração de imagens na API Respostas é suportada apenas pelos modelos da série gpt-image-1. No entanto, pode utilizar este modelo a partir desta lista de modelos suportados - modelos da série gpt-4o, gpt-4o-mini, gpt-4.1, gpt-4.1-mini, gpt-4.1-nano, o3, gpt-5 e gpt-5.1.

Atualmente, a ferramenta de geração de imagens da API de respostas não oferece suporte ao modo de streaming. Para usar o modo de streaming e gerar imagens parciais, chame a API de geração de imagens diretamente fora da API de respostas.

Use a API de Respostas se quiser criar experiências de imagem de conversação com o GPT Image.

from openai import OpenAI
from azure.identity import DefaultAzureCredential, get_bearer_token_provider

token_provider = get_bearer_token_provider(
    DefaultAzureCredential(), "https://cognitiveservices.azure.com/.default"
)

client = OpenAI(  
  base_url = "https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/",  
  api_key=token_provider,
  default_headers={"x-ms-oai-image-generation-deployment":"gpt-image-1", "api_version":"preview"}
)

response = client.responses.create(
    model="o3",
    input="Generate an image of gray tabby cat hugging an otter with an orange scarf",
    tools=[{"type": "image_generation"}],
)

# Save the image to a file
image_data = [
    output.result
    for output in response.output
    if output.type == "image_generation_call"
]
    
if image_data:
    image_base64 = image_data[0]
    with open("otter.png", "wb") as f:
        f.write(base64.b64decode(image_base64))

Modelos de raciocínio

Para obter exemplos de como usar modelos de raciocínio com a API de respostas, consulte o guia de modelos de raciocínio.

Utilização do computador

O uso do computador com o Playwright foi transferido para o guia do modelo de uso específico do computador.

  • Last updated on