使用 Azure OpenAI 回應 API

使用 Azure OpenAI 回應 API 來產生有狀態、多回合的回應。 它將聊天完成功能與助理 API 整合於一個統一體驗中。 使用 多代理協調 將獨立工作委派給平行運作的子代理，或使用 工具搜尋，僅在模型需要時才載入工具定義。 回應 API 也支援驅動電腦使用的computer-use-preview模式。

欲了解完整的請求與回應參數描述，請參閱 回應 API 參數參考。

先決條件

  • 一個已部署的 Azure OpenAI 模型。
  • 一種認證方法：
    • API 金鑰（例如， AZURE_OPENAI_API_KEY），或
    • Microsoft Entra ID（推薦）。
  • 安裝你語言的客戶端函式庫：
    • Python： pip install openai azure-identity
    • .NET： dotnet add package OpenAI 和 dotnet add package Azure.Identity
    • JavaScript/TypeScript： npm install openai @azure/identity
    • Java：在專案中加入com.openai:openai-java和com.azure:azure-identity。
  • 以 REST 為例，設定 AZURE_OPENAI_API_KEY（API 金鑰流程）或 AZURE_OPENAI_AUTH_TOKEN（Microsoft Entra ID 流程）。

支援的區域

在執行本文範例前，請確認你的資源區域是否支援 Responses API。 必須使用 v1 API 才能存取最新功能。 詳情請參閱 API 版本生命週期。 關於 Foundry Agent Service 的區域支援，請參閱 區域可用性表。 回應 API 目前可在以下地區使用：

  • 澳洲東部
  • 巴西南部
  • 加拿大中央
  • 加拿大東部
  • centralus
  • 伊斯特斯
  • eastus2
  • francecentral
  • 德國-西中部
  • 義大利北方
  • 日本東部
  • japanwest
  • koreacentral
  • northcentralus
  • 挪威東部
  • 波蘭中央
  • southafricanorth
  • 美國中南部
  • 東南亞
  • 南印度
  • 西班牙中心
  • swedencentral
  • switzerlandnorth
  • switzerlandwest
  • uaenorth
  • UKSOUTH
  • ukwest
  • westcentralus
  • 西歐
  • westus
  • westus2
  • westus3

支援的模型

回應 API 支援以下模型：

  • gpt-6.1-terra （版本： 2026-10-26）
  • gpt-6.1-sol （版本： 2026-09-29）
  • gpt-6-luna （版本： 2026-09-22）
  • gpt-6-sol （版本： 2026-09-22）
  • gpt-6-astra （版本： 2026-09-03）
  • gpt-5.6-sol （版本： 2026-07-09）
  • gpt-5.6-terra （版本： 2026-07-09）
  • gpt-5.6-luna （版本： 2026-07-09）
  • gpt-chat-latest（版本：2026-10-07， 2026-08-06， 2026-06-24， 2026-05-28， 2026-05-05）
  • gpt-5.5 （版本： 2026-04-24）
  • gpt-5.4-nano （版本： 2026-03-17）
  • gpt-5.4-mini （版本： 2026-03-17）
  • gpt-5.4-pro （版本：2026-03-05）
  • gpt-5.4 （版本：2026-03-05）
  • gpt-5.3-chat （版本： 2026-03-03）
  • gpt-5.3-codex （版本： 2026-02-24）
  • gpt-5.2-codex （版本： 2026-01-14）
  • gpt-5.2 （版本： 2025-12-11）
  • gpt-5.2-chat （版本： 2025-12-11）
  • gpt-5.2-chat （版本： 2026-02-10）
  • gpt-5.1-codex-max （版本： 2025-12-04）
  • gpt-5.1 （版本： 2025-11-13）
  • gpt-5.1-chat （版本： 2025-11-13）
  • gpt-5.1-codex （版本： 2025-11-13）
  • gpt-5.1-codex-mini （版本： 2025-11-13）
  • gpt-5-pro （版本： 2025-10-06）
  • gpt-5-codex （版本： 2025-09-11）
  • gpt-5 （版本： 2025-08-07）
  • gpt-5-mini （版本： 2025-08-07）
  • gpt-5-nano （版本： 2025-08-07）
  • gpt-5-chat （版本： 2025-08-07）
  • gpt-5-chat （版本： 2025-10-03）
  • gpt-5-codex （版本： 2025-09-15）
  • gpt-4o（版本：2024-11-20、、2024-08-062024-05-13）
  • gpt-4o-mini （版本： 2024-07-18）
  • computer-use-preview
  • gpt-4.1 （版本： 2025-04-14）
  • gpt-4.1-nano （版本： 2025-04-14）
  • gpt-4.1-mini （版本： 2025-04-14）
  • gpt-image-1 （版本： 2025-04-15）
  • gpt-image-1-mini （版本： 2025-10-06）
  • gpt-image-1.5 （版本： 2025-12-16）
  • gpt-image-2.5-flare （版本： 2026-09-09）
  • gpt-image-2.5-sunburst （版本： 2026-09-09）
  • o1 （版本： 2024-12-17）
  • o3-mini （版本： 2025-01-31）
  • o3 （版本： 2025-04-16）
  • o4-mini （版本： 2025-04-16）

並非所有型號都能在所有支援地區取得。 請查看 模型頁面 以了解模型區域的可用性。

註

目前不支援：

  • 利用多回合剪輯與串流產生影像。

以下有一個已知的問題：

  • 現在支援 PDF 作為輸入檔，但目前不支援將檔案上傳目的設定為 。user_data
  • 當背景模式搭配串流時，效能會有問題。 Microsoft 正在努力解決這個問題。

產生文字回應

使用 Responses API 產生一個簡單的文字回應。 用你的部署值替換 YOUR-RESOURCE-NAME 和 MODEL_NAME 。

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

範例回應

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

檢索回應

從先前的回應 API 呼叫中，依其 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.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))

範例回應

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

刪除回應

預設情況下，回應資料會保留30天。 依 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)

儲存回應資料的加密

當 Responses API 持久保存訊息歷程記錄和相關內容時，該服務會對該內容進行靜態加密。 有關儲存加密的說明，請參閱 Microsoft Foundry 中由 Azure 銷售的模型的資料、隱私與安全性。 關於 CMK 的覆蓋範圍與前置條件，請參見 Microsoft Foundry 中的客戶管理金鑰加密。

此加密與您使用 store=false 管理交談狀態時傳回應用程式的加密推理項目不同。

將回應串連起來

鍊結傳回的方式是將先前的回覆識別碼傳遞給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)

手動串接回應

或者，您也可以在下一個請求中手動轉轉輸出項目。

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

壓縮回應

壓縮減少輸入上下文，同時保留後續回合的本質狀態。

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)

使用返回的項目進行壓縮

你可以壓縮所有來自先前請求的內容，例如推理、訊息、函式呼叫等。

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)

使用先前的回應 ID 壓縮

你也可以用先前的回應 ID 來壓縮。

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)

伺服器端壓縮

你也可以直接在回應POST /responses或client.responses.create中使用伺服器端壓縮，透過設定context_managementcompact_threshold。

  • 當輸出令牌數超過設定的門檻時，回應 API 會自動執行壓縮。
  • 在此模式下，您不需要單獨執行 /responses/compact。
  • 回應包含一個加密的壓縮項目。
  • 當您在「Responses創建請求」中設定store=false時，伺服器端壓縮會生效。

壓縮項目會將必要的先前狀態與推理，延續到下一回合，同時使用較少的詞元。 它不透明，並非設計給人類閱讀。

如果你使用無狀態輸入陣列鏈，請像平常一樣附加輸出項目。 如果你用的是 previous_response_id，每回合只傳遞新用戶訊息。 在這兩種模式中，壓縮項目都包含下一個視窗所需的上下文。

提示

在將輸出項目附加到前一個輸入項目後，你可以刪除最近壓縮項目之前的項目，以減少請求並降低長尾延遲。 最新的壓縮項目會攜帶繼續交談所需的必要內容。 如果你使用previous_response_id 串接，請不要手動修剪。

Flow

  1. 照常打電話 responses 。 添加 context_management 合併 compact_threshold 來啟用伺服器端壓縮。
  2. 若輸出超過閾值，服務會觸發緊縮，在輸出流中發送壓縮項目，並在繼續推理前修整上下文。
  3. 請使用下列其中一種模式來繼續交談：
    1. 無狀態輸入陣列鏈接：將輸出項目（包括壓縮項目）附加到下一個輸入陣列。
    2. previous_response_id 鏈結：每一回合只傳遞新的使用者訊息，並將最新的回應識別碼往後延續。

範例

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

串流

透過設定 stream=true來串流回應產生的過程。 該服務會發出增量事件，您可以使用它來逐詞元來呈現輸出。

import os
from openai import OpenAI

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

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

在串流過程中，若中段發生錯誤，系統會嘗試內部重試以解決錯誤。 如果請求仍然失敗，服務會遇到無法恢復的錯誤。 在這些情況下，HTTP 回應碼為 200（成功），但串流中的錯誤事件包含中游錯誤的詳細資訊。

伺服器回傳以下錯誤類型：

錯誤類型 可翻譯為
server_error 回傳代碼 500
too_many_requests 回傳代碼 429
forbidden 回傳代碼 403
user_error 回傳代碼 400

範例錯誤事件：

{
  "type": "error",
  "error": {
    "type": "too_many_requests",
    "code": "no_capacity",
    "headers": {
      "skip-error-remapping": "true"
    },
    "message": "The system is currently experiencing high demand and cannot process your request. Your request exceeds the maximum usage size allowed during peak load. For improved capacity reliability, consider switching to Provisioned Throughput.",
    "param": null
  }
}

應用程式應該能偵測這些錯誤，並優雅地停止或重新啟動串流。 串流回應失敗期間產生的詞元不會向您收費。

結構化輸出

使用結構化輸出來讓回應遵循 JSON 架構。 在回應 API 請求中，請在 中定義結構 text.format。 聊天完成功能則是用 response_format 來代替的。 關於 SDK 與 REST 範例、支援的結構限制與限制，請參見 結構化輸出。

函式呼叫

回應 API 支援函式呼叫。

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)

管理防護機制與內容過濾

在部署層級套用護欄（內容過濾器）。 每個設定的控制項評估其支援的內容與介入點：核心傷害過濾器評估輸入與輸出，使用者提示攻擊偵測評估使用者輸入，文件攻擊偵測在啟用時評估文件內容。 請分別設定防護機制。 欲了解更多資訊，請參閱 「配置護欄與控制」。 本節說明如何在呼叫回應 API 時偵測並處理護欄結果。

回覆 API 會以與聊天完成不同的方式顯示護欄結果。 回應物件不會使用聊天完成所回傳的 prompt_filter_results 和 content_filter_results 欄位，而是包含頂層的 content_filters 陣列。 每個項目描述一個濾鏡結果。

Field Description
blocked 內容是否被封鎖。
source_type 結果是適用於 prompt（輸入）還是 completion（輸出）。
content_filter_results 類別結果如 hate、 sexual、 violence及 self_harm ，且具有嚴重程度等級，外加可選類別如 jailbreak、 indirect_attack、 protected_material_text、 protected_material_code和 。
content_filter_offsets 結果所適用的字元偏移。

註

content_filters 陣列是 Microsoft Foundry 的擴充功能，不屬於基本 OpenAI 回應結構描述的一部分，因此 SDK 不會為其提供對應的型別化屬性。 可將其視為原始欄位或額外欄位，如以下範例所示。

偵測被阻擋的輸入

當保護欄阻擋你的輸入時，API 會回傳一個帶有程式碼 content_filter的 HTTP 400 錯誤。 擷取此錯誤，以優雅地處理遭到阻擋的提示。

import os
from openai import OpenAI, BadRequestError

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

# A blocked prompt raises BadRequestError with the code "content_filter"
try:
    response = client.responses.create(
        model="MODEL_NAME",
        input="This is a test."
    )
    print(response.output_text)
except BadRequestError as error:
    if error.code == "content_filter":
        print("The prompt was blocked by a guardrail.")
    else:
        raise

閱讀護欄註解

當請求成功時，從回應中讀取 content_filters 陣列以檢查輸入與輸出的護欄結果。

在註解模式下，設定的控制項可以報告嚴重度或偵測結果，而不會據此強制執行。 對應的 blocked 和 filtered 值仍為 false。 四個核心危害類別的註釋模式需要核准修改過的護欄。

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.getenv("AZURE_OPENAI_API_KEY"),
    base_url="https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/",
)
response = client.responses.create(
    model="MODEL_NAME",
    input="This is a test."
)

# content_filters is an Azure extension, so read it from model_extra
content_filters = response.model_extra.get("content_filters", [])
for result in content_filters:
    print(f"Source: {result['source_type']}, Blocked: {result['blocked']}")

欲了解更多護欄類別與嚴重程度，請參閱 護欄概覽 及 註解工作。

程式碼直譯器

Code Interpreter 工具使模型能在安全且沙盒化的環境中撰寫並執行 Python 程式碼。 它支援一系列進階任務，包括：

  • 處理具有多種資料格式與結構的檔案
  • 產生包含資料與視覺化的檔案（例如圖表）
  • 反覆撰寫並執行程式碼以解決問題——模型可以除錯並重試程式碼直到成功
  • 使用支援的模型（例如 o3、o4-mini），增強視覺推理能力，啟用影像轉換功能，如裁切、縮放和旋轉
  • 此工具特別適用於資料分析、數學計算及程式碼產生的情境。
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)

容器

重要

Code Interpreter 在 Azure OpenAI 使用時，除了基於代幣的費用之外，還有額外收費。 如果你的回應 API 在兩個不同執行緒中同時呼叫 Code Interpreter，就會建立兩個 Code Interpreter 會話。 每次會談均按分鐘計費，最低收費為五分鐘。 只要您在 20 分鐘的閒置逾時內存取其容器，工作階段就會保持在作用中的狀態。

程式碼解譯器工具需要一個容器——一個完全沙盒化的虛擬機器，模型可執行 Python 程式碼。 容器可以包含上傳的檔案或執行過程中產生的檔案。

要建立容器，請在工具設定中指定 "container": { "type": "auto", "file_ids": ["file-1", "file-2"] } ，並建立新的回應物件。 這會自動建立一個新容器，或在模型的上下文中重複使用來自先前 code_interpreter_call 的作用中容器。 API 輸出中的 code_interpreter_call 會包含所產生的 container_id。 這個容器如果20分鐘內未使用即失效。

以下檔案限制適用：

  • 一個請求最多可包含 50 個檔案 ID。
  • 一個容器總共可容納多達 1,000 個檔案，包括輸入檔案及由 Code Interpreter 產生的檔案。

檔案輸入與輸出

執行 Code Interpreter 時，模型可以建立自己的檔案。 舉例來說，如果你要求它建構圖表或建立 CSV 檔，它就會直接在你的容器上生成這些圖片。 它會在下一則訊息的註解中引用這些檔案。

模型輸入中的任何檔案都會自動上傳到容器。 您不需要將其明確上傳至容器。

支援檔案

檔案格式 MIME 類型
.c text/x-c
.cs text/x-csharp
.cpp text/x-c++
.csv 文字/CSV
.doc 應用程式/MSWord
.docx application/vnd.openxmlformats-officedocument.wordprocessingml.document
.html 文字/HTML
.java text/x-java
.json application/json
.md text/markdown
.pdf 申請/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 文本/CSS
.js 文字/JavaScript
.sh application/x-sh
.ts application/TypeScript
.csv 應用程式/CSV
.jpeg image/jpeg
.jpg image/jpeg
.gif image/gif
.pkl 應用程式/八位元組串流
.png 圖像/PNG
.tar application/x-tar
.xlsx application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
.xml application/xml 或「text/xml」
.zip application/zip

列出輸入項目

取得已傳送至回應的輸入項目。 這對於檢視完整的對話上下文非常有用，包括模型新增的任何項目（例如函式呼叫或壓縮項目）。

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

範例回應

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

影像輸入

具備視覺功能的模型能同時解讀影像與文字。 他們能辨識物體、形狀、顏色和紋理，並閱讀圖片中包含的文字，但受本文後述限制限制。

你可以用以下任一方式，將圖片作為請求的輸入：

  • 一個連至映像檔的完整網址
  • 一個 Base64 編碼的資料 URI
  • 一個使用 Files API 建立的檔案 ID

圖像網址

引用位於公開 URL 的圖片。 模型會擷取影像並將其納入輸入內容。

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 編碼影像

透過將映像的位元組編碼為 base64 資料，來內嵌傳送映像 當圖片不是放在公開 URL 或你想避免額外網路擷取時，才會用這個模式。

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

請用 檔案 API purpose="assistants"上傳圖片，然後在請求中參考回傳的檔案 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")
)

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

影像輸入需求

下表列出支援的影像輸入檔案類型。

檔案類型 MIME 類型
PNG image/png
JPEG image/jpeg
WebP image/webp
非動畫 GIF image/gif

在一次請求中，你可以包含最多 50 張圖片。 每個獨立影像檔案必須在 512 MB 以下，且提示與該請求中所有圖片的總大小也必須低於 512 MB。

影像必須符合以下額外要求：

  • 圖片必須與提示相關;這個模型並非為無關的視覺內容設計。
  • 圖片不應包含違反內容政策的有害或敏感內容。
  • 影像檔不會損壞或無法讀取。 如果模型無法處理影像，請求就會失敗。

選擇影像細節等級

使用 detail 內容部分上的 input_image 屬性，以控制模型如何處理影像。 細節越低，標記越少且速度越快;細節越少，模型能捕捉更細緻的特徵。

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

下表描述了每個細節層級。

詳細程度 Description
low 該模型使用較低解析度的影像版本。 此選項使用最少的標記，且回應最快，但模型可能會遺漏細節。
high 模型使用較高解析度的影像版本。 此選項能捕捉更細緻的細節，但使用更多代幣且回覆時間較長。
auto 預設值。 模型會根據圖片和提示選擇適當的細節等級。

影像輸入限制

具備視覺功能的模型有以下限制：

  • 醫療影像：此模型不適合解讀像電腦斷層掃描（CT）等專業醫學影像，也不適合用於醫療建議。
  • 非英文文字：當處理包含非拉丁字母（如日文或韓文）文字的影像時，模型可能無法達到最佳效能。
  • 小字：放大圖片中的文字以提升可讀性，但避免裁切重要細節。
  • 旋轉：模型可能會誤解旋轉或倒置的文字與影像。
  • 視覺元素：對於顏色或樣式會變化的圖表或文字內容（例如實線、破折線或點線），模型可能難以辨識。
  • 空間推理：模型在需要精確空間定位的任務上較為困難，例如識別西洋棋局面。
  • 準確性：模型在某些情況下可能會產生錯誤的描述或說明。
  • 影像形狀：模型在全景與魚眼鏡頭影像上有困難。
  • 元資料與調整大小：模型不會處理原始檔案名稱或元資料，且影像在分析前會先調整大小，這會影響其原始尺寸。
  • 計數：模型可能會給出影像中物體的近似計數。
  • CAPTCHA：出於安全考量，系統已建立以阻止提交 CAPTCHA。

檔案輸入

具備視覺功能的模型支援 PDF 輸入。 您可以以下任一方式提供 PDF 檔案：

  • Base64 編碼的資料
  • 一個使用 Files API 建立的檔案 ID
  • 外部檔案 URL（file_url）

為了幫助模型解讀 PDF 內容，模型的上下文包含擷取後的文字與每頁的圖片。 當關鍵資訊透過圖表或非文字內容傳達時，此功能非常有用。

註

  • 所有擷取的文字與圖片都會置於模型的上下文中。 務必了解使用 PDF 作為輸入時的定價及代幣使用影響。
  • 在單一 API 請求中，你可以包含多個檔案，但每個檔案必須不超過 50 MB。 請求中所有檔案的總限制為 50 MB。
  • 只有支援文字與圖片輸入的機型才能接受 PDF 檔案作為輸入。
  • 目前不支援 purpose 為 user_data。 作為臨時的變通方法，你需要將目的設定為 assistants。

將 PDF 轉為 Base64 並進行分析

透過將 PDF 的位元組編碼為 base64 資料 URI，來內嵌傳送 PDF。 模型同時接收擷取的文字與每頁的渲染影像。

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 並進行分析

使用 purpose="assistants" 上傳 PDF 檔案。 目前不支援purpose的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)

從外部檔案網址分析 PDF

利用 file_url 內容項目的 input_file 屬性，參照由可公開存取的 URL 託管的 PDF。 你不需要先下載、轉碼或上傳檔案。

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": "Analyze the letter and provide a summary of the key points.",
                },
                {
                    "type": "input_file",
                    "file_url": "https://www.berkshirehathaway.com/letters/2024ltr.pdf",
                },
            ],
        },
    ]
)

print(response.output_text)

使用遠端 MCP 伺服器

你可以透過連接遠端模型情境協定（MCP）伺服器上的工具來擴展模型的功能。 這些伺服器由開發者和組織維護，並公開可由相容 MCP 用戶端存取的工具，例如 Responses API。

模型上下文協定 （MCP）是一項開放標準，定義應用程式如何向大型語言模型（LLM）提供工具與上下文資料。 它能將外部工具整合到模型工作流程中，保持一致且可擴展。

以下範例說明如何利用遠端 MCP 伺服器查詢 Azure REST API 儲存庫的資訊。 模型會即時檢索並推理資料庫內容。

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)

MCP 工具僅能在回應 API 中使用，且適用於所有較新的模型（gpt-4o、gpt-4.1 及我們的推理模型）。 使用MCP工具時，您只需支付匯入工具定義或工具呼叫時使用的代幣費用，無需額外費用。

核准

預設情況下，回應 API 要求在與遠端 MCP 伺服器分享資料前，先經過明確核准。 此審核步驟有助於確保透明度，並讓您掌控將哪些資訊傳送至外部。

我們建議審查所有與遠端 MCP 伺服器共享的資料，並可選擇性地記錄以供稽核。

當需要核准時，模型會在回應輸出中回傳一項 mcp_approval_request 項目。 此物件包含待處理請求的詳細資料，並允許您在繼續前檢查或修改資料。

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

要進行遠端 MCP 呼叫，您必須透過建立包含 mcp_approval_response 項目的新回應物件來回應核准請求。 這個物件確認你允許模型將指定資料傳送到遠端 MCP 伺服器的意圖。

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)

認證

重要

  • 回應 API 中的 MCP 用戶端需要 TLS 1.2 或更高版本。
  • 目前不支援雙向 TLS（mTLS）。
  • Azure 服務標籤目前不支援 MCP 用戶端流量。

與 GitHub MCP 伺服器不同，大多數遠端 MCP 伺服器需要驗證。 回應 API 中的 MCP 工具支援自訂標頭，讓你能使用這些伺服器所需的認證方案安全連接。

你可以在請求中直接指定標頭，例如 API 金鑰、OAuth 存取權杖或其他憑證。 最常用的標頭是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)

背景任務

背景模式讓您能以非同步方式執行長時間執行的工作，並搭配如o3和o1-pro等推理模型。 它對於需要數分鐘完成的複雜任務非常有用（例如，像是Codex或Deep Research風格的特工）。 當要求和"background": true一起送出時，工作會以非同步方式處理，並您需輪詢以取得其狀態。

啟動背景任務

在請求中設定 background=true，以將該任務排入佇列。 服務會立即回傳回應 ID 和 queued 狀態——用該 ID 輪詢、串流或取消任務。

import os
from openai import OpenAI

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

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

print(response.status)

輪詢直到完成

當狀態為 queued 或 in_progress 時，持續輪詢。 一旦回應達到終端狀態，即可被檢索。

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

取消背景任務

使用 cancel 端點取消進行中的背景工作。 取消是冪零式的——後續呼叫會回傳最終回應物件。

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

若要串流背景回應，請將兩者 backgroundstream 和 都設為 true。 這個模式讓你在連線斷線時繼續串流。 透過各場活動的 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"]

背景回應目前的第一個詞元延遲時間比同步回應更高。 目前正進行改善以縮小這個差距。

限制

  • 背景模式需要 store=true。 不支援無狀態請求。
  • 只有當原始請求包含 stream=true時，才能繼續串流。
  • 若要取消同步回應，請直接終止連線。

從特定位置繼續串流

如果串流連線中斷，您可以透過在回覆的stream=true上一併傳遞starting_after=<sequence_number>和GET，從已知事件重新開始。 服務會重播該序號之後發出的事件。

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"

加密推理

當你使用推理模型，並使用 Responses API 的無狀態模式（store=false）時，你的應用程式會為每個後續請求提供上下文。 先前訊息提供對話歷史，但不包含模型的內部推理。 加密推理項目能讓你將相容的推理上下文帶入後續請求，而不會將推理暴露為對您的應用程式可讀的文字。

為什麼要用加密推理？

當你的應用程式管理對話狀態並需要持續多回合推理工作流程時，請使用加密推理。 例如，使用者可能會提出後續問題，或模型呼叫工具後，在收到結果後繼續進行。

僅僅傳遞先前訊息並不能傳遞模型前一回合的推理上下文。 加密的推理項目會將這些上下文傳遞下去，同時保持其內容對你的應用程式不透明。

如何使用

  1. 設定 store=false。 要明確請求加密推理，將 reasoning.encrypted_content 加入 include 參數中，如下範例所示。
  2. 保留所有傳回的輸出項目的原始順序，包括帶有 encrypted_content 屬性的推理項目。
  3. 下一次通話時，將這些項目與其他相關對話項目一起放入 input，並繼續設定 store=false。 不要將 previous_response_id 用於未儲存的回應。

無狀態回應預設回傳加密內容；include 參數仍受支援，以維持相容性。 重播一個項目可使用相容推理，但模型使用哪種推理取決於其支援的推理上下文模式。 如需詳細資訊，請參閱在呼叫之間保留推理內容。

在無狀態模式下，加密的推理項目會傳回您的應用程式。 您的應用程式負責安全保存該資料並在後續請求時傳回該資料。 選擇符合您安全性與生命週期需求的應用端儲存地點。

以下範例使用了 API 金鑰驗證。 Python 範例使用 OpenAI 用戶端函式庫。 其他範例則直接呼叫 Responses REST 端點，並將完整輸出項目保留為 JSON。

安裝你的語言所需的相依套件：

  • Python：使用 pip install --upgrade openai 安裝客戶端。
  • C#：使用.NET 8或更新版本的主控台應用程式。 不需要其他套件。
  • JavaScript：使用 Node.js 18 或更新版本，並將每個樣本儲存為 .mjs 檔案。 不需要其他套件。
  • Java：使用 JDK 17 或更新版本，並新增 Maven 相依性com.fasterxml.jackson.core:jackson-databind:2.22.4。 將每個樣本以其分頁中顯示的檔名儲存。
  • REST：用 PowerShell 7 或更新版本執行 PowerShell 範例。

為每種語言設定以下環境變數：

  • AZURE_OPENAI_ENDPOINT：你的資源端點，例如 https://YOUR-RESOURCE-NAME.openai.azure.com。
  • AZURE_OPENAI_API_KEY：你的 API 金鑰。
  • AZURE_OPENAI_DEPLOYMENT：一個支援的推理模型部署名稱。

兩個樣本都會檢查是否有加密推理項目，若未回傳則會產生錯誤。 使用部署與推理設定，產生範例請求的推理項目。

繼續無狀態對話

此範例會將回傳項目保留在應用程式管理的清單中，並將它們傳送到後續請求中。

import os

from openai import BadRequestError, OpenAI

client = OpenAI(
    api_key=os.environ["AZURE_OPENAI_API_KEY"],
    base_url=f"{os.environ['AZURE_OPENAI_ENDPOINT'].rstrip('/')}/openai/v1/",
)
deployment = os.environ["AZURE_OPENAI_DEPLOYMENT"]

# Application-managed state. This example keeps it in memory.
conversation = [
    {"role": "user", "content": "Explain the trade-offs of this design."}
]


def add_response_items(response):
    items = [item.model_dump(exclude_none=True) for item in response.output]

    if not any(
        item.get("type") == "reasoning" and item.get("encrypted_content")
        for item in items
    ):
        raise RuntimeError(
            "No encrypted reasoning item was returned. Check the deployment "
            "and the request's include parameter."
        )

    # Preserve the returned items, including encrypted reasoning.
    conversation.extend(items)


try:
    first = client.responses.create(
        model=deployment,
        input=conversation,
        store=False,
        include=["reasoning.encrypted_content"],
    )
    add_response_items(first)
    print("First answer:", first.output_text)

    conversation.append({
        "role": "user",
        "content": "Which trade-off matters most for reliability?",
    })

    second = client.responses.create(
        model=deployment,
        input=conversation,
        store=False,
        include=["reasoning.encrypted_content"],
    )
    add_response_items(second)
    print("Follow-up answer:", second.output_text)

except BadRequestError as exc:
    # Inspect the service error before deciding whether to restart.
    print(f"Request rejected: {exc}")
    raise

範例會印出第一個答案和後續答案。 它保留所有輸出項目，包括加密推理，而非僅保留可讀答案。

conversation 清單是此範例應用程式保留項目的地方。 它被儲存在記憶體中，在程序重新啟動後不會保留。 若應用程式需要稍後繼續執行，就必須自行選擇儲存體，並確保其安全性。

在工具呼叫作業後繼續

此範例保留推理與函式呼叫項目，執行範例函式，並使用相符的 call_id 將結果傳回。

import json
import os

from openai import BadRequestError, OpenAI

client = OpenAI(
    api_key=os.environ["AZURE_OPENAI_API_KEY"],
    base_url=f"{os.environ['AZURE_OPENAI_ENDPOINT'].rstrip('/')}/openai/v1/",
)
deployment = os.environ["AZURE_OPENAI_DEPLOYMENT"]

tools = [{
    "type": "function",
    "name": "get_order_status",
    "description": "Look up the status of an example order.",
    "parameters": {
        "type": "object",
        "properties": {
            "order_id": {"type": "string"}
        },
        "required": ["order_id"],
        "additionalProperties": False,
    },
}]


def get_order_status(order_id):
    # Replace this example with your own trusted data source.
    if order_id == "A123":
        return {"order_id": order_id, "status": "Shipped"}
    return {"order_id": order_id, "status": "Not found"}


conversation = [{
    "role": "user",
    "content": "What is the status of order A123?",
}]


def create_response():
    return client.responses.create(
        model=deployment,
        input=conversation,
        tools=tools,
        store=False,
        include=["reasoning.encrypted_content"],
    )


try:
    # Bound the number of tool rounds.
    for _ in range(3):
        response = create_response()
        items = [item.model_dump(exclude_none=True) for item in response.output]

        if not any(
            item.get("type") == "reasoning" and item.get("encrypted_content")
            for item in items
        ):
            raise RuntimeError("No encrypted reasoning item was returned.")

        # Preserve returned items in order, including reasoning and tool calls.
        conversation.extend(items)

        calls = [
            item for item in response.output
            if item.type == "function_call"
        ]
        if not calls:
            print(response.output_text)
            break

        for call in calls:
            if call.name != "get_order_status":
                raise ValueError(f"Unexpected tool: {call.name}")

            arguments = json.loads(call.arguments)
            result = get_order_status(arguments["order_id"])

            conversation.append({
                "type": "function_call_output",
                "call_id": call.call_id,
                "output": json.dumps(result),
            })
    else:
        raise RuntimeError("The tool-call limit was reached.")

except BadRequestError as exc:
    print(f"Request rejected: {exc}")
    raise

範例在處理範例訂單狀態後，會列印模型的最終答案。 此函數使用範例資料，而非即時訂單系統。 迴圈限制回應請求次數為三個，若模型繼續請求工具，則會產生錯誤。

保持加密推理項目完整;不要嘗試閱讀或修改他們的加密內容。 關於函式定義及工具-結果格式，請參見 函式呼叫。

路由考量

如果你是透過 Azure API 管理 路由，請先驗證已加密的 reasoning replay 是否能在你設定的後端之間運作，再決定是否依賴它。 如果服務返回 invalid_encrypted_content，請檢查錯誤及資源路由，再決定是否重新啟動對話。

資料保護考量

加密推理項目在請求之間帶有不透明的推理上下文。 它們不會說明服務如何加密儲存的資料、哪些金鑰保護儲存的提示或對話狀態，或你的應用程式必須將傳回的項目存放在哪裡。

設定 store=false 並不代表能全面保證所有服務處理流程皆不保留任何資料。 關於服務端儲存與濫用監控的細節，請參見 Azure OpenAI 的資料、隱私與安全。

影像產生

回應 API 讓影像生成成為對話和多步驟工作流程的一部分。 它支援在情境中輸入與輸出影像，並內建產生與編輯影像的工具。

與獨立的影像 API 相比，回應 API 有兩大優勢：

  • 串流：在產生過程中顯示部分影像輸出以改善感知延遲。
  • 彈性輸入：除了原始影像位元組外，還接受影像檔案 ID 作為輸入。

註

回應 API 中的影像生成工具支援 gpt-image-1-series 模型，你可以從相容的聊天與推理模型中呼叫它。 關於目前支援的編排模型清單，請參閱本文後面的 支援模型 章節。

影像生成工具目前不支援串流模式。 若要串流部分影像，請直接在回應 API 外呼叫 影像生成 API 。

使用 Responses API 與 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]))

推理模型

關於如何搭配回應 API 使用推理模型的範例，請參考 推理模型指南。

電腦應用

搭配 Playwright 使用電腦的內容已移至專用的電腦使用模型指南。

故障排除

為什麼我的 API 會被終止以防萬一？

使用 Astra 模型時，為確保代理正確解讀並遵循您的指令，我們有一套系統，若偵測到代理可能未正確解讀您的指令，例如傳輸敏感資料、存取敏感資料或做出破壞性變更，則會停止回應 API 的會話。 如果你的會話結束了，這不一定代表客服犯了錯，只是值得回顧客服的操作，確保他正確解讀並遵循你的指示。

這個系統監控哪些 API 請求？

上述所述的同一個系統會在 Responses API 中以非同步方式監控發送至 Astra 的請求。 聊天完成 API 不會被這個特定的監控系統掃描。 我們建議使用 Responses API，以獲得代理型使用情境中最高的效能與安全性。

如何偵測這個系統在 API 中已經結束對話？

當安全系統偵測到代理程式可能以嚴重偏差的方式錯誤解讀指示時，API 會傳回安全註釋代碼 misalignment-enforcement。 此時，該會話無法繼續。

如果偵測到這樣的案例，我的申請應該怎麼做？

你可以考慮建立某種系統，讓某人能查看客服在這類對話中所採取的操作，例如提供使用者介面讓最終使用者檢視。 一旦 API 因此原因停止對話，便無法恢復。

解決常見的 API 錯誤

請參考以下指引來解決常見的 API 錯誤：

  • 401/403：如果你使用 Microsoft Entra ID，請確保你的令牌範圍設定為 https://ai.azure.com/.default。 如果你使用 API 金鑰，請確認你使用的是該資源的正確金鑰。
  • 404：確認 model 與你的部署名稱相符。

相關內容

  • 上次更新時間：