Azure OpenAI di Microsoft Foundry Models v1 API

Artikel ini memperlihatkan kepada Anda cara menggunakan API Azure OpenAI v1. API v1 menyederhanakan autentikasi, menghapus kebutuhan akan parameter tanggal api-version , dan mendukung panggilan model lintas penyedia.

Nota

Objek respons API baru mungkin ditambahkan ke respons API kapan saja. Sebaiknya Anda hanya mengurai objek respons yang Anda butuhkan.

Prasyarat

• Langganan Azure - Buat satu secara gratis
• Sumber daya Foundry atau sumber daya Azure OpenAI yang disebarkan di wilayah yang didukung
• Setidaknya satu penyebaran model
• Untuk autentikasi ID Microsoft Entra: peran Cognitive Services OpenAI User yang ditetapkan untuk identitas Anda. Untuk informasi selengkapnya, lihat Kontrol akses berbasis peran untuk Azure OpenAI

Evolusi Antarmuka Pemrograman Aplikasi (API)

Sebelumnya, Azure OpenAI menerima pembaruan bulanan versi API baru. Memanfaatkan fitur baru yang diperlukan terus memperbarui kode dan variabel lingkungan dengan setiap rilis API baru. Azure OpenAI juga memerlukan langkah tambahan menggunakan klien khusus Azure yang membuat overhead saat memigrasikan kode antara OpenAI dan Azure OpenAI.

Mulai Agustus 2025, Anda dapat ikut serta ke API Azure OpenAI generasi berikutnya yang menambahkan dukungan untuk:

• Akses berkelanjutan ke fitur terbaru tanpa perlu menentukan baru api-versionsetiap bulan.
• Siklus rilis API yang lebih cepat dengan fitur baru diluncurkan lebih sering.
• Dukungan klien OpenAI dengan perubahan kode minimal untuk bertukar antara OpenAI dan Azure OpenAI saat menggunakan autentikasi berbasis kunci.
• Dukungan klien OpenAI untuk autentikasi berbasis token dan refresh token otomatis tanpa perlu mengambil dependensi pada klien Azure OpenAI terpisah.
• Lakukan panggilan penyelesaian obrolan dengan model dari penyedia lain seperti DeepSeek dan Grok yang mendukung sintaks penyelesaian obrolan v1.

Akses ke panggilan API baru yang masih dalam pratinjau akan dikontrol dengan meneruskan header pratinjau khusus fitur yang memungkinkan Anda ikut serta dalam fitur yang Anda inginkan, tanpa harus menukar versi API. Atau, beberapa fitur akan menunjukkan status pratinjau melalui jalur API mereka dan tidak memerlukan header tambahan.

Examples:

• Ketika /openai/v1/evals sebelumnya dalam pratinjau, perlu melewatkan header "aoai-evals":"preview". /evals tidak lagi dalam tahap awal.
• /openai/v1/fine_tuning/alpha/graders/ dalam pratinjau dan tidak memerlukan header kustom karena adanya alpha di jalur API.

Untuk peluncuran API awal v1 yang Umum Tersedia (GA), hanya sebagian kemampuan API inferensi dan penulisan API yang didukung. Semua fitur GA didukung untuk digunakan dalam produksi. Dukungan untuk lebih banyak kemampuan sedang ditambahkan dengan cepat.

Perubahan kode

Python

API v1

Contoh Python v1

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

Perbedaan utama dari API sebelumnya:

• OpenAI() klien digunakan alih-alih AzureOpenAI().
• base_url meneruskan titik akhir Azure OpenAI dan /openai/v1 ditambahkan ke alamat titik akhir.
• api-version bukan lagi parameter yang diperlukan dengan API GA v1.

Kunci API dengan variabel lingkungan:

Atur variabel lingkungan berikut sebelum menjalankan kode:

Variabel	Nilai
OPENAI_BASE_URL	https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/
OPENAI_API_KEY	Kunci API Azure OpenAI Anda

Kemudian buat klien tanpa parameter:

client = OpenAI()

Microsoft Entra ID

Penting

Menangani refresh token otomatis sebelumnya ditangani melalui penggunaan AzureOpenAI() klien. API v1 menghapus dependensi ini, dengan menambahkan dukungan refresh token otomatis ke OpenAI() klien.

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 meneruskan titik akhir Azure OpenAI dan /openai/v1 ditambahkan ke alamat titik akhir.
• api_key parameter diatur ke token_provider, memungkinkan pengambilan otomatis dan refresh token autentikasi alih-alih menggunakan kunci API statis.

C#

API v1

Contoh C# v1

Kunci 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/"),
    })

JavaScript

API v1

Contoh JavaScript v1

Kunci API:

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

Kunci API dengan variabel lingkungan yang ditetapkan untuk OPENAI_BASE_URL dan 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
});

Lanjut

API v1

Contoh Go v1

Kunci API:

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

Kunci API dengan variabel lingkungan yang ditetapkan untuk OPENAI_BASE_URL dan 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

Contoh Java v1

API v1

Kunci API:

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

Kunci API dengan variabel lingkungan yang ditetapkan untuk OPENAI_BASE_URL dan 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();

REST

API v1

Kunci 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"
    }'

Dukungan model

Untuk model Azure OpenAI, sebaiknya gunakan Api Respons, namun, API v1 juga memungkinkan Anda melakukan panggilan penyelesaian obrolan dengan model dari penyedia lain seperti DeepSeek dan Grok yang mendukung sintaks penyelesaian obrolan OpenAI v1.

base_url akan menerima format https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/ dan https://YOUR-RESOURCE-NAME.services.ai.azure.com/openai/v1/ .

Nota

Api Respons juga berfungsi dengan Model Foundry yang dijual langsung oleh Azure, seperti model Microsoft AI, DeepSeek, dan Grok. Untuk mempelajari cara menggunakan Api Respons dengan model ini, lihat Cara menghasilkan respons teks dengan Model Microsoft Foundry.

Python

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

C#

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

JavaScript

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

Lanjut

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

Java

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

REST

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?"
      }
    ]
  }'

Dukungan API v1

• Spesifikasi v1 OpenAPI 3.0

Changelog versi API

Bagian berikut ini meringkas perubahan antar versi API.

Perubahan antara rilis pratinjau v1 dan pratinjau 2025-04-01

• API versi pratinjau v1
• Dukungan pembuatan video
• BARU Fitur API Respons:
  • Integrasi alat server Remote Model Context Protocol (MCP)
  • Dukungan untuk tugas latar belakang asinkron
  • Penalaran terenkripsi item
  • Pembuatan gambar

Perubahan antara 2025-04-01-preview dan 2025-03-01-preview

• GPT-image-1 dukung
• Ringkasan penalaran untuk o3 dan o4-mini
• API Evaluasi

Perubahan antara 2025-03-01-preview dan 2025-02-01-preview

• API Respons
• Penggunaan komputer

Perubahan antara 2025-02-01-preview dan 2025-01-01-preview

• Penyelesaian tersimpan (dukungan API penyulingan).

Perubahan antara 2025-01-01-preview dan 2024-12-01-preview

• prediction parameter ditambahkan untuk dukungan output terprediksi.
• gpt-4o-audio-preview dukungan untuk model.

Perubahan antara 2024-12-01-preview dan 2024-10-01-preview

• store, dan parameter metadata ditambahkan untuk mendukung penyelesaian tersimpan.
• reasoning_effortditambahkan untuk model penalaran terbaru.
• user_security_contextditambahkan untuk integrasi Microsoft Defender untuk Cloud.

Perubahan antara 2024-09-01-preview dan 2024-08-01-preview

• max_completion_tokens ditambahkan untuk mendukung model o1-preview dan o1-mini. max_tokens tidak berfungsi dengan model seri o1 .
• parallel_tool_calls ditambahkan.
• completion_tokens_details & reasoning_tokens ditambahkan.
• stream_options & include_usage ditambahkan.

Perubahan antara spesifikasi API 2024-07-01-preview dan 2024-08-01-preview

• Output terstruktur dukungan.
• API unggahan file besar ditambahkan.
• Tentang perubahan data Anda:
  • Integrasi MongoDB.
  • role_information parameter dihapus.
  • rerank_score ditambahkan ke objek kutipan.
  • Sumber data AML dihapus.
  • Peningkatan pada integrasi vektorisasi pencarian AI.

Perubahan antara spesifikasi API 2024-05-01-preview dan 2024-07-01-preview

• Dukungan API Batch ditambahkan
• Parameter strategi segmentasi penyimpanan vektor
• max_num_results bahwa alat pencarian file seharusnya menghasilkan.

Perubahan antara spesifikasi API 2024-04-01-preview dan 2024-05-01-preview

• Dukungan Asisten v2 - Alat pencarian file dan penyimpanan vektor
• Menyempurnakan titik pemeriksaan, benih, peristiwa
• Pada pembaruan data Anda
• DALL-E 2 sekarang mendukung implementasi model dan dapat digunakan dengan API pratinjau terbaru.
• Pembaruan pemfilteran konten

Perubahan antara spesifikasi API 2024-03-01-preview dan 2024-04-01-preview

• Perubahan Mengganggu: Parameter penyempurnaan dihapus. Ini berdampak pada gpt-4Versi:vision-preview model.
• parameter timestamp_granularities ditambahkan.
• audioWord objek ditambahkan.
• Tambahan TTS response_formats: wav & pcm.

Masalah yang diketahui

• Spesifikasi 2025-04-01-preview Azure OpenAI menggunakan OpenAPI 3.1. Ini adalah masalah umum bahwa versi ini tidak sepenuhnya didukung oleh Azure API Management.

Langkah selanjutnya

• Bahasa pemrograman yang didukung untuk API v1
• Model-model Foundry yang dijual langsung oleh Azure
• Bekerja dengan model Azure OpenAI
• Kuota dan batasan Azure OpenAI
• Spesifikasi v1 OpenAPI 3.0