Uso de la API de respuestas de OpenAI de Azure

Use la API de respuestas de Azure OpenAI para generar respuestas con estado y de varios turnos. Reúne funcionalidades de completaciones de chat y de la API de asistentes en una experiencia unificada. La API de respuestas también admite el modelo que impulsa el computer-use-previewuso del equipo.

Requisitos previos

  • Un modelo de OpenAI implementado Azure.
  • Un método de autenticación:
    • Clave de API (por ejemplo, AZURE_OPENAI_API_KEY) o
    • Microsoft Entra ID (recomendado).
  • Instale la biblioteca cliente para el idioma:
    • Python: pip install openai azure-identity
    • .NET: dotnet add package OpenAI y dotnet add package Azure.Identity
    • JavaScript/TypeScript: npm install openai @azure/identity
    • Java: agregue com.openai:openai-java y com.azure:azure-identity al proyecto.
  • Para obtener ejemplos de REST, establezca AZURE_OPENAI_API_KEY (flujo de claves de API) o AZURE_OPENAI_AUTH_TOKEN (flujo de Microsoft Entra ID).

Regiones soportadas

Antes de ejecutar los ejemplos de este artículo, confirme que la región de recursos admite la API de respuestas. La API v1 es necesaria para acceder a las características más recientes; para obtener más información, consulte el ciclo de vida de la versión de la API. La API de respuestas está disponible actualmente en las siguientes regiones:

  • australiaeast
  • brazilsouth
  • canadacentral
  • Canadá Este
  • eastus
  • eastus2
  • francecentral
  • alemaniawestcentral
  • italynorth
  • japaneast
  • koreacentral
  • northcentralus
  • norwayeast
  • PolandCentral
  • southafricanorth
  • southcentralus
  • southeastasia
  • Sur de India
  • spaincentral
  • swedencentral
  • switzerlandnorth
  • uaenorth
  • uksouth
  • westus
  • westus3

Modelos compatibles

La API de respuestas admite los siguientes modelos:

  • gpt-chat-latest (Versión: 2026-05-05)
  • gpt-5.5 (Versión: 2026-04-24)
  • gpt-5.4-nano (Versión: 2026-03-17)
  • gpt-5.4-mini (Versión: 2026-03-17)
  • gpt-5.4-pro (Versión:2026-03-05)
  • gpt-5.4 (Versión:2026-03-05)
  • gpt-5.3-chat (Versión: 2026-03-03)
  • gpt-5.3-codex (Versión: 2026-02-24)
  • gpt-5.2-codex (Versión: 2026-01-14)
  • gpt-5.2 (Versión: 2025-12-11)
  • gpt-5.2-chat (Versión: 2025-12-11)
  • gpt-5.2-chat (Versión: 2026-02-10)
  • gpt-5.1-codex-max (Versión: 2025-12-04)
  • gpt-5.1 (Versión: 2025-11-13)
  • gpt-5.1-chat (Versión: 2025-11-13)
  • gpt-5.1-codex (Versión: 2025-11-13)
  • gpt-5.1-codex-mini (Versión: 2025-11-13)
  • gpt-5-pro (Versión: 2025-10-06)
  • gpt-5-codex (Versión: 2025-09-11)
  • gpt-5 (Versión: 2025-08-07)
  • gpt-5-mini (Versión: 2025-08-07)
  • gpt-5-nano (Versión: 2025-08-07)
  • gpt-5-chat (Versión: 2025-08-07)
  • gpt-5-chat (Versión: 2025-10-03)
  • gpt-5-codex (Versión: 2025-09-15)
  • gpt-4o (Versiones: 2024-11-20, 2024-08-06, 2024-05-13)
  • gpt-4o-mini (Versión: 2024-07-18)
  • computer-use-preview
  • gpt-4.1 (Versión: 2025-04-14)
  • gpt-4.1-nano (Versión: 2025-04-14)
  • gpt-4.1-mini (Versión: 2025-04-14)
  • gpt-image-1 (Versión: 2025-04-15)
  • gpt-image-1-mini (Versión: 2025-10-06)
  • gpt-image-1.5 (Versión: 2025-12-16)
  • o1 (Versión: 2024-12-17)
  • o3-mini (Versión: 2025-01-31)
  • o3 (Versión: 2025-04-16)
  • o4-mini (Versión: 2025-04-16)

No todos los modelos están disponibles en todas las regiones admitidas. Compruebe la página modelos para ver la disponibilidad de la región del modelo. Para obtener el conjunto completo de parámetros de solicitud y respuesta, consulte la documentación de referencia de la API de respuestas.

Nota

Actualmente no se admite:

  • Generación de imágenes con edición iterativa y en tiempo real.
  • Las imágenes no se pueden cargar como un archivo y, a continuación, se hace referencia a ellas como entrada.

Hay un problema conocido con lo siguiente:

  • Ahora se admite PDF como archivo de entrada, pero la configuración del propósito de carga de archivos en user_data no se admite actualmente.
  • Problemas de rendimiento cuando se usa el modo en segundo plano con streaming. Microsoft está trabajando para resolver este problema.

Generación de una respuesta de texto

Genere una respuesta de texto simple mediante la API de respuestas. Reemplace YOUR-RESOURCE-NAME y MODEL_NAME por los valores de implementación.

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

Respuesta de ejemplo

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

Recuperación de una respuesta

Recupera una respuesta mediante su ID de una llamada anterior a la API de Responses.

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

Respuesta de ejemplo

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

Eliminación de una respuesta

De forma predeterminada, los datos de respuesta se conservan durante 30 días. Elimine una respuesta almacenada por identificador.

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)

Encadenar respuestas

Encadena los turnos pasando el id. de la respuesta anterior a 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)

Encadenar respuestas manualmente

Como alternativa, puede arrastrar manualmente los elementos de salida a la siguiente solicitud.

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 una respuesta

La compactación reduce el contexto de entrada al tiempo que conserva el estado esencial para los 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 elementos devueltos

Puede compactar todos los elementos devueltos de solicitudes anteriores, como razonamiento, mensaje, llamada a función, 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 utilizando el ID de respuesta anterior

También puede comprimir usando un identificador de respuesta 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)

Compactación del lado servidor

También puede usar la compactación del lado del servidor directamente en Respuestas (POST /responses o client.responses.create) estableciendo context_management con un compact_threshold.

  • Cuando el recuento de tokens de salida supera el umbral configurado, la API de respuestas ejecuta automáticamente la compactación.
  • En este modo, no es necesario llamar /responses/compact por separado.
  • La respuesta incluye un elemento de compactación cifrado.
  • La compactación del lado del servidor funcionará si establece store=false en las solicitudes de creación de respuestas.

El elemento de compactación traslada el estado y el razonamiento esenciales del turno anterior al siguiente usando menos tokens. Es opaco y no está pensado para ser legible.

Si usa el encadenamiento de matrices de entrada sin estado, anexe los elementos de salida como de costumbre. Si está utilizando previous_response_id, pase solo el nuevo mensaje de usuario en cada turno. En ambos patrones, el objeto de compactación lleva el contexto necesario para la siguiente ventana.

Sugerencia

Después de anexar elementos de salida a los elementos de entrada anteriores, puede quitar elementos que vinieron antes del elemento de compactación más reciente para mantener las solicitudes más pequeñas y reducir la latencia de cola larga. El último elemento de compactación lleva el contexto necesario para continuar la conversación. Si usa el encadenamiento previous_response_id, no realice una eliminación manual.

Flujo

  1. Llame responses como de costumbre. Agregue context_management con compact_threshold para habilitar la compactación del lado servidor.
  2. Si la salida cruza el umbral, el servicio desencadena la compactación, emite un elemento de compactación en el flujo de salida y elimina el contexto antes de continuar la inferencia.
  3. Continúe la conversación con uno de estos patrones:
    1. Encadenamiento sin estado de matrices de entrada: añade elementos de salida, incluidos los elementos de compactado, a la siguiente matriz de entrada.
    2. Encadenamiento previous_response_id: pase solo el nuevo mensaje de usuario en cada turno y transmita el ID de respuesta más reciente.

Ejemplo

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(),
    }
  )

Transmisión en tiempo real

Transmita la respuesta a medida que se genera estableciendo stream=true. El servicio emite eventos incrementales que puede consumir para mostrar la salida, token a token.

Nota

Durante el streaming, la API de respuestas puede devolver un evento de error ( 500, 429y errores similares) si el servicio encuentra un error, como los límites del token o los problemas de análisis. Las aplicaciones deben detectar este evento y detener o reiniciar correctamente el streaming. No se le cobrarán los tokens generados durante las respuestas en tiempo real con errores.

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

Llamada a funciones

La API de respuestas admite llamadas a funciones.

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)

Intérprete de código

La herramienta De intérprete de código permite a los modelos escribir y ejecutar código Python en un entorno seguro y de espacio aislado. Admite una variedad de tareas avanzadas, entre las que se incluyen:

  • Procesamiento de archivos con formatos y estructuras de datos variados
  • Generación de archivos que incluyen datos y visualizaciones (por ejemplo, gráficos)
  • Escribir y ejecutar código iterativamente para resolver problemas: los modelos pueden depurar y reintentar código hasta que se realice correctamente.
  • Mejorar el razonamiento visual en los modelos admitidos (por ejemplo, o3, o4-mini) habilitando transformaciones de imagen como recorte, zoom y rotación
  • Esta herramienta es especialmente útil para escenarios que implican análisis de datos, cálculo matemático y generación 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)

Contenedores

Importante

El intérprete de código tiene cargos adicionales más allá de las tarifas basadas en tokens para el uso de Azure OpenAI. Si la API de respuestas llama al intérprete de código simultáneamente en dos subprocesos diferentes, se crean dos sesiones de intérprete de código. Cada sesión está activa de forma predeterminada durante 1 hora con un tiempo de espera de inactividad de 20 minutos.

La herramienta del intérprete de código requiere un contenedor: una máquina virtual totalmente aislada donde el modelo puede ejecutar código Python. Los contenedores pueden incluir archivos cargados o archivos generados durante la ejecución.

Para crear un contenedor, especifique "container": { "type": "auto", "file_ids": ["file-1", "file-2"] } en la configuración de la herramienta al crear un nuevo objeto Response. Esto crea automáticamente un nuevo contenedor o reutiliza uno activo de un code_interpreter_call anterior en el contexto del modelo. El code_interpreter_call en la salida de la API contendrá el container_id que se generó. Este contenedor expira si no se usa durante 20 minutos.

Entradas y salidas de archivo

Al ejecutar el intérprete de código, el modelo puede crear sus propios archivos. Por ejemplo, si le pide que construya un trazado o cree un CSV, crea estas imágenes directamente en el contenedor. Citará estos archivos en las anotaciones de su siguiente mensaje.

Los archivos de la entrada del modelo se cargan automáticamente en el contenedor. No es necesario cargarlo explícitamente en el contenedor.

Archivos admitidos

Formato de archivo Tipo MIME
.c text/x-c
.cs text/x-csharp
.cpp text/x-c++
.csv text/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 text/JavaScript
.sh application/x-sh
.ts application/TypeScript
.csv application/csv
.jpeg image/jpeg
.jpg image/jpeg
.gif imagen/GIF
.pkl application/octet-stream
.png image/png
.tar application/x-tar
.xlsx application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
.xml application/xml o "text/xml"
.zip application/zip

Enumerar elementos de entrada

Recupera los elementos de entrada que se enviaron en una respuesta. Esto resulta útil para inspeccionar el contexto completo de la conversación, incluidos los elementos añadidos por el modelo (por ejemplo, llamadas a funciones o elementos de compactación).

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

Respuesta de ejemplo

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

Entrada de imagen

Los modelos habilitados para visión pueden interpretar imágenes junto con texto. Pueden reconocer objetos, formas, colores y texturas, y leer texto contenido dentro de una imagen, sujeto a las limitaciones enumeradas más adelante en este artículo.

Puede proporcionar una imagen como entrada a una solicitud de cualquiera de las maneras siguientes:

  • Una URL completa de un archivo de imagen
  • Un URI de datos codificados en Base64
  • Un identificador de archivo creado con la API de archivos

URL de imagen

Haga referencia a una imagen hospedada en una dirección URL pública. El modelo captura la imagen e la incluye como parte del contenido 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)

Imagen codificada en Base64

Envíe una imagen en línea codificando sus bytes como URI de datos en base64. Use este patrón cuando la imagen no esté hospedada en una dirección URL pública o cuando desee evitar una captura de red adicional.

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 de archivo

Cargue una imagen con la API de archivos mediante purpose="vision"y, a continuación, haga referencia al identificador de archivo devuelto en la solicitud. Este enfoque es útil cuando desea reutilizar la misma imagen en varias solicitudes sin volver a enviar sus 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 imagen

En la tabla siguiente se enumeran los tipos de archivo admitidos para las entradas de imagen.

Tipo de archivo Tipo MIME
PNG image/png
JPEG image/jpeg
WebP image/webp
GIF no animado image/gif

En una sola solicitud, puede incluir hasta 100 imágenes. Cada archivo de imagen individual debe tener menos de 50 MB y el tamaño combinado de todas las imágenes de la solicitud también debe tener menos de 50 MB.

Las imágenes deben cumplir estos requisitos adicionales:

  • La imagen debe ser relevante para el mensaje; el modelo no está diseñado para contenido visual no relacionado.
  • Las imágenes no deben contener contenido dañino o confidencial que infrinja las directivas de contenido.
  • Los archivos de imagen no pueden estar dañados ni ser ilegibles. Si el modelo no puede procesar una imagen, se produce un error en la solicitud.

Elección de un nivel de detalle de imagen

Use la detail propiedad de un input_image elemento de contenido para controlar cómo procesa el modelo la imagen. Los detalles más bajos usan menos tokens y son más rápidos, mientras que los detalles más altos usan más tokens, pero permite que el modelo capture características más finas.

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

En la tabla siguiente se describe cada nivel de detalle.

Nivel de detalle Description
low El modelo usa una versión de resolución inferior de la imagen. Esta opción usa los tokens más pequeños y genera la respuesta más rápida, pero el modelo podría perder detalles finos.
high El modelo usa una versión de resolución superior de la imagen. Esta opción captura detalles más finos, pero usa más tokens y tarda más tiempo en responder.
auto El valor predeterminado. El modelo selecciona el nivel de detalle adecuado en función de la imagen y de la instrucción.

Limitaciones de entrada de imagen

Los modelos habilitados para Vision tienen las siguientes limitaciones:

  • Imágenes médicas: el modelo no es adecuado para interpretar imágenes médicas especializadas como exámenes ct y no debe usarse para asesoramiento médico.
  • Texto no en inglés: es posible que el modelo no funcione de forma óptima al controlar imágenes que contienen texto en alfabetos no latinos, como japonés o coreano.
  • Texto pequeño: amplíe el texto dentro de una imagen para mejorar la legibilidad, pero evite recortar detalles importantes.
  • Rotación: el modelo podría interpretar mal el texto y las imágenes giradas o al revés.
  • Elementos visuales: el modelo puede tener problemas con gráficos o texto en los que los colores o estilos (como líneas de puntos, discontinuos o sólidos) varían.
  • Razonamiento espacial: el modelo tiene dificultades con tareas que requieren localización espacial precisa, como la identificación de posiciones de ajedrez.
  • Precisión: el modelo puede generar descripciones o subtítulos incorrectos en algunos casos.
  • Forma de imagen: el modelo tiene dificultades con imágenes panorámicas y de ojo de pez.
  • Metadatos y cambio de tamaño: el modelo no procesa los nombres de archivo originales ni los metadatos, y las imágenes se cambian de tamaño antes del análisis, lo que afecta a sus dimensiones originales.
  • Recuento: el modelo puede proporcionar recuentos aproximados de objetos en imágenes.
  • CAPTCHAs: Por motivos de seguridad, se aplica un sistema para bloquear el envío de CAPTCHAs.

Entrada de archivo

Los modelos con funcionalidades de visión admiten la entrada pdf. Los archivos PDF se pueden proporcionar como datos codificados en Base64 o como identificadores de archivo. Para ayudar a los modelos a interpretar el contenido PDF, tanto el texto extraído como una imagen de cada página se incluyen en el contexto del modelo. Esto resulta útil cuando la información clave se transmite a través de diagramas o contenido no textual.

Nota

  • Todo el texto extraído y las imágenes se colocan en el contexto del modelo. Asegúrese de conocer bien cómo funciona el uso de tokens y los precios por usar archivos PDF como datos de entrada.
  • En una única solicitud de API, puede incluir más de un archivo, pero cada archivo debe tener menos de 50 MB. El límite combinado en todos los archivos de la solicitud es de 50 MB.
  • Solo los modelos que admiten entradas de texto e imagen pueden aceptar archivos PDF como entrada.
  • Actualmente, no se admite purpose de user_data. Como solución temporal, deberá establecer el propósito en assistants.

Conversión de PDF a Base64 y análisis

Envíe un PDF integrado codificando sus bytes en un URI de datos en base64. El modelo recibe tanto el texto extraído como una imagen representada 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)

Carga de PDF y análisis

Cargue el archivo PDF con purpose="assistants". Actualmente no se admite un purpose de user_data .

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)

Uso de servidores MCP remotos

Puede ampliar las funcionalidades del modelo mediante la conexión a herramientas hospedadas en servidores remotos del Protocolo de contexto de modelo (MCP). Los desarrolladores y las organizaciones mantienen estos servidores y exponen herramientas a las que pueden acceder los clientes compatibles con MCP, como la API de respuestas.

El Protocolo de contexto de modelo (MCP) es un estándar abierto que define cómo las aplicaciones proporcionan herramientas y datos contextuales a modelos de lenguaje grandes (LLM). Permite una integración coherente y escalable de herramientas externas en flujos de trabajo de modelo.

En el ejemplo siguiente se muestra cómo usar un servidor MCP remoto para consultar información sobre un repositorio de API REST de Azure. El modelo recupera y razona sobre el contenido del repositorio en tiempo 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)

La herramienta MCP solo funciona en la API de respuestas y está disponible en todos los modelos más recientes (gpt-4o, gpt-4.1 y nuestros modelos de razonamiento). Cuando se usa la herramienta MCP, solo se pagan los tokens que se usan al importar definiciones de herramientas o realizar llamadas a herramientas, no hay cargos adicionales.

Aprobaciones

De forma predeterminada, la API de respuestas requiere aprobación explícita antes de que los datos se compartan con un servidor MCP remoto. Este paso de aprobación ayuda a garantizar la transparencia y le proporciona control sobre qué información se envía externamente.

Se recomienda revisar todos los datos que se comparten con servidores MCP remotos y, opcionalmente, registrarlos con fines de auditoría.

Cuando se requiere una aprobación, el modelo devuelve un mcp_approval_request elemento en la salida de la respuesta. Este objeto contiene los detalles de la solicitud pendiente y permite inspeccionar o modificar los datos antes de continuar.

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

Para continuar con la llamada a MCP remota, debe responder a la solicitud de aprobación mediante la creación de un nuevo objeto de respuesta que incluya un elemento de mcp_approval_response. Este objeto confirma la intención de permitir que el modelo envíe los datos especificados al 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)

Autenticación

Importante

  • El cliente MCP dentro de la API de respuestas requiere TLS 1.2 o posterior.
  • Actualmente no se admite TLS mutua (mTLS).
  • Etiquetas de servicio de Azure no están actualmente admitidas para el tráfico de cliente MCP.

A diferencia del GitHub servidor MCP, la mayoría de los servidores MCP remotos requieren autenticación. La herramienta MCP de la API de respuestas admite encabezados personalizados, lo que le permite conectarse de forma segura a estos servidores mediante el esquema de autenticación que requieren.

Puede especificar encabezados como claves de API, tokens de acceso de OAuth u otras credenciales directamente en la solicitud. El encabezado más usado es el Authorization encabezado .

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)

Tareas en segundo plano

El modo en segundo plano permite ejecutar tareas de ejecución prolongada de forma asincrónica con modelos de razonamiento como o3 y o1-pro. Resulta útil para las tareas complejas que pueden tardar varios minutos en completarse (por ejemplo, agentes de estilo de Códice o Deep Research). Cuando se envía una solicitud con "background": true, la tarea se procesa de forma asincrónica y se sondea su estado.

Iniciar una tarea en segundo plano

Establezca background=true en la solicitud para poner en cola la tarea. El servicio devuelve de inmediato un id. de respuesta y un estado queued: use ese identificador para sondear, recibir en streaming o cancelar la tarea.

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)

Sondear la finalización

Continúe sondeando mientras el estado es queued o in_progress. Una vez que la respuesta alcanza un estado terminal, está disponible para su recuperación.

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 una tarea en segundo plano

Cancela una tarea en segundo plano en curso con el punto de conexión cancel. El proceso de cancelación es de efecto único (idempotente): las llamadas posteriores devolverán el objeto de la respuesta final.

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

Para transmitir una respuesta en segundo plano, establezca tanto background como stream en true. Este patrón le permite reanudar el streaming si se quita la conexión. Siga su posición con sequence_number desde 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"]

Actualmente, las respuestas en segundo plano tienen una latencia de tiempo a primer token mayor que las respuestas sincrónicas. Se están llevando a cabo mejoras para reducir esta brecha.

Limitaciones

  • El modo en segundo plano requiere store=true. No se admiten solicitudes sin estado.
  • Solo puede reanudar el streaming si la solicitud original incluía stream=true.
  • Para cancelar una respuesta sincrónica, finalice la conexión directamente.

Reanudación del streaming desde un punto específico

Si se interrumpe una conexión de streaming, puede reanudarla desde un evento conocido pasando stream=true junto con starting_after=<sequence_number> en la respuesta a una GET. El servicio reproduce los eventos emitidos después de ese número de secuencia.

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"

Elementos de razonamiento cifrados

Al usar la API de respuestas en modo sin estado (store=false), debe conservar el contexto de razonamiento entre turnos de conversación. Para ello, incluya elementos de razonamiento cifrados en las solicitudes.

Para conservar los elementos de razonamiento entre turnos, agregue reasoning.encrypted_content al include parámetro . La respuesta contiene entonces una versión cifrada de la traza de razonamiento, que puede incluir en futuras solicitudes.

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)

La API de respuestas habilita la generación de imágenes como parte de conversaciones y flujos de trabajo de varios pasos. Admite entradas y salidas de imagen dentro del contexto, e incluye herramientas integradas para generar y editar imágenes.

En comparación con la API de imágenes independiente, la API de respuestas ofrece dos ventajas:

  • Streaming: muestra salidas parciales de imágenes durante la generación para mejorar la latencia percibida.
  • Entradas flexibles: acepte identificadores de archivo de imagen como entradas además de bytes de imagen sin procesar.

Nota

La herramienta de generación de imágenes de la Responses API es compatible con modelos de la serie gpt-image-1, y puedes invocarla desde un conjunto de modelos de chat y de razonamiento compatibles. Para obtener la lista actual de modelos de orquestación admitidos, consulte la sección Modelos admitidos más adelante en este artículo.

La herramienta de generación de imágenes no admite actualmente el modo de streaming. Para transmitir imágenes parciales, llame a la API de generación de imágenes directamente fuera de la API de respuestas.

Use la API de respuestas para crear experiencias de imagen conversacional con modelos de imagen 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 razonamiento

Para obtener ejemplos de cómo usar modelos de razonamiento con la API de respuestas, consulte la guía de modelos de razonamiento.

Uso del equipo

El uso del ordenador con Playwright se ha trasladado a la guía específica del modelo de uso del ordenador.

Solución de problemas

  • 401/403: si usa Microsoft Entra ID, compruebe que el token está en el ámbito de https://ai.azure.com/.default. Si usa una clave de API, confirme que usa la clave correcta para el recurso.
  • 404: Confirme que model coincide con el nombre de la implementación.

Contenido relacionado

  • Last updated on