你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

Azure OpenAI 在 Microsoft Foundry 模型 v1 API 中

本文介绍如何使用 v1 Azure OpenAI API。 v1 API 简化了身份验证，消除了对日期 api-version 参数的需求，并支持跨提供程序模型调用。

注释

可以随时将新的 API 响应对象添加到 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 密钥：

运行代码之前，请设置以下环境变量：

Variable	价值
`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}" 
});

为和 OPENAI_BASE_URL 设置环境变量的 API 密钥OPENAI_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}")
)

为和 OPENAI_BASE_URL 设置环境变量的 API 密钥OPENAI_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();

为和 OPENAI_BASE_URL 设置环境变量的 API 密钥OPENAI_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 还允许你与其他提供程序（例如 DeepSeek 和 Grok）的模型（支持 OpenAI v1 聊天完成语法）进行聊天完成调用。

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

注释

响应 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 预览版 API
视频生成支持
新的响应 API 功能：
- 远程模型上下文协议（MCP）服务器工具集成
- 对异步后台任务的支持
- 加密推理项
- 图像生成

2025-04-01-preview 和 2025-03-01-preview 之间的更改

2025-03-01-preview 和 2025-02-01-preview 之间的更改

响应 API
计算机使用

2025-02-01-preview 和 2025-01-01-preview 之间的更改

存储完成结果（蒸馏 API 支持）。

2025-01-01-preview 和 2024-12-01-preview 之间的更改

已为prediction支持添加参数。
gpt-4o-audio-preview 模型支持。

2024-12-01-preview 和 2024-10-01-preview 之间的变更

store 和 metadata 是为支持存储完成而添加的参数。
为最新的reasoning_effort添加了。
为 user_security_context添加了。

2024-09-01-preview 和 2024-08-01-preview 之间的变更

添加了 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-preview API 规范之间的变更

结构化输出支持。
添加了大型文件上传 API。
关于数据更改：
- MongoDB 集成。
- 已删除 role_information 参数。
- 添加到引文对象的 rerank_score。
- 已删除 AML 数据源。
- AI 搜索矢量化集成改进。

2024-05-01-preview 和 2024-07-01-preview API 规范之间的更改

添加了 Batch API 支持
Vector 存储分块策略参数
文件搜索工具应输出的 max_num_results。

2024-04-01-preview 和 2024-05-01-preview API 规范之间的变更

助手 v2 支持 - 文件搜索工具和矢量存储
微调checkpoints、seed、events
关于数据更新
DALL-E 2 现在支持模型部署，可用于最新的预览 API。
内容筛选更新

2024-03-01-preview 和 2024-04-01-preview API 规范之间的更改

中断性变更：删除了增强功能参数。这将影响 gpt-4 版本:vision-preview 模型。
添加了 timestamp_granularities 参数。
添加了 audioWord 对象。
其他 TTS response_formats: wav & pcm。

已知问题

2025-04-01-preview Azure OpenAI 规范使用 OpenAPI 3.1。这是一个已知问题，Azure API Management不支持此版本。

后续步骤

反馈

此页面是否有帮助？

Last updated on 2026-03-20

通过

Azure OpenAI 在 Microsoft Foundry 模型 v1 API 中

先决条件

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-preview 和 2025-01-01-preview 之间的更改

2025-01-01-preview 和 2024-12-01-preview 之间的更改

2024-12-01-preview 和 2024-10-01-preview 之间的变更

2024-09-01-preview 和 2024-08-01-preview 之间的变更

2024-07-01-preview 和 2024-08-01-preview 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 规范之间的更改

已知问题

后续步骤

反馈

其他资源