Use a API de Respostas do Azure OpenAI

Use a API de Respostas do Azure OpenAI para gerar respostas com estado e múltiplas voltas. Reúne capacidades de conclusão de chats e da API de Assistentes numa experiência unificada. A API Respostas também suporta o computer-use-preview modelo que alimenta o uso do computador.

Pré-requisitos

• Um modelo Azure OpenAI implementado
• Um método de autenticação:
  • Chave API (por exemplo, AZURE_OPENAI_API_KEY), ou
  • Microsoft Entra ID (recomendado).

Instale ou atualize o pacote OpenAI

Instale ou atualize o pacote Python da 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)) 

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

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

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

response = client.responses.create(
    model="gpt-4.1-nano",
    input= "This is a test" 
)

print(response.model_dump_json(indent=2)) 

curl -X POST 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-4o",
     "input": "This is a test"
    }'

curl -X POST https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/responses \
  -H "Content-Type: application/json" \
  -H "api-key: $AZURE_OPENAI_API_KEY" \
  -d '{
     "model": "gpt-4.1-nano",
     "input": "This is a test"
    }'

{
  "id": "resp_67cb32528d6881909eb2859a55e18a85",
  "created_at": 1741369938.0,
  "error": null,
  "incomplete_details": null,
  "instructions": null,
  "metadata": {},
  "model": "gpt-4o-2024-08-06",
  "object": "response",
  "output": [
    {
      "id": "msg_67cb3252cfac8190865744873aada798",
      "content": [
        {
          "annotations": [],
          "text": "Great! How can I help you today?",
          "type": "output_text"
        }
      ],
      "role": "assistant",
      "status": null,
      "type": "message"
    }
  ],
  "output_text": "Great! How can I help you today?",
  "parallel_tool_calls": null,
  "temperature": 1.0,
  "tool_choice": null,
  "tools": [],
  "top_p": 1.0,
  "max_output_tokens": null,
  "previous_response_id": null,
  "reasoning": null,
  "status": "completed",
  "text": null,
  "truncation": null,
  "usage": {
    "input_tokens": 20,
    "output_tokens": 11,
    "output_tokens_details": {
      "reasoning_tokens": 0
    },
    "total_tokens": 31
  },
  "user": null,
  "reasoning_effort": null
}

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")

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

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

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

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

print(response.model_dump_json(indent=2))

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

curl -X GET https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/responses/{response_id} \
  -H "Content-Type: application/json" \
  -H "api-key: $AZURE_OPENAI_API_KEY" 

{
  "id": "resp_67cb61fa3a448190bcf2c42d96f0d1a8",
  "created_at": 1741382138.0,
  "error": null,
  "incomplete_details": null,
  "instructions": null,
  "metadata": {},
  "model": "gpt-4o-2024-08-06",
  "object": "response",
  "output": [
    {
      "id": "msg_67cb61fa95588190baf22ffbdbbaaa9d",
      "content": [
        {
          "annotations": [],
          "text": "Hello! How can I assist you today?",
          "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": null,
  "reasoning": null,
  "status": "completed",
  "text": null,
  "truncation": null,
  "usage": {
    "input_tokens": 20,
    "output_tokens": 11,
    "output_tokens_details": {
      "reasoning_tokens": 0
    },
    "total_tokens": 31
  },
  "user": null,
  "reasoning_effort": null
}

Apagar resposta

Por defeito, os dados de resposta são mantidos durante 30 dias. Para eliminar uma resposta armazenada, chame client.responses.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)

Encadear respostas

Pode encadear respostas 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-se no resultado que, embora nunca tenhamos compartilhado a primeira pergunta de entrada com a chamada API second_response, ao passar o previous_response_id, o modelo tem o contexto completo da pergunta e da resposta anteriores para responder à nova pergunta.

Saída:

{
  "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
}

Encadear respostas manualmente

Em alternativa, pode encadear respostas manualmente 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))  

Compactar uma Resposta

A compactação permite-lhe reduzir a janela de contexto enviada ao modelo, preservando a informação essencial para a compreensão do modelo.

Compactar usando itens devolvidos

Podes compactar todos os itens devolvidos de pedidos anteriores, como raciocínio, mensagem, chamada de função, etc.

curl https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/responses/compact \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AZURE_OPENAI_AUTH_TOKEN" \
  -d '{
        "model": "gpt-4.1",
        "input": [
          {
            "role"   : "user",
            "content": "Create a simple landing page for a dog petting café."
          },
          {
            "id": "msg_001",
            "type": "message",
            "status": "completed",
            "content": [
              {
                "type": "output_text",
                "annotations": [],
                "logprobs": [],
                "text": "Below is a single file, ready-to-use landing page for a dog petting café:..."
              }
            ],
            "role": "assistant"
          }
        ]
    }'

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")  
)

compacted_response = client.responses.compact(
    model="gpt-4.1",
    input=[
    {
        "role": "user",
        "content": "Create a simple landing page for a dog petting cafe.",
    },
    # All items returned from previous requests are included here, like reasoning, message, function call, etc.
    {
        "id": "msg_001",
        "type": "message",
        "status": "completed",
        "content": [
        {
            "type": "output_text",
            "annotations": [],
            "logprobs": [],
            "text": "Below is a single file, ready-to-use landing page for a dog petting café:...",
        },
        ],
        "role": "assistant",
    },
    ]
)
# Pass the compacted_response.output as input to the next request
print(compacted_response)

Compactar usando o ID de resposta anterior

Também pode comprimir usando um ID de resposta prévio.

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")  
)

# Get back a full response
initial_response = client.responses.create(
        model="gpt-4.1",
        input="What is the size of France?"
    )

print(f"Initial Response: {initial_response.output_text}")

# Now compact the response
compacted_response = client.responses.compact(
    model="gpt-4.1",
    previous_response_id=initial_response.id
)

# use the compacted response in a follow up
followup_response = client.responses.create(
    model="gpt-4.1",
    input=[
        *compacted_response.output,
        {"role": "user", "content": "And what is the capital/major city"}
    ]
)
print(f"Follow-up Response: {followup_response.output_text}")

Compactação do lado do servidor

Também pode usar compactação do lado do servidor diretamente em Respostas (POST /responses ou client.responses.create) definindo context_management com um compact_threshold.

• Quando a contagem de tokens de saída ultrapassa o limiar configurado, a API de Respostas executa automaticamente a compactação.
• Neste modo, não precisa de ligar /responses/compact separadamente.
• A resposta inclui um item de compactação encriptado.
• A compactação do lado do servidor funcionará quando definires store=false nos teus pedidos de criação de respostas.

O item de compactação transporta o estado e raciocínio essenciais para o turno seguinte, usando menos tokens. É opaco e não pretende ser legível para humanos.

Se estiver a usar encadeamento de matrizes de entrada sem estado, adicione itens de saída como de costume. Se estiveres a usar previous_response_id, passa apenas a mensagem do novo utilizador em cada turno. Em ambos os padrões, o item de compactação transporta o contexto necessário para a janela seguinte.

Flow

1. Liga responses como sempre. Adicione context_management com compact_threshold para permitir a compactação do lado do servidor.
2. Se a saída ultrapassar o limiar, o serviço desencadeia a compactação, emite um item de compactação no fluxo de saída e reduz o contexto antes de continuar a inferência.
3. Continue a conversa usando um destes padrões:
   1. Encadeamento de matrizes de entrada sem estado: adicionar itens de saída, incluindo itens de compactação, ao próximo array de entrada.
   2. previous_response_id encadeamento: passa apenas a mensagem do novo utilizador em cada turno e leva o ID de resposta mais recente para a frente.

Exemplo

conversation = [
  {
    "type": "message",
    "role": "user",
    "content": "Let's begin a long coding task.",
  }
]

while keep_going:
  response = client.responses.create(
    model="gpt-5.3-codex",
    input=conversation,
    store=False,
    context_management=[{"type": "compaction", "compact_threshold": 200000}],
  )

  conversation.append(
    {
      "type": "message",
       "role": "user",
      "content": get_next_user_input(),
    }
  )

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 chamada 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)) 

Interpretador de Código

A ferramenta Code Interpreter permite que modelos escrevam e executem código Python num ambiente seguro e sandbox. Suporta uma variedade de tarefas avançadas, incluindo:

• Processamento de ficheiros com formatos e estruturas de dados variados
• Gerar ficheiros que incluam dados e visualizações (por exemplo, gráficos)
• Escrever e executar código iterativamente para resolver problemas — os modelos podem depurar e tentar 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 recortar, ampliar 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

A ferramenta Code Interpreter requer um contentor — uma máquina virtual totalmente sandbox onde o modelo pode executar código Python. Os contentores podem incluir ficheiros carregados ou gerados durante a execução.

Para criar um contentor, especifique "container": { "type": "auto", "file_ids": ["file-1", "file-2"] } na configuração da ferramenta ao criar um novo objeto Resposta. Isto cria automaticamente um novo contentor ou reutiliza um contentor ativo de um code_interpreter_call 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 usado durante 20 minutos.

Entradas e saídas de ficheiros

Ao executar o Code Interpreter, o modelo pode criar os seus próprios ficheiros. Por exemplo, se lhe pedires para construir um gráfico ou criar um CSV, ele cria estas imagens diretamente no teu contentor. Irá citar estes ficheiros nas anotações da sua próxima mensagem.

Quaisquer ficheiros na entrada do modelo são automaticamente carregados para o contentor. Não tens de o carregar explicitamente no contentor.

Ficheiros Suportados

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

Saída:

{
  "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 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 ficheiros

Modelos com capacidades de visão suportam entrada em PDF. Os ficheiros PDF podem ser fornecidos tanto como dados codificados em Base64 como IDs de ficheiro. Para ajudar os modelos a interpretar o conteúdo PDF, tanto o texto extraído como 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.

Converter PDF para Base64 e analisar

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)

Carregar PDF e analisar

Carregue o ficheiro PDF. Um purpose de user_data atualmente não é suportado. Como solução alternativa, terá de 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

Saída:

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

Depois, irá tomar o valor de id e passá-lo 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"
                    }
                ]
            }
        ]
    }'

Utilização de servidores MCP remotos

Pode expandir as capacidades do seu modelo ligando-o a ferramentas alojadas em servidores remotos do Model Context Protocol (MCP). Estes servidores são mantidos por programadores e organizações e expõem ferramentas que podem ser acedidas por clientes compatíveis com MCP, como a API Responses.

O Protocolo de Contexto de Modelo (MCP) é um padrão aberto que define como as aplicações fornecem ferramentas e dados contextuais a grandes modelos de linguagem (LLMs). Permite a integração consistente e escalável de ferramentas externas nos fluxos de trabalho dos modelos.

O exemplo seguinte demonstra como usar o servidor MCP fictício para consultar informações sobre a API REST do Azure. Isto permite ao modelo recuperar e raciocinar 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 Responses e está disponível em todos os modelos mais recentes (gpt-4o, gpt-4.1 e os nossos modelos de raciocínio). Quando utiliza a ferramenta MCP, só paga pelos tokens usados ao importar definições ou fazer chamadas de ferramentas — não há taxas adicionais envolvidas.

Aprovações

Por defeito, a API de Respostas requer aprovação explícita antes de qualquer dado ser partilhado com um servidor MCP remoto. Este passo de aprovação ajuda a garantir transparência e dá-lhe controlo sobre a informação enviada externamente.

Recomendamos rever todos os dados partilhados com servidores MCP remotos e, opcionalmente, logá-los para efeitos de auditoria.

Quando é necessária uma aprovação, o modelo devolve um mcp_approval_request item na saída da resposta. Este objeto contém os detalhes do pedido pendente e permite-lhe inspecionar ou modificar 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, deve responder ao pedido de aprovação criando um novo objeto de resposta que inclua um item mcp_approval_response. Este objeto confirma a 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"
    }],
)

Autenticação

Ao contrário do servidor MCP do GitHub, a maioria dos servidores MCP remotos requer autenticação. A ferramenta MCP na API de Respostas suporta cabeçalhos personalizados, permitindo-lhe ligar de forma segura a estes servidores usando o esquema de autenticação que exigem.

Pode especificar cabeçalhos como chaves API, tokens de acesso OAuth ou outras credenciais diretamente no seu pedido. 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 de fundo

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

Ao ativar o modo em segundo plano, pode evitar timeouts e manter a fiabilidade durante operações prolongadas. Quando um pedido é enviado com "background": true, a tarefa é processada de forma assíncrona, e pode consultar o seu estado ao longo do tempo.

Para iniciar uma tarefa em segundo plano, defina o parâmetro em segundo plano para true no seu pedido:

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 GET endpoint para verificar o estado de uma resposta em segundo plano. Continue a fazer sondagens enquanto o estado está em fila ou in_progress. Quando a resposta atingir o estado final (terminal), estará disponível para recuperação.

curl -X 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}")

Podes cancelar uma tarefa em segundo plano em curso usando o cancel endpoint. O cancelamento é idempotente — 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)

Transmita uma resposta em segundo plano

Para transmitir uma resposta em segundo plano, defina ambos background e stream para true. Isto é útil se quiseres retomar o streaming mais tarde, caso a ligação caia. Usa o sequence_number de cada evento para acompanhar a tua 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"]

Limitações

• O modo de fundo requer store=true. Pedidos sem estado não são suportados.
• Pode retomar o streaming apenas se o pedido original incluir stream=true.
• Para cancelar uma resposta síncrona, termine a ligação diretamente.

Resumir 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 Encriptado

Ao usar a API Respostas em modo sem estado, definindo store como falso, deve ainda preservar o contexto de raciocínio entre turnos de conversa. Para isso, inclua itens de raciocínio encriptado nos seus pedidos de API.

Para reter itens de raciocínio ao longo dos turnos, adicione reasoning.encrypted_content ao include parâmetro no seu pedido. Isto garante que a resposta inclui uma versão encriptada do rastreio de raciocínio, que pode ser transmitida em pedidos futuros.

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 imagem (pré-visualização)

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

Comparada com a API de Imagem independente, a API de Respostas oferece várias vantagens:

• Streaming: Mostrar saídas parciais de imagem durante a geração para melhorar a latência percebida.
• Entradas flexíveis: Aceitar IDs de ficheiro de imagem como entradas, além dos bytes de imagem bruto.

Use a API Respostas se quiser criar experiências de imagem conversacional 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://ai.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.5", "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 exemplos de como usar modelos de raciocínio com a API de respostas, consulte o guia de modelos de raciocínio.

Utilização de computadores

O uso do computador com Playwright foi movido para o guia do modelo de uso dedicado do computador

API de Respostas

Suporte para API

• A API v1 é necessária para aceder às funcionalidades mais recentes

Disponibilidade da Região

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

• AustráliaLeste
• Brasil-Sul
• CanadaCentral
• CanadaEast
• eastus
• eastus2
• Francecentral
• Alemanha Centro-Ocidental
• Itália Norte
• Leste do Japão
• Koreacentral
• Northcentralus
• Norwayeast
• Polónia Central
• África do Sul-Norte
• Southcentralus
• Southeastasia
• Sul da Índia
• Espanha Central
• Suécia-Central
• Suíça-norte
• uaenorth
• uksouth
• Westus
• Westus3

Suporte a modelos

• gpt-5.5 (Versão: 2026-04-24)
• gpt-5.4-nano (Versão: 2026-03-17)
• gpt-5.4-mini (Versão: 2026-03-17)
• gpt-5.4-pro (Versão:2026-03-05)
• gpt-5.4 (Versão:2026-03-05)
• gpt-5.3-chat (Versão: 2026-03-03)
• gpt-5.3-codex (Versão: 2026-02-24)
• gpt-5.2-codex (Versão: 2026-01-14)
• gpt-5.2 (Versão: 2025-12-11)
• gpt-5.2-chat (Versão: 2025-12-11)
• gpt-5.2-chat (Versão: 2026-02-10)
• 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)
• gpt-image-1.5 (Versão: 2025-12-16)
• 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. Consulte a página dos modelos para a disponibilidade da região dos modelos.

Documentação de referência

• Documentação de referência da API de Respostas

Resolução de problemas

• 401/403: Se usar Microsoft Entra ID, verifique se o seu token está abrangido por https://ai.azure.com/.default. Se usares uma chave API, confirma que estás a usar a chave correta para o recurso.
• 404: Confirma model que corresponde ao teu nome de destacamento.

Conteúdo relacionado

• Ciclo de vida da versão da API
• Referência da API REST do Azure OpenAI
• Utilização de computadores