Verwenden der Azure OpenAI-Antwort-API

Verwenden Sie die Azure OpenAI-Antwort-API, um zustandsbehaftete, mehrstufige Dialogantworten zu generieren. Es vereint Funktionen von Chatabschlussen und der Assistenten-API in einer einheitlichen Benutzeroberfläche. Die Antwort-API unterstützt auch das computer-use-preview Modell, das die Computernutzung ermöglicht.

Voraussetzungen

  • Ein bereitgestelltes Azure OpenAI-Modell.
  • Eine Authentifizierungsmethode:
    • API-Schlüssel (z. B AZURE_OPENAI_API_KEY. ) oder
    • Microsoft Entra ID (empfohlen).
  • Installieren Sie die Clientbibliothek für Ihre Sprache:
    • Python: pip install openai azure-identity
    • .NET: dotnet add package OpenAI und dotnet add package Azure.Identity
    • JavaScript/TypeScript: npm install openai @azure/identity
    • Java: Fügen Sie ihrem Projekt com.openai:openai-java und com.azure:azure-identity hinzu.
  • Legen Sie für REST-Beispiele AZURE_OPENAI_API_KEY (API-Schlüsselfluss) oder AZURE_OPENAI_AUTH_TOKEN (Microsoft Entra ID Flow) fest.

Unterstützte Regionen

Bevor Sie die Beispiele in diesem Artikel ausführen, vergewissern Sie sich, dass Ihre Ressourcenregion die Antwort-API unterstützt. Die v1-API ist erforderlich, um auf die neuesten Features zuzugreifen – ausführliche Informationen finden Sie im API-Versionslebenszyklus. Die Antwort-API ist derzeit in den folgenden Regionen verfügbar:

  • australiaeast
  • brazilsouth
  • kanadacentral
  • canadaeast
  • eastus
  • Eastus2
  • francecentral
  • Deutschland Westzentral
  • Norditalien
  • japaneast
  • koreacentral
  • Northcentralus
  • norwayeast
  • Polenzentral
  • südafricanorth
  • southcentralus
  • Südostasien
  • Südindien
  • spaniencentral
  • schwedencentral
  • schweiznord
  • uaenorth
  • uksouth
  • Westus
  • westus3

Unterstützte Modelle

Die Antwort-API unterstützt die folgenden Modelle:

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

Nicht jedes Modell ist in jeder unterstützten Region verfügbar. Überprüfen Sie die Modellseite auf die Verfügbarkeit von Modellregionen. Den vollständigen Satz von Anforderungs- und Antwortparametern finden Sie in der Referenzdokumentation zur Antwort-API.

Hinweis

Derzeit nicht unterstützt:

  • Bildgenerierung mit Multi-Turn-Bearbeitung und Streaming.
  • Bilder können nicht als Datei hochgeladen und dann als Eingabe referenziert werden.

Es gibt ein bekanntes Problem bei den folgenden:

  • PDF als Eingabedatei wird jetzt unterstützt, das Festlegen des Dateiuploadzwecks user_data wird jedoch zurzeit nicht unterstützt.
  • Leistungsprobleme, wenn der Hintergrundmodus beim Streaming verwendet wird. Microsoft arbeitet daran, dieses Problem zu beheben.

Generieren einer Textantwort

Generieren Sie eine einfache Textantwort mithilfe der Antwort-API. Ersetzen Sie YOUR-RESOURCE-NAME und MODEL_NAME durch Ihre Werte für die Bereitstellung.

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

Beispielantwort

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

Abrufen einer Antwort

Rufen Sie eine Antwort anhand ihrer ID aus einem vorherigen Antwort-API-Aufruf ab.

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

Beispielantwort

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

Löschen einer Antwort

Standardmäßig werden Antwortdaten 30 Tage lang aufbewahrt. Löschen Sie eine gespeicherte Antwort über die 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)

Verketten von Antworten

Verketten Sie die Antworten, indem Sie die vorherige Antwort-ID an previous_response_id übergeben.

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)

Manuelles Verketten von Antworten

Alternativ können Sie ausgabeelemente manuell in der nächsten Anforderung weiterleiten.

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

Komprimen einer Antwort

Durch die Verdichtung wird der Eingabekontext reduziert, wobei der für spätere Züge essentielle Status erhalten bleibt.

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)

Komprimieren mit zurückgegebenen Elementen

Sie können alle Elemente komprimieren, die von vorherigen Anforderungen zurückgegeben werden, wie Begründung, Nachricht, Funktionsaufruf usw.

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)

Komprimieren mit vorheriger Antwort-ID

Sie können auch eine vorherige Antwort-ID komprimieren.

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)

Serverseitige Komprimierung

Sie können auch die serverseitige Komprimierung direkt in den Antworten (POST /responses oder client.responses.create) verwenden, indem Sie context_management mit einem compact_threshold einstellen.

  • Wenn die Anzahl des Ausgabetokens den konfigurierten Schwellenwert überschreitet, wird die Antwort-API automatisch komprimiert.
  • In diesem Modus müssen Sie nicht separat anrufen /responses/compact .
  • Die Antwort enthält ein verschlüsseltes Komprimierungselement.
  • Die serverseitige Verdichtung funktioniert, wenn Sie store=false auf Ihren Anfragen zum Erstellen von Requests festlegen.

Das Komprimierungselement überträgt den wesentlichen vorherigen Zustand und die Argumentation in den nächsten Durchlauf, indem es weniger Token verwendet. Es ist undurchsichtig und nicht dafür vorgesehen, von Menschen gelesen zu werden.

Wenn Sie die stateless Input-Array-Verkettung verwenden, fügen Sie Ausgabeelemente wie üblich an. Wenn Sie previous_response_id verwenden, übergeben Sie bei jedem Vorgang nur die neue Benutzernachricht. Bei beiden Strukturierungen enthält das Verdichtungselement den für das nächste Fenster erforderlichen Kontext.

Tipp

Nachdem Sie Ausgabeelemente an die vorherigen Eingabeelemente angefügt haben, können Sie Elemente, die vor dem letzten Verdichtungselement aufgetreten sind, ablegen, um die Anforderungen kleiner zu halten und die Longtail-Latenz zu verringern. Das letzte Verdichtungselement enthält den notwendigen Kontext, um die Kommunikation fortzusetzen. Wenn Sie die previous_response_id-Verkettung verwenden, sollten Sie nicht manuell kürzen.

Flow

  1. Rufen Sie responses wie gewohnt an. Fügen Sie context_management mit compact_threshold hinzu, um die serverseitige Komprimierung zu aktivieren.
  2. Wenn die Ausgabe den Schwellenwert überschreitet, löst der Dienst die Komprimierung aus, emittiert ein Komprimierungselement im Ausgabedatenstrom und schneidet den Kontext ab, bevor die Rückschlüsse fortgesetzt werden.
  3. Führen Sie die Unterhaltung mit einem der folgenden Muster aus:
    1. Zustandslose Verkettung von Eingabearrays: Anhängen von Ausgabeelementen, einschließlich Kompaktierungselementen, an das nächste Eingabearray.
    2. previous_response_id Verkettung: Übergeben Sie bei jedem Turn nur die neue Nachricht des Benutzers und übermitteln Sie die letzte Antwort-ID.

Beispiel

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

Streamen Sie die Antwort so, wie sie durch Festlegen stream=truegeneriert wird. Der Dienst sendet inkrementelle Ereignisse, die Sie verarbeiten können, um die Ausgabe Token für Token zu rendern.

Hinweis

Während des Streamings gibt die Responses-API möglicherweise ein Fehlerereignis (500, 429 und ähnliche Fehler) zurück, wenn im Dienst ein Fehler auftritt, z. B. Token-Beschränkungen oder Analyseprobleme. Anwendungen sollten dieses Ereignis erkennen und Streaming ordnungsgemäß beenden oder neu starten. Token, die bei fehlgeschlagenen Streamingantworten generiert wurden, werden ihnen nicht in Rechnung gestellt.

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

Funktionsaufrufe

Die Antwort-API unterstützt Funktionsaufrufe.

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)

Codedolmetscher

Mit dem Codedolmetschertool können Modelle Python Code in einer sicheren Sandkastenumgebung schreiben und ausführen. Es unterstützt eine Reihe erweiterter Aufgaben, einschließlich:

  • Verarbeiten von Dateien mit unterschiedlichen Datenformaten und Strukturen
  • Generieren von Dateien, die Daten und Visualisierungen enthalten (z. B. Diagramme)
  • Iteratives Schreiben und Ausführen von Code zum Beheben von Problemen – Modelle können Code debuggen und wiederholen, bis die Ausführung erfolgreich war.
  • Verbessern der visuellen Begründung in unterstützten Modellen (z. B. o3, o4-mini) durch Aktivieren von Bildtransformationen wie Zuschneiden, Zoomen und Drehung
  • Dieses Tool eignet sich besonders für Szenarien mit Datenanalyse, mathematischer Berechnung und Codegenerierung.
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)

Container

Wichtig

Code Interpreter verfügt über zusätzliche Gebühren, die über die tokenbasierten Gebühren für Azure OpenAI-Nutzung hinausgehen. Wenn Ihre Antwort-API Code-Interpreter gleichzeitig in zwei verschiedenen Threads aufruft, werden zwei Codedolmetschersitzungen erstellt. Jede Sitzung ist standardmäßig für 1 Stunde mit einem Leerlauftimeout von 20 Minuten aktiv.

Das Code-Interpreter-Tool erfordert einen Container – einen vollständig sandkastenbasierten virtuellen Computer, auf dem das Modell Python Code ausführen kann. Container können hochgeladene Dateien oder Dateien enthalten, die während der Ausführung generiert wurden.

Geben Sie zum Erstellen eines Containers in der Toolkonfiguration "container": { "type": "auto", "file_ids": ["file-1", "file-2"] } beim Erstellen eines neuen Antwortobjekts an. Dadurch wird automatisch ein neuer Container erstellt oder ein aktiver Container aus einem vorherigen code_interpreter_call im Kontext des Modells wiederverwendet. code_interpreter_call in der Ausgabe der API enthält das generierte container_id-Element. Dieser Container läuft ab, wenn er 20 Minuten nicht verwendet wird.

Dateieingaben und -ausgaben

Beim Ausführen des Codedolmetschers kann das Modell eigene Dateien erstellen. Wenn Sie z. B. aufgefordert werden, eine Zeichnung zu erstellen oder eine CSV-Datei zu erstellen, werden diese Images direkt in Ihrem Container erstellt. Sie wird diese Dateien in den Anmerkungen der nächsten Nachricht zitieren.

Alle Dateien in der Modelleingabe werden automatisch in den Container hochgeladen. Sie müssen sie nicht explizit in den Container hochladen.

Unterstützte Dateien

Dateiformat MIME-Typ
.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 anwendung/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 Textdatei/Klartext
.css text/css
.js text/JavaScript
.sh application/x-sh
.ts application/TypeScript
.csv application/csv
.jpeg image/jpeg
.jpg image/jpeg
.gif Bild/GIF
.pkl application/octet-stream
.png Bild/PNG
.tar application/x-tar
.xlsx application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
.xml application/xml oder "text/xml"
.zip application/zip

Listeneingabeelemente

Rufen Sie die Eingabeelemente ab, die an eine Antwort gesendet wurden. Dies ist nützlich, um den vollständigen Unterhaltungskontext zu untersuchen, einschließlich aller Elemente, die vom Modell hinzugefügt wurden (z. B. Funktionsaufrufe oder Komprimierungselemente).

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

Beispielantwort

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

Bildeingabe

Für visionsfähige Modelle sind unterstützte Bildformate PNG, JPEG und WebP.

Bild-URL

Verweisen Sie auf ein Bild, das unter einer öffentlichen URL gehostet wird. Das Modell ruft das Bild ab und enthält es als Teil des Eingabeinhalts.

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)

Base64-codiertes Bild

Senden Sie ein Bild inline, indem Sie seine Bytes als Base64-Daten-URI codieren. Verwenden Sie dieses Muster, wenn das Bild nicht unter einer öffentlichen URL gehostet wird oder wenn Sie einen zusätzlichen Netzwerkabruf vermeiden möchten.

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)

Dateieingabe

Modelle mit Vision-Funktionen unterstützen die PDF-Eingabe. PDF-Dateien können entweder als Base64-codierte Daten oder als Datei-IDs bereitgestellt werden. Damit Modelle PDF-Inhalte interpretieren können, sind sowohl der extrahierte Text als auch ein Bild jeder Seite im Kontext des Modells enthalten. Dies ist nützlich, wenn wichtige Informationen über Diagramme oder nicht textbezogene Inhalte vermittelt werden.

Hinweis

  • Alle extrahierten Texte und Bilder werden in den Kontext des Modells eingefügt. Stellen Sie sicher, dass Sie die Auswirkungen der Preis- und Tokennutzung bei der Verwendung von PDFs als Eingabe verstehen.
  • In einer einzelnen API-Anforderung sollte sich die Größe von Inhalten, die über mehrere Eingaben (Dateien) hochgeladen wurden, innerhalb der Kontextlänge des Modells befinden.
  • Nur Modelle, die Sowohl Text- als auch Bildeingaben unterstützen, können PDF-Dateien als Eingabe akzeptieren.
  • Ein purpose von user_data wird momentan nicht unterstützt. Als temporäre Problemumgehung müssen Sie Zweck auf assistants festlegen.

Konvertieren von PDF in Base64 und Analysieren

Senden Sie eine PDF-Inline, indem Sie ihre Bytes als Base64-Daten-URI codieren. Das Modell empfängt sowohl den extrahierten Text als auch ein gerendertes Bild jeder Seite.

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)

PDF hochladen und analysieren

Laden Sie die PDF-Datei mit purpose="assistants". Ein purpose von user_data wird derzeit nicht unterstützt.

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)

Verwenden von Remote-MCP-Servern

Sie können die Funktionen Ihres Modells erweitern, indem Sie es mit Tools verbinden, die auf McP-Servern (Remote Model Context Protocol) gehostet werden. Diese Server werden von Entwicklern und Organisationen verwaltet und stellen Tools bereit, auf die von MCP-kompatiblen Clients zugegriffen werden kann, z. B. die Antwort-API.

Model Context Protocol (MCP) ist ein offener Standard, der definiert, wie Anwendungen Tools und Kontextdaten für große Sprachmodelle (LLMs) bereitstellen. Sie ermöglicht eine konsistente, skalierbare Integration externer Tools in Modellworkflows.

Das folgende Beispiel zeigt, wie Sie mithilfe eines MCP-Remoteservers Informationen zu einem Azure REST-API-Repository abfragen. Das Modell ruft Repository-Inhalte in Echtzeit ab und analysiert sie.

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)

Das MCP-Tool funktioniert nur in der Antwort-API und ist in allen neueren Modellen verfügbar (gpt-4o, gpt-4.1 und unsere Begründungsmodelle). Wenn Sie das MCP-Tool verwenden, zahlen Sie nur für Token, die beim Importieren von Tooldefinitionen oder Beim Tätigen von Toolaufrufen verwendet werden– es sind keine zusätzlichen Gebühren beteiligt.

Zulassungen

Standardmäßig erfordert die Antwort-API eine explizite Genehmigung, bevor Daten für einen Remote-MCP-Server freigegeben werden. Dieser Genehmigungsschritt trägt dazu bei, Transparenz zu gewährleisten und Ihnen die Kontrolle darüber zu geben, welche Informationen extern gesendet werden.

Es wird empfohlen, alle Daten zu überprüfen, die für Remote-MCP-Server freigegeben werden, und optional die Daten für Überwachungszwecke zu protokollieren.

Wenn eine Genehmigung erforderlich ist, gibt das Modell ein mcp_approval_request Element in der Antwortausgabe zurück. Dieses Objekt enthält die Details der ausstehenden Anforderung und ermöglicht es Ihnen, die Daten zu prüfen oder zu ändern, bevor Sie fortfahren.

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

Um mit dem Remote-MCP-Aufruf fortzufahren, müssen Sie auf die Genehmigungsanforderung reagieren, indem Sie ein neues Antwortobjekt erstellen, das ein mcp_approval_response Element enthält. Dieses Objekt bestätigt, dass das Modell die angegebenen Daten an den Remote-MCP-Server senden kann.

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)

Authentifizierung

Wichtig

  • Der MCP-Client innerhalb der Antwort-API erfordert TLS 1.2 oder höher.
  • Mutual TLS (mTLS) wird derzeit nicht unterstützt.
  • Azure Diensttags werden derzeit für MCP-Clientdatenverkehr nicht unterstützt.

Im Gegensatz zum GitHub MCP-Servers erfordern die meisten REMOTE-MCP-Server eine Authentifizierung. Das MCP-Tool in der Antwort-API unterstützt benutzerdefinierte Header, sodass Sie mithilfe des erforderlichen Authentifizierungsschemas sicher eine Verbindung mit diesen Servern herstellen können.

Sie können Header wie API-Schlüssel, OAuth-Zugriffstoken oder andere Anmeldeinformationen direkt in Ihrer Anforderung angeben. Die am häufigsten verwendete Kopfzeile ist die Authorization Kopfzeile.

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)

Hintergrundaufgaben

Im Hintergrundmodus können Sie lang laufende Aufgaben asynchron mit Reasoning-Modellen wie o3 und o1-pro ausführen. Es ist nützlich für komplexe Aufgaben, die mehrere Minuten dauern können, bis sie abgeschlossen sind (z. B. Codex- oder Deep Research-Style-Agents). Wenn eine Anfrage mit "background": true gesendet wird, wird die Aufgabe asynchron verarbeitet, und Sie fragen ihren Status per Polling ab.

Starten einer Hintergrundaufgabe

Legen Sie background=true in der Anfrage fest, um die Aufgabe in die Warteschlange einzureihen. Der Dienst wird sofort mit einer Antwort-ID und einem queued Status zurückgegeben – verwenden Sie diese ID, um die Aufgabe abzufragen, zu streamen oder abzubrechen.

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)

Umfrage zum Abschluss

Die Abfrage fortsetzen, während der Status ist queued oder in_progress. Sobald die Antwort einen Terminalzustand erreicht hat, steht sie für den Abruf zur Verfügung.

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

Abbrechen einer Hintergrundaufgabe

Brechen Sie eine laufende Hintergrundaufgabe über den cancel-Endpunkt ab. Das Abbrechen ist idempotent: Nachfolgende Aufrufe geben das finale Antwortobjekt zurück.

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

Um eine Antwort im Hintergrund zu streamen, legen Sie sowohl background als auch stream auf true fest. Mit diesem Muster können Sie das Streaming fortsetzen, wenn die Verbindung abbricht. Verfolgen Sie Ihre Position bei jedem Ereignis mit dem sequence_number.

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

Hintergrundantworten haben derzeit eine höhere Zeit-bis-zum-ersten-Token-Latenz als synchrone Antworten. Verbesserungen sind im Gange, um diese Lücke zu verringern.

Einschränkungen

  • Der Hintergrundmodus erfordert store=true. Statuslose Anforderungen werden nicht unterstützt.
  • Sie können das Streaming nur fortsetzen, wenn die ursprüngliche Anfrage stream=true enthält.
  • Um eine synchrone Antwort abzubrechen, beenden Sie die Verbindung direkt.

Fortsetzen des Streamings von einem bestimmten Punkt

Wenn eine Streamingverbindung abbricht, können Sie die Verarbeitung ab einem bekannten Ereignis fortsetzen, indem Sie stream=true zusammen mit starting_after=<sequence_number> in einer GET an die Antwort übergeben. Der Dienst spielt Ereignisse erneut ab, die nach dieser Sequenznummer ausgegeben wurden.

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"

Verschlüsselte Begründungselemente

Wenn Sie die Responses API im zustandslosen Modus (store=false) verwenden, müssen Sie den Argumentationskontext dennoch über mehrere Gesprächsrunden hinweg beibehalten. Fügen Sie dazu verschlüsselte Begründungselemente in Ihre Anforderungen ein.

Um Reasoning-Elemente über mehrere Turns hinweg beizubehalten, fügen Sie reasoning.encrypted_content zum Parameter include hinzu. Die Antwort enthält dann eine verschlüsselte Version der Begründungsablaufverfolgung, die Sie an zukünftige Anforderungen übergeben können.

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)

Die Antwort-API ermöglicht die Bildgenerierung als Teil von Unterhaltungen und mehrstufigen Workflows. Es unterstützt Bildeingaben und -ausgaben im Kontext und enthält integrierte Tools zum Generieren und Bearbeiten von Bildern.

Im Vergleich zur eigenständigen Image-API bietet die Antwort-API zwei Vorteile:

  • Streaming: Teilbilder werden während der Erzeugung angezeigt, um die wahrgenommene Latenz zu verbessern.
  • Flexible Eingaben: Akzeptieren Sie Bilddatei-IDs als Eingaben zusätzlich zu unformatierten Bildbytes.

Hinweis

Das Bildgenerierungstool in der Responses API wird von Modellen der gpt-image-1-Serie unterstützt, und Sie können es mit einer Reihe kompatibler Chat- und Reasoning-Modelle aufrufen. Die aktuelle Liste der unterstützten Orchestrierungsmodelle finden Sie im Abschnitt " Unterstützte Modelle " weiter unten in diesem Artikel.

Das Tool zur Bildgenerierung unterstützt derzeit keinen Streamingmodus. Rufen Sie die Bildgenerierungs-API direkt außerhalb der Antwort-API auf, um Teilbilder zu streamen.

Verwenden Sie die Antwort-API, um Unterhaltungsbilderfahrungen mit GPT-Imagemodellen zu erstellen.

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

Reasoning-Modelle

Beispiele für die Verwendung von Begründungsmodellen mit der Antwort-API finden Sie im Leitfaden zu Gründendenmodellen.

Computerverwendung

Die Computernutzung mit Playwright wurde in die Anleitung für Modelle mit dedizierter Computernutzung verschoben.

Problembehandlung

  • 401/403: Wenn Sie Microsoft Entra ID verwenden, überprüfen Sie, ob Ihr Token auf https://ai.azure.com/.default festgelegt ist. Wenn Sie einen API-Schlüssel verwenden, bestätigen Sie, dass Sie den richtigen Schlüssel für die Ressource verwenden.
  • 404: Überprüfen Sie, ob model mit Ihrem Bereitstellungsnamen übereinstimmt.

Verwandte Inhalte

  • Last updated on