Usare l'API Risposte OpenAI Azure

Usare l'API delle risposte di Azure OpenAI per generare risposte con stato a più turni. Riunisce le funzionalità dai completamenti della chat e dall'API degli Assistenti in un'unica esperienza. L'API Risposte supporta anche il modello che supporta computer-use-preview del computer.

Prerequisiti

  • Un modello Azure OpenAI distribuito.
  • Metodo di autenticazione:
    • Chiave API (ad esempio, AZURE_OPENAI_API_KEY) o
    • Microsoft Entra ID (scelta consigliata).
  • Installa la libreria client per il tuo linguaggio:
    • 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: aggiungere com.openai:openai-java e com.azure:azure-identity al progetto.
  • Per esempi REST, impostare AZURE_OPENAI_API_KEY (flusso di chiave API) o AZURE_OPENAI_AUTH_TOKEN (flusso di Microsoft Entra ID).

Regioni supportate

Prima di eseguire gli esempi in questo articolo, verificare che l'area di risorse supporti l'API Risposte. L'API v1 è necessaria per accedere alle funzionalità più recenti. Per informazioni dettagliate, vedere il ciclo di vita della versione dell'API. L'API Risposte è attualmente disponibile nelle aree seguenti:

  • australiaeast
  • brasilesouth
  • canadacentral
  • Canada orientale
  • eastus
  • eastus2
  • francecentral
  • germania ovest centrale
  • italynorth
  • japaneast
  • koreacentral
  • northcentralus
  • norvegiaest
  • polandcentral
  • southafricanorth
  • southcentralus
  • Sud-est asiatico
  • southindia
  • spaincentral
  • Swedencentral
  • SvizzeraNorth
  • uaenorth
  • uksouth
  • westus
  • westus3

Modelli supportati

L'API Risposte supporta i modelli seguenti:

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

Non tutti i modelli sono disponibili in ogni area supportata. Controllare la pagina dei modelli per la disponibilità dell'area del modello. Per il set completo di parametri di richiesta e risposta, vedere la documentazione di riferimento dell'API Risposte.

Nota

Attualmente non supportato:

  • Generazione di immagini con modifica e streaming a più turni.
  • Non è possibile caricare le immagini come file e quindi fare riferimento come input.

Si è verificato un problema noto con quanto segue:

  • PDF come file di input è ora supportato, ma l'impostazione dello scopo di caricamento dei file su user_data non è attualmente supportata.
  • Problemi di prestazioni quando viene usata la modalità in background con lo streaming. Microsoft sta lavorando per risolvere questo problema.

Generare una risposta di testo

Generare una risposta di testo semplice usando l'API Risposte. Sostituire YOUR-RESOURCE-NAME e MODEL_NAME con i valori di distribuzione.

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

Risposta di esempio

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

Recuperare una risposta

Recuperare una risposta in base al relativo ID da una chiamata API Risposte precedente.

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

Risposta di esempio

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

Eliminare una risposta

Per impostazione predefinita, i dati di risposta vengono conservati per 30 giorni. Eliminare una risposta archiviata in base all'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)

Concatenamento delle risposte

Concatena i turni passando l'ID della risposta precedente 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)

Concatenamento manuale delle risposte

In alternativa, è possibile trasferire manualmente gli elementi di output nella richiesta successiva.

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

Compattare una risposta

La compattazione riduce il contesto di input mantenendo lo stato essenziale per turni successivi.

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)

Compattare utilizzando gli elementi restituiti

È possibile compattare tutti gli elementi restituiti dalle richieste precedenti, ad esempio ragionamento, messaggio, chiamata di funzione e così via.

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)

Compattare utilizzando l'ID risposta precedente

È anche possibile compattare usando un ID risposta precedente.

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)

Compattazione lato server

È anche possibile usare la compattazione lato server direttamente in Risposte (POST /responses o client.responses.create) impostando context_management con .compact_threshold

  • Quando il numero di token di output supera la soglia configurata, l'API Risposte esegue automaticamente la compattazione.
  • In questa modalità non è necessario chiamare /responses/compact separatamente.
  • La risposta include un elemento di compattazione crittografato.
  • La compattazione lato server funzionerà quando si imposta store=false sulle richieste di creazione delle risposte.

L'elemento di compattazione porta avanti lo stato precedente essenziale e il ragionamento nel turno successivo usando meno token. È opaco e non deve essere leggibile dall'uomo.

Se si usa il concatenamento di matrici di input senza stato, aggiungere gli elementi di output come di consueto. Se si usa previous_response_id, passare solo il nuovo messaggio utente ad ogni turno. In entrambi i modelli, l'elemento di compattazione contiene il contesto necessario per la finestra successiva.

Suggerimento

Dopo aver accodato gli elementi di output agli elementi di input precedenti, è possibile eliminare gli elementi che sono arrivati prima dell'elemento di compattazione più recente per mantenere le richieste più piccole e ridurre la latenza della coda lunga. L'elemento di compattazione più recente contiene il contesto necessario per continuare la conversazione. Se si usa il concatenamento previous_response_id, non eseguire manualmente l'eliminazione.

Flusso

  1. Chiama responses come di consueto. Aggiungere context_management a compact_threshold per abilitare la compattazione lato server.
  2. Se l'output supera la soglia, il servizio attiva la compattazione, genera un elemento di compattazione nel flusso di output e elimina il contesto prima di continuare l'inferenza.
  3. Continuare la conversazione usando uno dei modelli seguenti:
    1. Concatenamento di matrici di input senza stato: aggiungere elementi di output, inclusi gli elementi di compattazione, alla matrice di input successiva.
    2. Concatenamentoprevious_response_id: passare solo il nuovo messaggio utente a ogni turno e portare avanti l'ID risposta più recente.

Esempio

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

Trasmetti la risposta in streaming man mano che viene generata impostando stream=true. Il servizio emette eventi incrementali che puoi consumare per visualizzare l'output token per token.

Nota

Durante lo streaming, l'API Risposte potrebbe restituire un evento di errore ( 500, 429e errori simili) se il servizio rileva un errore, ad esempio limiti di token o problemi di analisi. Le applicazioni devono rilevare questo evento e arrestare o riavviare normalmente lo streaming. Non vengono addebitati i costi per i token generati durante le risposte di streaming fallite.

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

Chiamata di funzione

La Responses API supporta il function calling.

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)

Interprete di codice

Lo strumento Interprete codice consente ai modelli di scrivere ed eseguire codice Python in un ambiente protetto e in modalità sandbox. Supporta una gamma di attività avanzate, tra cui:

  • Elaborazione di file con formati e strutture di dati diversi
  • Generazione di file che includono dati e visualizzazioni (ad esempio, grafici)
  • Scrivere ed eseguire codice in modo iterativo per risolvere i problemi: i modelli possono eseguire il debug e riprovare il codice fino a raggiungere il successo.
  • Miglioramento del ragionamento visivo nei modelli supportati (ad esempio, o3, o4-mini) abilitando trasformazioni delle immagini, ad esempio ritaglio, zoom e rotazione
  • Questo strumento è particolarmente utile per scenari che coinvolgono l'analisi dei dati, il calcolo matematico e la generazione di codice.
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)

Contenitori

Importante

L'interprete del codice ha addebiti aggiuntivi oltre alle tariffe basate su token per l'utilizzo di Azure OpenAI. Se l'API Risposte chiama l'interprete del codice contemporaneamente in due thread diversi, vengono create due sessioni dell'interprete di codice. Ogni sessione è attiva per impostazione predefinita per 1 ora con un timeout di inattività di 20 minuti.

Lo strumento Interprete del codice richiede un contenitore, ovvero una macchina virtuale con sandbox completa dove il modello può eseguire codice Python. I contenitori possono includere file o file caricati generati durante l'esecuzione.

Per creare un contenitore, specificare "container": { "type": "auto", "file_ids": ["file-1", "file-2"] } nella configurazione dello strumento quando si crea un nuovo oggetto Response. In questo modo viene creato automaticamente un nuovo contenitore o riutilizzato uno attivo da un code_interpreter_call precedente nel contesto del modello. L'oggetto code_interpreter_call nell'output dell'API conterrà l'oggetto container_id generato. Questo contenitore scade se non viene usato per 20 minuti.

Input e output dei file

Quando si esegue l'interprete del codice, il modello può creare i propri file. Ad esempio, se si chiede di costruire un tracciato o di creare un file CSV, queste immagini vengono create direttamente nel contenitore. Questi file verranno riportati nelle annotazioni del messaggio successivo.

Tutti i file nell'input del modello vengono caricati automaticamente nel contenitore. Non è necessario caricarlo in modo esplicito nel contenitore.

File compatibili

Formato file 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 testo/puro
.css text/css
.js text/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 o "text/xml"
.zip application/zip

Elencare gli elementi di input

Recuperare gli elementi di input inviati a una risposta. Ciò è utile per esaminare il contesto di conversazione completo, inclusi gli elementi aggiunti dal modello (ad esempio, chiamate di funzione o elementi di compattazione).

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

Risposta di esempio

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

Input immagine

I modelli abilitati per la visione possono interpretare le immagini insieme al testo. Possono riconoscere oggetti, forme, colori e trame e leggere il testo contenuto in un'immagine, soggetto alle limitazioni elencate più avanti in questo articolo.

È possibile fornire un'immagine come input a una richiesta in uno dei modi seguenti:

  • URL completo di un file di immagine
  • URI di dati con codifica Base64
  • ID file creato con l'API Files

URL dell'immagine

Fare riferimento a un'immagine ospitata in un URL pubblico. Il modello recupera l'immagine e la include come parte del contenuto di input.

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)

Immagine con codifica Base64

Invia un'immagine in linea codificandone i byte come URI di dati base64. Usare questo modello quando l'immagine non è ospitata in un URL pubblico o quando si vuole evitare un recupero di rete aggiuntivo.

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 del file

Caricare un'immagine con l'API File usando purpose="vision", quindi fare riferimento all'ID file restituito nella richiesta. Questo approccio è utile quando si vuole riutilizzare la stessa immagine tra più richieste senza inviare nuovamente i byte.

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)

Requisiti di input dell'immagine

Nella tabella seguente sono elencati i tipi di file supportati per gli input di immagine.

Tipo di file Tipo MIME
PNG image/png
JPEG image/jpeg
WebP image/webp
GIF non animata image/gif

In una singola richiesta è possibile includere fino a 100 immagini. Ogni singolo file di immagine deve essere inferiore a 50 MB e anche le dimensioni combinate di tutte le immagini nella richiesta devono essere minori di 50 MB.

Le immagini devono soddisfare questi requisiti aggiuntivi:

  • L'immagine deve essere rilevante per il prompt; il modello non è progettato per contenuto visivo non correlato.
  • Le immagini non devono contenere contenuto dannoso o sensibile che viola i criteri di contenuto.
  • I file di immagine non possono essere danneggiati o illeggibili. Se il modello non è in grado di elaborare un'immagine, la richiesta ha esito negativo.

Scegliere un livello di dettaglio immagine

Usare la detail proprietà in una input_image parte del contenuto per controllare il modo in cui il modello elabora l'immagine. I dettagli inferiori usano meno token ed è più veloce, mentre i dettagli più elevati usano più token, ma consentono al modello di acquisire funzionalità più dettagliate.

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

La tabella seguente descrive ogni livello di dettaglio.

Livello dettagli Description
low Il modello usa una versione con risoluzione inferiore dell'immagine. Questa opzione usa i token più piccoli e produce la risposta più veloce, ma il modello potrebbe perdere dettagli.
high Il modello usa una versione con risoluzione superiore dell'immagine. Questa opzione acquisisce dettagli più sottili, ma usa più token e richiede più tempo per rispondere.
auto Valore predefinito. Il modello seleziona il livello di dettaglio appropriato in base all'immagine e alla richiesta.

Limitazioni dell'inserimento di immagini

I modelli abilitati per la visione hanno le limitazioni seguenti:

  • Immagini mediche: il modello non è adatto per interpretare immagini mediche specializzate come le scansioni CT e non deve essere usato per consulenza medica.
  • Testo non in inglese: il modello potrebbe non funzionare in modo ottimale quando si gestiscono immagini contenenti testo in alfabeti non latini, ad esempio giapponese o coreano.
  • Testo piccolo: ingrandire il testo all'interno di un'immagine per migliorare la leggibilità, ma evitare di ritagliare dettagli importanti.
  • Rotazione: il modello potrebbe aver interpretato erroneamente testo e immagini ruotate o capovolte.
  • Elementi visivi: il modello potrebbe avere difficoltà con grafici o testi in cui variano colori o stili, ad esempio linee continue, tratteggiate o puntinate.
  • Ragionamento spaziale: il modello ha difficoltà con le attività che richiedono una localizzazione spaziale precisa, ad esempio l'identificazione delle posizioni degli scacchi.
  • Accuratezza: il modello potrebbe generare descrizioni o didascalie non corrette in alcuni casi.
  • Formato dell'immagine: il modello ha difficoltà con le immagini panoramiche e fisheye.
  • Metadati e ridimensionamento: il modello non elabora i nomi o i metadati dei file originali e le immagini vengono ridimensionate prima dell'analisi, che influisce sulle dimensioni originali.
  • Conteggio: il modello potrebbe fornire conteggi approssimativi per gli oggetti nelle immagini.
  • CAPTCHAs: per motivi di sicurezza, è in atto un sistema per bloccare l'invio di CAPTCHA.

Input file

I modelli con funzionalità di visione supportano l'input PDF. I file PDF possono essere forniti come dati con codifica Base64 o come ID file. Per consentire ai modelli di interpretare il contenuto PDF, sia il testo estratto che un'immagine di ogni pagina sono inclusi nel contesto del modello. Ciò è utile quando le informazioni chiave vengono trasmesse tramite diagrammi o contenuto non testuale.

Nota

  • Tutte le immagini e il testo estratti vengono inseriti nel contesto del modello. Assicurarsi di comprendere le implicazioni relative all'utilizzo dei prezzi e dei token dell'uso di PDF come input.
  • In una singola richiesta API è possibile includere più file, ma ogni file deve essere inferiore a 50 MB. Il limite combinato per tutti i file nella richiesta è 50 MB.
  • Solo i modelli che supportano input di testo e immagine possono accettare file PDF come input.
  • Un purpose di user_data non è attualmente supportato. Come soluzione alternativa temporanea è necessario impostare lo scopo su assistants.

Convertire il PDF in Base64 e analizzare

Inviare un PDF in linea codificandone i byte come URI di dati in Base64. Il modello riceve sia il testo estratto che un'immagine sottoposta a rendering di ogni pagina.

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)

Caricare pdf e analizzare

Caricare il file PDF con purpose="assistants". Un purpose di user_data non è attualmente supportato.

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 di server MCP remoti

È possibile estendere le funzionalità del modello collegandola agli strumenti ospitati in server MCP (Remote Model Context Protocol). Questi server vengono gestiti da sviluppatori e organizzazioni ed espongono strumenti accessibili dai client compatibili con MCP, ad esempio l'API Risposte.

Model Context Protocol (MCP) è uno standard aperto che definisce il modo in cui le applicazioni forniscono strumenti e dati contestuali a modelli di linguaggio di grandi dimensioni. Consente l'integrazione coerente e scalabile di strumenti esterni nei flussi di lavoro del modello.

L'esempio seguente illustra come usare un server MCP remoto per eseguire query su informazioni su un repository dell'API REST Azure. Il modello recupera il contenuto del repository e ragiona su di esso in tempo reale.

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)

Lo strumento MCP funziona solo nell'API Risposte ed è disponibile in tutti i modelli più recenti (gpt-4o, gpt-4.1 e i modelli di ragionamento). Quando si usa lo strumento MCP, si paga solo per i token usati durante l'importazione di definizioni degli strumenti o l'esecuzione di chiamate agli strumenti, senza costi aggiuntivi.

Approvazioni

Per impostazione predefinita, l'API Risposte richiede l'approvazione esplicita prima che tutti i dati vengano condivisi con un server MCP remoto. Questo passaggio di approvazione consente di garantire la trasparenza e di controllare le informazioni inviate esternamente.

È consigliabile esaminare tutti i dati condivisi con i server MCP remoti e, facoltativamente, registrarlo a scopo di controllo.

Quando è necessaria un'approvazione, il modello restituisce un mcp_approval_request elemento nell'output della risposta. Questo oggetto contiene i dettagli della richiesta in sospeso e consente di esaminare o modificare i dati prima di procedere.

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

Per procedere con la chiamata MCP remota, è necessario rispondere alla richiesta di approvazione creando un nuovo oggetto risposta che include un elemento mcp_approval_response. Questo oggetto conferma la finalità di consentire al modello di inviare i dati specificati al server 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)

Autenticazione

Importante

  • Il client MCP all'interno dell'API Risposte richiede TLS 1.2 o versione successiva.
  • Mutual TLS (mTLS) attualmente non è supportato.
  • Tag di servizio di Azure non è attualmente supportato per il traffico client MCP.

A differenza del server MCP GitHub, la maggior parte dei server MCP remoti richiede l'autenticazione. Lo strumento MCP nell'API Risposte supporta intestazioni personalizzate, consentendo di connettersi in modo sicuro a questi server usando lo schema di autenticazione richiesto.

È possibile specificare intestazioni come chiavi API, token di accesso OAuth o altre credenziali direttamente nella richiesta. L'intestazione più comunemente usata è l'intestazione Authorization .

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)

Attività in background

La modalità in background consente di eseguire attività con esecuzione prolungata in modo asincrono con modelli di ragionamento come o3 e o1-pro. È utile per le attività complesse che possono richiedere alcuni minuti per il completamento (ad esempio, agenti di tipo Codex o Deep Research). Quando una richiesta viene inviata con "background": true, l'operazione viene elaborata in modo asincrono e se ne interroga lo stato.

Avviare un'attività in background

Impostare background=true nella richiesta per accodare l'operazione. Il servizio restituisce immediatamente un ID di risposta e uno stato queued: usa quell'ID per eseguire il polling, trasmettere in streaming o annullare l'operazione.

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)

Eseguire il polling fino al completamento

Continuare a eseguire il polling mentre lo stato è queued o in_progress. Quando la risposta raggiunge uno stato terminale, è disponibile per il recupero.

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

Annullare un'attività in background

Annulla un'attività in background in esecuzione con l'endpoint cancel. L'annullamento è idempotente: le chiamate successive restituiscono l'oggetto di risposta finale.

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

Per trasmettere una risposta in background, impostare sia background che stream su true. Questo modello consente di riprendere lo streaming in caso di eliminazione della connessione. Tieni traccia della tua posizione con sequence_number di ogni 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"]

Le risposte in background hanno attualmente una latenza di tempo per il primo token più elevata rispetto alle risposte sincrone. Sono in corso miglioramenti per ridurre questo divario.

Limitazioni

  • La modalità in background richiede store=true. Le richieste senza stato non sono supportate.
  • È possibile riprendere lo streaming solo se la richiesta originale includeva stream=true.
  • Per annullare una risposta sincrona, terminare direttamente la connessione.

Riprendere lo streaming da un punto specifico

Se una connessione di streaming si interrompe, è possibile riprendere da un evento noto passando stream=true insieme a starting_after=<sequence_number> in una GET alla risposta. Il servizio ripete gli eventi emessi dopo quel numero di sequenza.

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"

Elementi di ragionamento crittografati

Quando si usa l'API Risposte in modalità senza stato (store=false), è comunque necessario mantenere il contesto di ragionamento tra turni di conversazione. A tale scopo, includere elementi di ragionamento crittografati nelle richieste.

Per mantenere gli elementi di ragionamento tra turni, aggiungere reasoning.encrypted_content al include parametro . La risposta contiene quindi una versione crittografata della traccia di ragionamento, che è possibile passare alle richieste future.

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)

L'API Risposte consente la generazione di immagini come parte delle conversazioni e dei flussi di lavoro in più passaggi. Supporta input e output di immagini all'interno del contesto e include strumenti predefiniti per la generazione e la modifica di immagini.

Rispetto all'API immagine autonoma, l'API Risposte offre due vantaggi:

  • Streaming: consente di visualizzare output di immagini parziali durante la generazione per migliorare la latenza percepita.
  • Input flessibili: accetta gli ID dei file di immagine come input, oltre ai byte grezzi delle immagini.

Nota

Lo strumento di generazione di immagini nell'API Responses è supportato dai modelli della serie gpt-image-1, e puoi richiamarlo da una serie di modelli compatibili per chat e ragionamento. Per l'elenco corrente dei modelli di orchestrazione supportati, vedere la sezione Modelli supportati più avanti in questo articolo.

Lo strumento di generazione di immagini attualmente non supporta la modalità di streaming. Per trasmettere immagini parziali, chiamare l'API di generazione di immagini direttamente all'esterno dell'API Risposte.

Usare l'API Risposte per creare esperienze di immagini conversazionali con modelli di immagine 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]))

Modelli di ragionamento

Per esempi di come usare i modelli di ragionamento con l'API delle risposte, vedere la guida ai modelli di ragionamento.

Uso del computer

L'uso del computer con Playwright è stato spostato nella guida dedicata al modello di utilizzo del computer.

Risoluzione dei problemi

  • 401/403: se utilizzi Microsoft Entra ID, verifica che l'ambito del token sia https://ai.azure.com/.default. Se si usa una chiave API, verificare di usare la chiave corretta per la risorsa.
  • 404: Confermare che model corrisponda al nome della distribuzione.

Contenuto correlato

  • Last updated on