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 funcionalidades de conclusões de chats e da API dos 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 a biblioteca cliente para a sua linguagem:
    • Python: pip install openai azure-identity
    • .NET: dotnet add package OpenAI e dotnet add package Azure.Identity
    • JavaScript/TypeScript: npm install openai @azure/identity
    • Java: Adicione com.openai:openai-java e com.azure:azure-identity ao seu projeto.
  • Para exemplos REST, defina AZURE_OPENAI_API_KEY (fluxo de chaves API) ou AZURE_OPENAI_AUTH_TOKEN (fluxo Microsoft Entra ID).

Regiões suportadas

Antes de executar os exemplos deste artigo, confirme se a sua região de recursos suporta a API Responses. A API v1 é necessária para aceder às funcionalidades mais recentes — para mais detalhes, consulte o ciclo de vida da versão da API. A API Respostas está atualmente disponível nas seguintes regiões:

  • AustráliaEast
  • Brasil-Sul
  • CanadaCentral
  • Canadá Oriental
  • eastus
  • eastus2
  • Francecentral
  • Alemanha Centro-Ocidental
  • Itália Norte
  • japaneast
  • 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

Modelos suportados

A API Responses suporta os seguintes modelos:

  • gpt-chat-latest (Versões: 2026-05-28, 2026-05-05)
  • 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 em todas as regiões suportadas. Consulte a página dos modelos para a disponibilidade da região dos modelos. Para o conjunto completo de parâmetros de pedido e resposta, consulte a documentação de referência da API Responses.

Nota

Não suportado atualmente:

  • Geração de imagem usando edição em múltiplas etapas e streaming.
  • As imagens não podem ser carregadas como ficheiro e depois referenciadas como entrada.

Há um problema conhecido com o seguinte:

  • O PDF como ficheiro de entrada é agora suportado, mas definir o propósito de upload do ficheiro como user_data não é atualmente suportado.
  • Problemas de desempenho quando o modo em segundo plano é usado com streaming. A Microsoft está a trabalhar para resolver este problema.

Gerar uma resposta de texto

Gera uma resposta simples de texto usando a API de Respostas. Substitua YOUR-RESOURCE-NAME e MODEL_NAME com os valores de implantação.

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

# API key authentication
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="MODEL_NAME",
    input="This is a test."
)
print(response.model_dump_json(indent=2))

# Microsoft Entra ID authentication (recommended)
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="MODEL_NAME",
    input="This is a test."
)
print(response.model_dump_json(indent=2))

Resposta de exemplo

{
  "id": "resp_67cb32528d6881909eb2859a55e18a85",
  "created_at": 1741369938.0,
  "output_text": "Great! How can I help you today?",
  ...
}

Recuperar uma resposta

Recupere uma resposta pelo seu ID de uma chamada anterior da API de Respostas.

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

# API key authentication
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("<response_id>")
print(response.model_dump_json(indent=2))

# Microsoft Entra ID authentication
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("<response_id>")
print(response.model_dump_json(indent=2))

Resposta de exemplo

{
  "id": "resp_67cb61fa3a448190bcf2c42d96f0d1a8",
  "output_text": "Hello! How can I assist you today?",
  ...
}

Apagar uma resposta

Por defeito, os dados de resposta são mantidos durante 30 dias. Apaga uma resposta armazenada por ID.

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

# API key authentication
client = OpenAI(
    api_key=os.getenv("AZURE_OPENAI_API_KEY"),
    base_url="https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/",
)
response = client.responses.delete("<response_id>")
print(response)

# Microsoft Entra ID authentication
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.delete("<response_id>")
print(response)

Encadear respostas

Encadeie os turnos ao passar o ID da resposta anterior para previous_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")
)

first_response = client.responses.create(
    model="MODEL_NAME",
    input="Define catastrophic forgetting."
)

second_response = client.responses.create(
    model="MODEL_NAME",
    previous_response_id=first_response.id,
    input="Explain it for a college freshman."
)

print(second_response.output_text)

Encadear respostas manualmente

Alternativamente, pode transferir manualmente os itens de saída no próximo pedido.

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="MODEL_NAME",
    input=inputs
)

print(second_response.model_dump_json(indent=2))

Compactar uma resposta

A compactação reduz o contexto de entrada enquanto preserva o estado essencial para turnos posteriores.

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 = client.responses.compact(
  model="MODEL_NAME",
  input=[
    {"role": "user", "content": "Create a simple landing page for a dog cafe."},
    {
      "id": "msg_001",
      "type": "message",
      "status": "completed",
      "role": "assistant",
      "content": [{"type": "output_text", "text": "..."}],
    },
  ]
)

follow_up = client.responses.create(
  model="MODEL_NAME",
  input=[*compacted.output, {"role": "user", "content": "Add a booking form."}]
)
print(follow_up.output_text)

Compactar usando itens devolvidos

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

curl -X POST 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": "MODEL_NAME",
        "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"
          }
        ]
    }'

# Use the compacted output as input for the next turn.
next_response = client.responses.create(
  model="MODEL_NAME",
  input=[*compacted.output, {"role": "user", "content": "Add opening hours."}],
)
print(next_response.output_text)

Compactar usando o ID de resposta anterior

Pode também compactar utilizando um ID de resposta anterior.

initial_response = client.responses.create(
  model="MODEL_NAME",
  input="What is the size of France?"
)

compacted_response = client.responses.compact(
  model="MODEL_NAME",
  previous_response_id=initial_response.id
)

follow_up_response = client.responses.create(
  model="MODEL_NAME",
  input=[
    *compacted_response.output,
    {"role": "user", "content": "What is the capital?"}
  ]
)
print(follow_up_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) ao definir 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 é necessário ligar /responses/compact separadamente.
  • A resposta inclui um item de compactação encriptado.
  • A compactação do lado do servidor funciona quando defines store=false nos teus pedidos de criação de respostas.

O item de compactação transfere o estado e raciocínio essenciais para a etapa 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.

Dica

Depois de adicionar itens de saída aos itens de entrada anteriores, pode eliminar itens que vieram antes do item de compactação mais recente para manter os pedidos mais pequenos e reduzir a latência de cauda longa. O último item de compactação traz o contexto necessário para continuar a conversa. Se usares previous_response_id encadeamento, não deves fazer o corte manualmente.

Flow

  1. Chame responses como sempre. Adicione context_management com compact_threshold para ativar 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 poda 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 elementos compactados, à próxima matriz de entrada.
    2. previous_response_id encadeamento: envia apenas a nova mensagem do utilizador em cada turno e transporta o ID de resposta mais recente.

Exemplo

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

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

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

Streaming

Transmita a resposta conforme é gerada ao definir stream=true. O serviço emite eventos incrementais que pode consumir para renderizar a saída token a token.

Nota

Durante o streaming, a API de Respostas pode devolver um evento de erro ( 500, 429, e erros semelhantes) se o serviço encontrar um erro, como limites de tokens ou problemas de análise sintática. As aplicações devem detetar este evento e interromper ou reiniciar a transmissão de forma gradual. Não são cobrados pelos tokens gerados durante tentativas falhadas de transmissão.

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

stream = client.responses.create(
    model="MODEL_NAME",
    input="Summarize Azure OpenAI Responses API in one sentence.",
    stream=True,
)

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

Chamada de função

A API Responses suporta chamadas de funções.

import os
import json
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="MODEL_NAME",
    tools=[
        {
            "type": "function",
            "name": "get_weather",
            "description": "Get weather for a location",
            "parameters": {
                "type": "object",
                "properties": {"location": {"type": "string"}},
                "required": ["location"],
            },
        }
    ],
    input="What is the weather in San Francisco?",
)

tool_outputs = []
for item in response.output:
    if item.type == "function_call" and item.name == "get_weather":
        args = json.loads(item.arguments)
        weather = {"location": args["location"], "temperature": "70 F"}
        tool_outputs.append(
            {
                "type": "function_call_output",
                "call_id": item.call_id,
                "output": json.dumps(weather),
            }
        )

final_response = client.responses.create(
    model="MODEL_NAME",
    previous_response_id=response.id,
    input=tool_outputs,
)

print(final_response.output_text)

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 -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": "MODEL_NAME",
        "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")
)

response = client.responses.create(
    model="MODEL_NAME",
    tools=[{"type": "code_interpreter", "container": {"type": "auto"}}],
    instructions="You are a math tutor. Write and run Python code to solve math problems.",
    input="Solve 3x + 11 = 14."
)

print(response.output_text)

Contentores

Importante

Code Interpreter tem custos adicionais além das taxas baseadas em tokens para o uso do Azure OpenAI. Se a sua API de Respostas chamar o Interpretador de Código simultaneamente em dois threads diferentes, são criadas duas sessões de interpretador de código. Cada sessão está ativa por defeito durante 1 hora, com um timeout de inatividade de 20 minutos.

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 uma chamada anterior ao interprete_de_codigo 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

Formato de ficheiro tipo de MIME
.c Texto/X-C
.cs text/x-csharp
.cpp Texto/X-C++
.csv Texto/CSV
.doc Aplicação/MSWORD
.docx application/vnd.openxmlformats-officedocument.wordprocessingml.document
.html text/html
.java Text/X-Java
.json application/json
.md Texto/Markdown
.pdf Aplicação/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 texto simples
.css text/css
.js texto/JavaScript
.sh Application/X-SH
.ts application/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

Recupera os itens de entrada que foram enviados para uma resposta. Isto é útil para inspecionar o contexto completo da conversa, incluindo quaisquer itens adicionados pelo modelo (por exemplo, chamadas de função ou itens de compactação).

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

items = client.responses.input_items.list("<response_id>")
print(items.model_dump_json(indent=2))

Resposta de exemplo

{
  "object": "list",
  "data": [
    {
      "id": "msg_...",
      "type": "message",
      "role": "user",
      "content": [{"type": "input_text", "text": "This is a test."}]
    }
  ]
}

Entrada de imagem

Modelos com visão podem interpretar imagens juntamente com texto. Podem reconhecer objetos, formas, cores e texturas, e ler texto contido numa imagem, sujeito às limitações referidas mais adiante neste artigo.

Pode fornecer uma imagem como entrada para um pedido de qualquer uma das seguintes formas:

  • Um URL totalmente qualificado para um ficheiro de imagem
  • Um URI de dados codificado em Base64
  • Um ID de ficheiro criado com a API Ficheiros

URL da imagem

Referenciar uma imagem alojada numa URL pública. O modelo recolhe a imagem e inclui-a como parte do conteúdo 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.create(
    model="MODEL_NAME",
    input=[
        {
            "role": "user",
            "content": [
                {"type": "input_text", "text": "What is in this image?"},
                {"type": "input_image", "image_url": "<image_url>"}
            ]
        }
    ]
)

print(response.output_text)

Imagem codificada em base 64

Envie uma imagem em linha codificando os seus bytes como um URI de dados base64. Usa este padrão quando a imagem não estiver alojada numa URL pública ou quando quiseres evitar uma busca extra de rede.

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("path_to_your_image.jpg", "rb") as image_file:
    base64_image = base64.b64encode(image_file.read()).decode("utf-8")

response = client.responses.create(
    model="MODEL_NAME",
    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.output_text)

ID do ficheiro

Carregue uma imagem com a API Ficheiros usando purpose="vision", e depois faça referência ao ID do ficheiro devolvido no seu pedido. Esta abordagem é útil quando se quer reutilizar a mesma imagem através de múltiplos pedidos sem reenviar os seus bytes.

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 create_file(file_path):
    with open(file_path, "rb") as file_content:
        result = client.files.create(
            file=file_content,
            purpose="vision",
        )
        return result.id

file_id = create_file("path_to_your_image.jpg")

response = client.responses.create(
    model="MODEL_NAME",
    input=[
        {
            "role": "user",
            "content": [
                {"type": "input_text", "text": "What is in this image?"},
                {"type": "input_image", "file_id": file_id},
            ],
        }
    ],
)

print(response.output_text)

Requisitos de entrada de imagem

A tabela seguinte lista os tipos de ficheiros suportados para entradas de imagem.

Tipo de ficheiro tipo de MIME
PNG image/png
JPEG image/jpeg
WebP image/webp
GIF não animado image/gif

Num único pedido, pode incluir até 100 imagens. Cada ficheiro de imagem individual deve ter menos de 50 MB, e o tamanho combinado de todas as imagens no pedido também deve ser inferior a 50 MB.

As imagens devem cumprir estes requisitos adicionais:

  • A imagem deve ser relevante para o prompt; O modelo não foi concebido para conteúdo visual não relacionado.
  • As imagens não devem conter conteúdo prejudicial ou sensível que viole as políticas de conteúdo.
  • Ficheiros de imagem não podem estar corrompidos ou ilegíveis. Se o modelo não conseguir processar uma imagem, o pedido falha.

Escolha um nível de detalhe da imagem

Use a detail propriedade numa input_image parte de conteúdo para controlar como o modelo processa a imagem. O menor detalhe usa menos tokens e é mais rápido, enquanto o maior detalhe usa mais tokens, mas permite ao modelo captar características mais finas.

{
  "type": "input_image",
  "image_url": "<image_url>",
  "detail": "high"
}

A tabela seguinte descreve cada nível de detalhe.

Nível de detalhe Descrição
low O modelo utiliza uma versão de menor resolução da imagem. Esta opção usa menos tokens e produz a resposta mais rápida, mas o modelo pode perder detalhes finos.
high O modelo utiliza uma versão da imagem de maior resolução. Esta opção capta detalhes mais finos, mas usa mais tokens e demora mais tempo a responder.
auto O padrão. O modelo seleciona o nível de detalhe apropriado com base na imagem e no prompt.

Limitações de entrada de imagem

Os modelos com capacidades de visão têm as seguintes limitações:

  • Imagens médicas: O modelo não é adequado para interpretar imagens médicas especializadas, como tomografias computorizadas, e não deve ser usado para aconselhamento médico.
  • Texto não inglês: O modelo pode não ter um desempenho ideal ao lidar com imagens que contêm texto em alfabetos não latinos, como japonês ou coreano.
  • Texto pequeno: Amplie o texto dentro de uma imagem para melhorar a legibilidade, mas evite recortar detalhes importantes.
  • Rotação: O modelo pode interpretar mal texto e imagens rotados ou invertidos.
  • Elementos visuais: O modelo pode ter dificuldades com gráficos ou texto onde as cores ou estilos — como linhas sólidas, tracejadas ou pontilhadas — variam.
  • Raciocínio espacial: O modelo tem dificuldades com tarefas que exigem localização espacial precisa, como identificar posições de xadrez.
  • Precisão: O modelo pode gerar descrições ou legendas incorretas em alguns casos.
  • Forma da imagem: O modelo tem dificuldade com imagens panorâmicas e olho de peixe.
  • Metadados e redimensionamento: O modelo não processa nomes de ficheiros originais ou metadados, e as imagens são redimensionadas antes da análise, o que afeta as suas dimensões originais.
  • Contagem: O modelo pode fornecer contagens aproximadas para objetos em imagens.
  • CAPTCHAs: Por razões de segurança, existe um sistema para bloquear a submissão de CAPTCHAs.

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.

Nota

  • Todo o texto e imagens extraídos são colocados no contexto do modelo. Certifique-se de que compreende as implicações de preços e uso de tokens ao usar PDFs como entrada.
  • Num único pedido de API, pode incluir mais do que um ficheiro, mas cada ficheiro deve ter menos de 50 MB. O limite combinado para todos os ficheiros do pedido é de 50 MB.
  • Apenas modelos que suportam tanto entrada de texto como de imagem podem aceitar ficheiros PDF como entrada.
  • Atualmente, um purpose de user_data não é suportado. Como solução temporária, terá de definir o valor de propósito para assistants.

Converter PDF para Base64 e analisar

Envie um PDF inline codificando os seus bytes como um URI de dados base64. O modelo recebe tanto o texto extraído como uma imagem renderizada de cada página.

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:
    base64_string = base64.b64encode(f.read()).decode("utf-8")

response = client.responses.create(
    model="MODEL_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 com purpose="assistants". A purpose de user_data não é atualmente suportada.

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

file = client.files.create(
    file=open("nucleus_sampling.pdf", "rb"),
    purpose="assistants"
)

response = client.responses.create(
    model="MODEL_NAME",
    input=[
        {
            "role": "user",
            "content": [
                {"type": "input_file", "file_id": file.id},
                {"type": "input_text", "text": "Summarize this PDF."},
            ],
        },
    ]
)

print(response.output_text)

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 mostra como usar um servidor MCP remoto para consultar informação sobre um repositório da API REST do Azure. O modelo recupera e raciocina sobre o conteúdo do repositório em tempo real.

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="MODEL_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.

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="MODEL_NAME",
    tools=[
        {
            "type": "mcp",
            "server_label": "github",
            "server_url": "https://contoso.com/Azure/azure-rest-api-specs",
            "require_approval": "never"
        }
    ],
    previous_response_id="<previous_response_id>",
    input=[
        {
            "type": "mcp_approval_response",
            "approve": True,
            "approval_request_id": "<approval_request_id>"
        }
    ]
)

print(response.output_text)

Autenticação

Importante

  • O cliente MCP dentro da API Respostas requer TLS 1.2 ou superior.
  • O TLS mútuo (mTLS) não é atualmente suportado.
  • As etiquetas de serviço Azure atualmente não são 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 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.

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="MODEL_NAME",
    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_MCP_TOKEN"}
        }
    ]
)

print(response.output_text)

Tarefas de fundo

O modo em segundo plano permite-lhe executar tarefas de longa duração de forma assíncrona com modelos de raciocínio como o3 e o1-pro. É útil para tarefas complexas que podem demorar vários minutos a ser concluídas (por exemplo, agentes ao estilo Codex ou Deep Research). Quando um pedido é enviado com "background": true, a tarefa é processada de forma assíncrona, e consultas periodicamente o seu estado.

Iniciar uma tarefa em segundo plano

Define background=true o pedido para colocar a tarefa em fila. O serviço retorna imediatamente com um ID de resposta e um queued estado — use esse ID para consultar, transmitir ou cancelar a tarefa.

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="MODEL_NAME",
    input="Write me a very long story.",
    background=True
)

print(response.status)

Votação para conclusão

Continue a inquirir enquanto o estado estiver queued ou in_progress. Quando a resposta atinge um estado terminal, está disponível para recuperação.

from time import sleep

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

Cancelar uma tarefa em segundo plano

Cancelar uma tarefa em segundo plano em execução através de cancel. O cancelamento é idempotente — as chamadas subsequentes devolvem o objeto de resposta final.

response = client.responses.cancel("<response_id>")
print(response.status)

Para transmitir uma resposta em segundo plano, defina ambos background e stream para true. Este padrão permite-te retomar a transmissão se a ligação cair. Acompanha a tua posição com o sequence_number de cada evento.

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

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

As respostas em segundo plano têm atualmente uma latência até ao primeiro token mais longa do que as respostas síncronas. Estão em curso melhorias para reduzir esta lacuna.

Limitações

  • O modo de fundo requer store=true. Pedidos sem estado não são suportados.
  • Só pode retomar o streaming 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

Se uma ligação de transmissão for interrompida, pode retomar a partir de um evento conhecido passando stream=true juntamente com starting_after=<sequence_number> num GET para a resposta. O serviço reproduz eventos emitidos após esse número de sequência.

curl -N -X GET "https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/responses/<response_id>?stream=true&starting_after=42" \
  -H "Content-Type: application/json" \
  -H "api-key: $AZURE_OPENAI_API_KEY"

Itens de raciocínio criptografados

Quando usa a API Respostas em modo sem estado (store=false), deve ainda preservar o contexto de raciocínio entre turnos de conversa. Para isso, inclua itens de raciocínio encriptado nos seus pedidos.

Para reter itens de raciocínio ao longo dos turnos, adicione reasoning.encrypted_content ao include parâmetro. A resposta contém depois uma versão encriptada do registo do raciocínio, que pode enviar em pedidos futuros.

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="MODEL_NAME",
    reasoning={"effort": "medium"},
    input="What is the weather like today?",
    tools=[
        # Replace with your function or tool definitions.
    ],
    include=["reasoning.encrypted_content"],
    store=False,
)

print(response.output_text)

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 Image API autónoma, a Answers API oferece duas vantagens:

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

Nota

A ferramenta de geração de imagens na API de Respostas é compatível com modelos da série gpt-image-1, e pode invocá-la a partir de um conjunto de modelos compatíveis de chat e raciocínio. Para a lista atual de modelos de orquestração suportados, consulte a secção Modelos suportados mais adiante neste artigo.

A ferramenta de geração de imagens não suporta atualmente o modo de streaming. Para transmitir imagens parciais, chame a API de geração de imagens diretamente fora da API de Respostas.

Use a API Responses para construir experiências de imagem conversacional com modelos de imagem GPT.

import base64
import os
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": os.getenv("IMAGE_MODEL_NAME"),
        "api_version": "preview",
    },
)

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

image_data = [
    output.result
    for output in response.output
    if output.type == "image_generation_call"
]

if image_data:
    with open("otter.png", "wb") as f:
        f.write(base64.b64decode(image_data[0]))

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

A utilização do computador com o Playwright foi transferida para o guia dedicado do modelo de utilização do computador.

Resolução de problemas

  • 401/403: Se estiver a usar Microsoft Entra ID, verifique se o seu token está devidamente definido para https://ai.azure.com/.default. Se usares uma chave API, confirma que estás a usar a chave correta para o recurso.
  • 404: Confirme que model corresponde ao nome da sua implementação.

Conteúdo relacionado

  • Last updated on