Microsoft Foundry Models v1 API 中的 Azure OpenAI

本文將教你如何使用 v1 Azure OpenAI API。 v1 API 簡化了認證，消除了對過 api-version 時參數的需求，並支援跨提供者的模型呼叫。

註

API回應中可能隨時新增新的回應物件。我們建議你只解析你需要的回應物件。

先決條件

Azure訂閱 - 免費建立
部署於支援區域的 Foundry 資源或 Azure OpenAI 資源
至少需有一個模型部署
有關 Microsoft Entra ID 驗證的詳細資訊：指派給您身份的 Cognitive Services OpenAI User 角色。欲了解更多資訊，請參閱 Azure OpenAI 的角色基於存取控制

API 演進

過去，Azure OpenAI 每月都會收到新 API 版本的更新。利用新功能需要每次 API 更新時不斷更新程式碼和環境變數。 Azure OpenAI 還需要額外使用 Azure 專用客戶端，這在 OpenAI 與 Azure OpenAI 之間遷移程式碼時產生了額外負擔。

自 2025 年 8 月起，您可以選擇加入下一代 v1 Azure OpenAI API，這些 API 將新增以下支援：

持續使用最新功能，無需每月指定新 api-version功能。
API 發布週期更快，新功能更新頻率更高。
OpenAI 用戶端支援，程式碼變更最小，能在使用基於金鑰的驗證時，在 OpenAI 與 Azure OpenAI 之間切換。
OpenAI 用戶端支援基於憑證的認證與自動憑證更新，無需依賴獨立的 Azure OpenAI 用戶端。
使用支援 v1 聊天完成語法的其他供應商模型，例如 DeepSeek 和 Grok，進行聊天完成通話。

對於仍處於預覽階段的新 API 呼叫，將透過傳遞功能專屬的預覽標頭來控制，讓你能選擇加入想要的功能，無需更換 API 版本。或者，有些功能會透過 API 路徑顯示預覽狀態，且不需要額外的標頭。

舉例：

在 /openai/v1/evals 之前的預覽階段，需要傳遞 "aoai-evals":"preview" 標頭。 /evals 已不再預覽。
/openai/v1/fine_tuning/alpha/graders/ 目前處於預覽階段，且由於在 API 路徑中存在， alpha 不需要自訂標頭。

在最初的 v1 正式可用（GA）API 發布中，僅支援部分推論與創作 API 功能。所有 GA 功能均支援生產環境使用。我們正在快速增加對更多功能的支援。

法規變更

v1 API

Python v1 範例

API 關鍵碼：

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="gpt-4.1-nano", # Replace with your model deployment name 
  input="This is a test.",
)

print(response.model_dump_json(indent=2))

與先前 API 的主要差異：

OpenAI() 客戶端被用來取代 AzureOpenAI()。
base_url 傳遞 Azure OpenAI 端點，並附加 /openai/v1 於端點位址後。
api-version 在 v1 GA API 中不再是必備參數。

帶有環境變數的 API 金鑰：

執行程式碼前，請設定以下環境變數：

變數	價值
`OPENAI_BASE_URL`	`https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/`
`OPENAI_API_KEY`	您的 Azure OpenAI API 金鑰

接著建立沒有參數的客戶端：

client = OpenAI()

Microsoft Entra ID：

重要

過去自動憑證更新的處理是透過 AzureOpenAI() 用戶端來處理。 v1 API 透過為用戶端新增自動憑證刷新支援 OpenAI() ，移除了這種依賴。

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  
)

response = client.responses.create(
    model="gpt-4.1-nano",
    input= "This is a test" 
)

print(response.model_dump_json(indent=2))

base_url 傳遞 Azure OpenAI 端點，並附加 /openai/v1 於端點位址後。
api_key 參數設為 token_provider，可自動檢索並刷新認證權杖，而非使用靜態 API 金鑰。

v1 API

C# v1 範例

API 關鍵碼：

OpenAIClient client = new(
    new ApiKeyCredential("{your-api-key}"),
    new OpenAIClientOptions()
    {
        Endpoint = new("https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/"),
    })

Microsoft Entra ID：

#pragma warning disable OPENAI001

BearerTokenPolicy tokenPolicy = new(
    new DefaultAzureCredential(),
    "https://ai.azure.com/.default");
OpenAIClient client = new(
    authenticationPolicy: tokenPolicy,
    options: new OpenAIClientOptions()
    {
        Endpoint = new("https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/"),
    })

v1 API

JavaScript v1 範例

API 關鍵碼：

const client = new OpenAI({
    baseURL: "https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/",
    apiKey: "{your-api-key}" 
});

API Key，環境變數設置為 OPENAI_BASE_URLOPENAI_API_KEY 和：

const client = new OpenAI();

Microsoft Entra ID：

const tokenProvider = getBearerTokenProvider(
    new DefaultAzureCredential(),
    'https://ai.azure.com/.default');
const client = new OpenAI({
    baseURL: "https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/",
    apiKey: tokenProvider
});

v1 API

Go v1 範例

API 關鍵碼：

client := openai.NewClient(
    option.WithBaseURL("https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/"),
    option.WithAPIKey("{your-api-key}")
)

API Key，環境變數設置為 OPENAI_BASE_URLOPENAI_API_KEY 和：

client := openai.NewClient()

Microsoft Entra ID：

tokenCredential, err := azidentity.NewDefaultAzureCredential(nil)

client := openai.NewClient(
    option.WithBaseURL("https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/"),
    azure.WithTokenCredential(tokenCredential)
)

Java v1 範例

v1 API

API 關鍵碼：


OpenAIClient client = OpenAIOkHttpClient.builder()
                .baseUrl("https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/")
                .apiKey(apiKey)
                .build();

API Key，環境變數設置為 OPENAI_BASE_URLOPENAI_API_KEY 和：

OpenAIClient client = OpenAIOkHttpClient.builder()
                .fromEnv()
                .build();

Microsoft Entra ID：

Credential tokenCredential = BearerTokenCredential.create(
        AuthenticationUtil.getBearerTokenSupplier(
                new DefaultAzureCredentialBuilder().build(),
                "https://ai.azure.com/.default"));
OpenAIClient client = OpenAIOkHttpClient.builder()
        .baseUrl("https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/")
        .credential(tokenCredential)
        .build();

v1 API

API 關鍵碼：

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": "gpt-4.1-nano",
     "input": "This is a test"
    }'

Microsoft Entra ID：

curl -X POST https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AZURE_OPENAI_AUTH_TOKEN" \
  -d '{
     "model": "gpt-4o",
     "input": "This is a test"
    }'

模型支援

對於Azure OpenAI 模型，我們建議使用 Responses API ，不過 v1 API 也允許你用其他供應商的模型進行聊天完成呼叫，例如支援 OpenAI v1 聊天完成語法的 DeepSeek 和 Grok。

base_url會接受https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/和https://YOUR-RESOURCE-NAME.services.ai.azure.com/openai/v1/兩種格式。

註

Responses API 也支援 Azure 直接販售的 Foundry 模型，例如 Microsoft AI、Deepseek 和 Grok 模型。欲了解如何在這些模型中使用回應 API，請參閱如何用 Microsoft Foundry 模型產生文字回應。

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,
)
completion = client.chat.completions.create(
  model="MAI-DS-R1", # Replace with your model deployment name.
  messages=[
    {"role": "system", "content": "You are a helpful assistant."},
    {"role": "user", "content": "Tell me about the attention is all you need paper"}
  ]
)

#print(completion.choices[0].message)
print(completion.model_dump_json(indent=2))

using Azure.Identity;
using OpenAI;
using OpenAI.Chat;
using System.ClientModel.Primitives;

#pragma warning disable OPENAI001

BearerTokenPolicy tokenPolicy = new(
    new DefaultAzureCredential(),
    "https://ai.azure.com/.default");

ChatClient client = new(
    model: "MAI-DS-R1", // Replace with your model deployment name.
    authenticationPolicy: tokenPolicy,
    options: new OpenAIClientOptions() { 
    
        Endpoint = new Uri("https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1")
   }
);

ChatCompletion completion = client.CompleteChat("Tell me about the attention is all you need paper");

Console.WriteLine($"[ASSISTANT]: {completion.Content[0].Text}");

import { DefaultAzureCredential, getBearerTokenProvider } from "@azure/identity";
import { OpenAI } from "openai";

const tokenProvider = getBearerTokenProvider(
    new DefaultAzureCredential(),
    'https://ai.azure.com/.default');
const client = new OpenAI({
    baseURL: "https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/",
    apiKey: tokenProvider
});

const messages = [
    { role: 'system', content: 'You are a helpful assistant.' },
    { role: 'user', content: 'Tell me about the attention is all you need paper' }
];

// Make the API request with top-level await
const result = await client.chat.completions.create({ 
    messages, 
    model: 'MAI-DS-R1', // model deployment name
    max_tokens: 100 
});

// Print the full response
console.log('Full response:', result);

// Print just the message content from the response
console.log('Response content:', result.choices[0].message.content);


package main

import (
	"context"
	"fmt"
	"log"

	"github.com/Azure/azure-sdk-for-go/sdk/azidentity"
	"github.com/openai/openai-go/v3"
	"github.com/openai/openai-go/v3/azure"
	"github.com/openai/openai-go/v3/option"
)

func main() {
	// Create an Azure credential
	tokenCredential, err := azidentity.NewDefaultAzureCredential(nil)
	if err != nil {
		log.Fatalf("Failed to create credential: %s", err)
	}

	// Create a client with Azure OpenAI endpoint and token credential
	client := openai.NewClient(
		option.WithBaseURL("https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/"),
		azure.WithTokenCredential(tokenCredential),
	)

	// Make a completion request
	chatCompletion, err := client.Chat.Completions.New(context.TODO(), openai.ChatCompletionNewParams{
		Messages: []openai.ChatCompletionMessageParamUnion{
			openai.UserMessage("Explain what the bitter lesson is?"),
		},
		Model: "MAI-DS-R1", // Use your deployed model name on Azure
	})
	if err != nil {
		log.Fatalf("Failed to get chat completions: %s", err)
	}

	fmt.Println(chatCompletion.Choices[0].Message.Content)
}

package com.example;

import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.ChatModel;
import com.openai.models.chat.completions.ChatCompletion;
import com.openai.models.chat.completions.ChatCompletionCreateParams;

public class OpenAITest {
    public static void main(String[] args) {
        // Get API key from environment variable for security
        String apiKey = System.getenv("OPENAI_API_KEY");
        String resourceName = "https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1";
        String modelDeploymentName = "MAI-DS-R1"; //replace with your model deployment name

        try {
            OpenAIClient client = OpenAIOkHttpClient.builder()
                    .baseUrl(resourceName)
                    .apiKey(apiKey)
                    .build();

           ChatCompletionCreateParams params = ChatCompletionCreateParams.builder()
              .addUserMessage("Explain what the bitter lesson is?")
              .model(modelDeploymentName)
              .build();
           ChatCompletion chatCompletion = client.chat().completions().create(params);
        }
    }
}

curl -X POST https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AZURE_OPENAI_AUTH_TOKEN" \
  -d '{
      "model": "MAI-DS-R1",
      "messages": [
      {
        "role": "developer",
        "content": "You are a helpful assistant."
      },
      {
        "role": "user",
        "content": "Explain what the bitter lesson is?"
      }
    ]
  }'

v1 API 支援

v1 OpenAPI 3.0 規範

API 版本變更日誌

以下章節將總結 API 版本間的變更。

v1 預覽版與 2025-04-01-preview 之間的變更

v1 preview API
影片產生支援
新回應 API 功能：
- 遠端模型情境協定（MCP）伺服器工具整合
- 支援非同步背景任務
- 加密推理項目
- 影像生成

2025-04-01-preview 與 2025-03-01-preview 之間的變動

2025-03-01-preview 與 2025-02-01-preview 之間的變更

回應 API
電腦應用

2025-02-01-預覽與2025-01-01預覽之間的變更

儲存完成結果（支援蒸餾 API）。

2025-01-01-預覽與2024-12-01-預覽之間的變動

prediction 新增參數以支援預測輸出。
gpt-4o-audio-preview 模型支援。

2024-12-01-預覽與2024-10-01預覽之間的變動

store 和 metadata 參數已新增以支援儲存完成。
reasoning_effort 新增於最新推理模型。
user_security_context 為適用於雲端的 Microsoft Defender 整合而新增。

2024-09-01-預覽與2024-08-01預覽之間的變動

max_completion_tokens 新增支援 o1-preview 與 o1-mini 模型。 max_tokens O1 系列機型無法使用。
parallel_tool_calls 補充。
completion_tokens_details 和 reasoning_tokens 被加上。
stream_options 和 include_usage 被加上。

2024-07-01-preview 與 2024-08-01 預覽 API 規範之間的變更

結構化輸出支援。
新增大型檔案上傳 API。
關於您的資料變更：
- Mongo 資料庫整合。
- role_information 參數已移除。
- rerank_score 被加入引用物件。
- 反洗錢資料來源已移除。
- AI 搜尋向量化整合改進。

2024-05-01-preview 與 2024-07-01-preview API 規範之間的變更

新增批次 API 支援功能
向量存儲區塊策略參數
max_num_results 檔案搜尋工具應該會輸出這些。

2024-04-01-preview 與 2024-05-01-preview API 規範之間的變更

助手 v2 支援 - 檔案搜尋工具和向量儲存
微調檢查點、種子、事件
關於你的資料更新
DALL-E 2 現在支援模型部署，並可搭配最新的預覽 API 使用。
內容過濾更新

2024-03-01-preview 與 2024-04-01-preview API 規範之間的變更

重大變革：強化參數已移除。這會影響 gpt-4Version：vision-preview 模型。
timestamp_granularities參數已加入。
audioWord物件已加入。
額外的 TTS response_formats: wav & pcm。

已知問題

2025-04-01-preview Azure OpenAI 規範使用 OpenAPI 3.1。這個版本在 Azure API 管理上沒有完全支援，這是眾所周知的問題。

下一步

意見反應

此頁面對您有幫助嗎？

Last updated on 2026-04-30

Microsoft Foundry Models v1 API 中的 Azure OpenAI

先決條件

API 演進

法規變更

v1 API

模型支援

v1 API 支援

API 版本變更日誌

v1 預覽版與 2025-04-01-preview 之間的變更

2025-04-01-preview 與 2025-03-01-preview 之間的變動

2025-03-01-preview 與 2025-02-01-preview 之間的變更

2025-02-01-預覽與2025-01-01預覽之間的變更

2025-01-01-預覽與2024-12-01-預覽之間的變動

2024-12-01-預覽與2024-10-01預覽之間的變動

2024-09-01-預覽與2024-08-01預覽之間的變動

2024-07-01-preview 與 2024-08-01 預覽 API 規範之間的變更

2024-05-01-preview 與 2024-07-01-preview API 規範之間的變更

2024-04-01-preview 與 2024-05-01-preview API 規範之間的變更

2024-03-01-preview 與 2024-04-01-preview API 規範之間的變更

已知問題

下一步

意見反應

其他資源