Menggunakan AZURE OpenAI Responses API

Gunakan Azure OpenAI Responses API untuk menghasilkan respons multi-giliran yang bersifat stateful. Ini menggabungkan kemampuan dari penyelesaian percakapan dan API Asisten dalam satu pengalaman yang menyatu. Gunakan orkestrasi multi-agen untuk mendelegasikan pekerjaan independen ke subagen paralel, atau gunakan pencarian alat untuk memuat definisi alat hanya ketika model membutuhkannya. API Respons juga mendukung computer-use-preview model yang mendukung penggunaan Komputer.

Untuk deskripsi parameter permintaan dan respons lengkap, lihat referensi parameter API Respons.

Prasyarat

  • Model Azure OpenAI yang diterapkan.
  • Metode autentikasi:
    • Kunci API (misalnya, AZURE_OPENAI_API_KEY), atau
    • Microsoft Entra ID (disarankan).
  • Instal pustaka klien untuk bahasa Anda:
    • Python:pip install openai azure-identity
    • .NET: dotnet add package OpenAI dan dotnet add package Azure.Identity
    • JavaScript/TypeScript: npm install openai @azure/identity
    • Java: Tambahkan com.openai:openai-java dan com.azure:azure-identity ke proyek Anda.
  • Untuk contoh REST, atur AZURE_OPENAI_API_KEY (alur kunci API) atau AZURE_OPENAI_AUTH_TOKEN (alur Microsoft Entra ID).

Wilayah yang didukung

Sebelum menjalankan contoh dalam artikel ini, konfirmasikan bahwa wilayah sumber daya Anda mendukung API Respons. API v1 diperlukan untuk mengakses fitur terbaru. Untuk detailnya, lihat siklus hidup versi API. Untuk dukungan regional Foundry Agent Service, lihat tabel ketersediaan regional. API Respons saat ini tersedia di wilayah berikut:

  • AustraliaEast
  • brasilouth
  • kanadacentral
  • kanada timur
  • centralus
  • eastus
  • eastus2
  • francecentral
  • Jerman Barat Tengah
  • italynorth
  • japaneast
  • japanwest
  • koreacentral
  • northcentralus
  • norwayeast
  • polandcentral
  • southafricanorth
  • southcentralus
  • southeastasia
  • India Selatan
  • spaincentral
  • swedencentral
  • Swiss Utara
  • switzerlandwest
  • uaenorth
  • uksouth
  • ukwest
  • westcentralus
  • westeurope
  • westus
  • westus2
  • westus3

Model yang didukung

API Respons mendukung model berikut:

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

Tidak setiap model tersedia di setiap wilayah yang didukung. Periksa halaman model untuk ketersediaan wilayah model.

Catatan

Saat ini tidak didukung:

  • Pembuatan gambar menggunakan pengeditan dan streaming multi-giliran.

Ada masalah yang diketahui dengan hal berikut:

  • PDF sebagai file input sekarang didukung, tetapi mengatur tujuan unggahan file user_data saat ini tidak didukung.
  • Masalah performa saat mode latar belakang digunakan dengan streaming. Microsoft berupaya mengatasi masalah ini.

Membuat respons teks

Buat respons teks sederhana menggunakan API Respons. Ganti YOUR-RESOURCE-NAME dan MODEL_NAME dengan nilai penyebaran Anda.

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

Contoh tanggapan

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

Mengambil tanggapan

Ambil respons dengan ID-nya dari panggilan API Respons sebelumnya.

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

Contoh tanggapan

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

Menghapus respons

Secara default, data respons disimpan selama 30 hari. Hapus respons tersimpan menurut 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)

Menautkan respons bersama

Rantai berubah dengan meneruskan ID respons sebelumnya ke 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)

Pengurutan respons secara manual

Atau, Anda dapat meneruskan item output secara manual dalam permintaan berikutnya.

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

Padatkan Respons

Kompaksi mengurangi konteks masukan sambil mempertahankan status esensial untuk giliran berikutnya.

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)

Padatkan menggunakan item yang dikembalikan

Anda dapat memadatkan semua item yang dikembalikan dari permintaan-permintaan sebelumnya seperti penalaran, pesan, pemanggilan fungsi, dan lain-lain.

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)

Kompres dengan ID respons sebelumnya

Anda juga dapat memampatkan menggunakan ID respons sebelumnya.

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)

Pemadatan pada sisi server

Anda juga dapat menggunakan pemadatan sisi server secara langsung di Respons (POST /responses atau client.responses.create) dengan mengatur context_management dengan compact_threshold.

  • Saat jumlah token output melewati ambang batas yang dikonfigurasi, API Respons secara otomatis menjalankan pemadatan.
  • Dalam mode ini, Anda tidak perlu memanggil /responses/compact secara terpisah.
  • Respon mencakup elemen pemadatan terenkripsi.
  • Pemadatan sisi server akan berfungsi saat Anda mengatur store=false pada Permintaan pembuatan Respons Anda.

Item kompresi membawa status dan penalaran penting sebelumnya ke siklus berikutnya dengan menggunakan lebih sedikit token. Ini buram dan tidak dimaksudkan untuk dibaca manusia.

Jika Anda menggunakan perangkaian input-array stateless, tambahkan item output seperti biasanya. Jika Anda menggunakan previous_response_id, kirimkan hanya pesan dari pengguna baru pada setiap giliran. Di kedua pola, item pemadatan membawa konteks yang diperlukan untuk jendela berikutnya.

Tips

Setelah menambahkan item output ke item input sebelumnya, Anda dapat menghilangkan item yang datang sebelum item pemadatan terbaru untuk menjaga permintaan lebih kecil dan mengurangi latensi ekor panjang. Item pemadatan terbaru ini membawa konteks yang diperlukan untuk meneruskan percakapan. Jika Anda menggunakan previous_response_id rantai, jangan memangkas secara manual.

Flow

  1. Hubungi responses seperti biasa. Tambahkan context_management dengan compact_threshold untuk mengaktifkan pemadatan sisi server.
  2. Jika output melewati ambang batas, layanan memicu pemadatan, memancarkan item pemadatan dalam aliran output, dan memangkas konteks sebelum melanjutkan inferensi.
  3. Lanjutkan percakapan menggunakan salah satu pola ini:
    1. Rangkaian array input tanpa status: tambahkan elemen keluaran, termasuk elemen pemadatan, ke array input berikutnya.
    2. previous_response_id chaining: teruskan hanya pesan pengguna baru pada setiap giliran dan teruskan ID respons terbaru.

Contoh

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

Alirkan respons saat dihasilkan dengan menetapkan stream=true. Layanan ini menghasilkan event inkremental yang dapat Anda gunakan untuk merender output token demi token.

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

Selama proses streaming, jika terjadi kesalahan di tengah proses, sistem akan melakukan percobaan ulang secara internal untuk mengatasi kesalahan tersebut. Jika permintaan masih gagal, layanan mengalami kesalahan yang tidak dapat dipulihkan. Dalam kasus ini, kode respons HTTP adalah 200 (berhasil), tetapi event error dalam stream menyertakan detail tentang error yang terjadi di tengah stream.

Server mengembalikan jenis kesalahan berikut:

Jenis kesalahan Dapat diterjemahkan sebagai
server_error Mengembalikan kode 500
too_many_requests Mengembalikan kode 429
forbidden Mengembalikan kode 403
user_error Mengembalikan kode 400

Contoh peristiwa kesalahan:

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

Aplikasi harus mendeteksi kesalahan ini dan menghentikan atau memulai ulang streaming dengan lancar. Anda tidak dikenakan biaya untuk token yang dihasilkan selama respons streaming yang gagal.

Output terstruktur

Gunakan output terstruktur untuk membuat respons mengikuti Skema JSON. Dalam permintaan API Respons, tentukan skema di text.format. Chat Completions menggunakan response_format sebagai penggantinya. Untuk contoh SDK dan REST, batasan skema yang didukung, dan batasan, lihat Output terstruktur.

Pemanggilan fungsi

API Respons mendukung panggilan fungsi.

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)

Menangani pagar pembatas dan pemfilteran konten

Pagar pembatas (filter konten) diterapkan pada tingkat penyebaran dan berjalan secara otomatis pada setiap panggilan API Respons, sehingga mereka melindungi input yang Anda kirim dan output yang dihasilkan model. Anda mengonfigurasi pagar pembatas secara terpisah. Untuk informasi selengkapnya, lihat Mengonfigurasi pagar pembatas dan kontrol. Bagian ini menjelaskan cara mendeteksi dan menangani hasil pagar pengaman saat Anda memanggil API Responses.

API Respons menampilkan hasil pagar pembatas secara berbeda dari penyelesaian obrolan. Alih-alih kolom prompt_filter_results dan content_filter_results yang dikembalikan oleh chat completions, objek respons mencakup array content_filters tingkat atas. Setiap entri menjelaskan satu hasil filter.

Field Deskripsi
blocked Apakah isi diblokir.
source_type Apakah hasilnya berlaku untuk prompt (input) atau completion (output).
content_filter_results Hasil kategori, seperti hate, , sexualviolence, dan self_harm dengan tingkat keparahan, ditambah kategori opsional seperti jailbreak, , indirect_attackprotected_material_text, dan protected_material_code.
content_filter_offsets Offset karakter yang diterapkan pada hasil.

Catatan

Array content_filters adalah ekstensi Microsoft Foundry yang bukan bagian dari skema respons OpenAI dasar, sehingga SDK tidak mengekspos properti yang diketik untuknya. Baca sebagai kolom mentah atau kolom tambahan, seperti yang ditunjukkan dalam contoh berikut.

Mendeteksi input yang diblokir

Saat pagar pembatas memblokir input Anda, API mengembalikan kesalahan HTTP 400 dengan kode content_filter. Tangani error ini untuk menangani prompt yang diblokir dengan baik.

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

Membaca anotasi pagar pembatas

Ketika permintaan berhasil, baca larik content_filters di dalam respons untuk meninjau hasil guardrail untuk input dan output.

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

Untuk mempelajari selengkapnya tentang kategori pagar pembatas dan tingkat keparahan, lihat Gambaran umum Pagar pembatas dan Bekerja dengan anotasi.

Penerjemah Kode

Alat Penerjemah Kode memungkinkan model untuk menulis dan menjalankan kode Python di lingkungan yang aman dan sandbox. Ini mendukung berbagai tugas tingkat lanjut, termasuk:

  • Memproses file dengan format dan struktur data yang bervariasi
  • Membuat file yang menyertakan data dan visualisasi (misalnya, grafik)
  • Menulis dan menjalankan kode secara berulang untuk menyelesaikan masalah—model dapat men-debug dan mencoba kembali kode hingga berhasil
  • Meningkatkan penalaran visual dalam model yang didukung (misalnya, o3, o4-mini) dengan mengaktifkan transformasi gambar seperti pemotongan, perbesar tampilan, dan rotasi
  • Alat ini sangat berguna untuk skenario yang melibatkan analisis data, komputasi matematika, dan pembuatan kode.
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)

Kontainer

Penting

Penerjemah Kode memiliki biaya tambahan di luar biaya berbasis token untuk penggunaan Azure OpenAI. Jika API Respons Anda memanggil Penerjemah Kode secara bersamaan dalam dua utas yang berbeda, dua sesi Penerjemah Kode dibuat. Setiap sesi dikenakan biaya per menit, dengan biaya minimum lima menit. Sesi tetap aktif selama Anda masih mengakses containernya dalam batas waktu diam 20 menit.

Alat Penerjemah Kode memerlukan wadah—mesin virtual yang terisolasi sepenuhnya di mana model dapat menjalankan kode Python. Kontainer dapat berisi file yang diunggah atau file yang dihasilkan saat eksekusi.

Untuk membuat kontainer, tentukan "container": { "type": "auto", "file_ids": ["file-1", "file-2"] } dalam konfigurasi alat saat membuat objek Respons baru. Ini secara otomatis membuat kontainer baru atau menggunakan kembali kontainer aktif dari code_interpreter_call sebelumnya dalam konteks model. code_interpreter_call dalam output API akan berisi container_id yang dihasilkan. Kontainer ini kedaluwarsa jika tidak digunakan selama 20 menit.

Batas file berikut berlaku:

  • Permintaan dapat mencakup hingga 50 ID file.
  • Kontainer dapat menampung hingga total 1.000 file, termasuk file input dan file yang dihasilkan oleh Penerjemah Kode.

Input dan Output File

Saat menjalankan Penerjemah Kode, model dapat membuat filenya sendiri. Misalnya, jika Anda memintanya untuk membuat plot, atau membuat CSV, itu membuat gambar-gambar ini langsung di kontainer Anda. Ini akan mengutip file-file ini dalam anotasi pesan berikutnya.

File apa pun dalam input model diunggah secara otomatis ke kontainer. Anda tidak perlu mengunggahnya secara eksplisit ke kontainer.

File yang Didukung

Format file Jenis MIME
.c text/x-c
.cs text/x-csharp
.cpp text/x-c++
.csv text/csv
.doc application/msword (format dokumen Microsoft Word)
.docx application/vnd.openxmlformats-officedocument.wordprocessingml.document
.html teks/html
.java text/x-java
.json application/json
.md teks/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 teks/biasa
.css text/css
.js text/JavaScript
.sh application/x-sh
.ts application/TypeScript
.csv application/csv
.jpeg gambar/jpeg
.jpg gambar/jpeg
.gif gambar/gif
.pkl application/octet-stream
.png image/png
.tar application/x-tar
.xlsx application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
.xml application/xml atau "text/xml"
.zip application/zip

Mencantumkan item input

Ambil item masukan yang dikirim dalam respons. Ini berguna untuk meninjau konteks lengkap percakapan, termasuk setiap item yang ditambahkan oleh model (misalnya, panggilan fungsi atau item kompaksi).

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

Contoh tanggapan

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

Input gambar

Model yang mendukung visi dapat menginterpretasikan gambar bersama teks. Mereka dapat mengenali objek, bentuk, warna, dan tekstur, dan membaca teks yang terkandung dalam gambar, tunduk pada batasan yang tercantum nanti dalam artikel ini.

Anda dapat memberikan gambar sebagai input ke permintaan dengan salah satu cara berikut:

  • URL yang sepenuhnya memenuhi syarat untuk file gambar
  • URI data yang dikodekan Base64
  • ID file yang dibuat dengan FILES API

URL gambar

Mereferensikan gambar yang dihosting di URL publik. Model mengambil gambar dan menyertakannya sebagai bagian dari konten 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)

Gambar yang dikodekan Base64

Kirim gambar sebaris dengan mengodekan bytenya sebagai URI data base64. Gunakan pola ini saat gambar tidak tersedia di URL publik atau saat Anda ingin menghindari permintaan jaringan tambahan.

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)

Identifikasi Berkas

Unggah gambar dengan Files API dengan menggunakan purpose="assistants", lalu referensikan ID file yang dikembalikan dalam permintaan Anda. Pendekatan ini berguna ketika Anda ingin menggunakan kembali gambar yang sama di beberapa permintaan tanpa mengirim ulang byte-nya.

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)

Persyaratan input gambar

Tabel berikut mencantumkan jenis file yang didukung untuk input gambar.

Jenis file Jenis MIME
PNG image/png
JPEG image/jpeg
WebP image/webp
GIF non-animasi image/gif

Dalam satu permintaan, Anda dapat menyertakan hingga 50 gambar. Setiap file gambar individu harus di bawah 50 MB, dan ukuran gabungan semua gambar dalam permintaan juga harus di bawah 50 MB.

Gambar harus memenuhi persyaratan tambahan ini:

  • Gambar harus relevan dengan perintah; model tidak dirancang untuk konten visual yang tidak terkait.
  • Gambar tidak boleh berisi konten berbahaya atau sensitif yang melanggar kebijakan konten.
  • File gambar tidak dapat rusak atau tidak dapat dibaca. Jika model tidak dapat memproses gambar, permintaan gagal.

Pilih tingkat detail gambar

detail Gunakan properti pada input_image bagian konten untuk mengontrol cara model memproses gambar. Detail yang lebih rendah menggunakan lebih sedikit token dan lebih cepat, sementara detail yang lebih tinggi menggunakan lebih banyak token tetapi memungkinkan model menangkap fitur yang lebih halus.

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

Tabel berikut ini menjelaskan setiap tingkat detail.

Tingkat detail Deskripsi
low Model ini menggunakan versi gambar beresolusi lebih rendah. Opsi ini menggunakan token terkecil dan menghasilkan respons tercepat, tetapi model mungkin melewatkan detail yang baik.
high Model ini menggunakan versi gambar beresolusi lebih tinggi. Opsi ini menangkap detail yang lebih halus tetapi menggunakan lebih banyak token dan membutuhkan waktu lebih lama untuk merespons.
auto Standar. Model memilih tingkat detail yang sesuai berdasarkan gambar dan perintah.

Batasan input gambar

Model berkemampuan visi memiliki batasan berikut:

  • Gambar medis: Model ini tidak cocok untuk menafsirkan gambar medis khusus seperti pemindaian CT dan tidak boleh digunakan untuk saran medis.
  • Teks non-Bahasa Inggris: Model mungkin tidak berkinerja optimal saat menangani gambar yang berisi teks dalam alfabet non-Latin, seperti Jepang atau Korea.
  • Teks kecil: Perbesar teks dalam gambar untuk meningkatkan keterbacaan, tetapi hindari memotong detail penting.
  • Rotasi: Model mungkin salah menafsirkan teks dan gambar yang diputar atau terbalik.
  • Elemen visual: Model mungkin kesulitan dengan grafik atau teks yang warna atau gayanya—seperti garis utuh, putus-putus, atau titik-titik—bervariasi.
  • Penalaran spasial: Model mengalami kesulitan dengan tugas yang memerlukan pelokalan spasial yang tepat, seperti mengidentifikasi posisi catur.
  • Akurasi: Model mungkin menghasilkan deskripsi atau keterangan yang salah dalam beberapa kasus.
  • Bentuk gambar: Model mengalami kesulitan dengan gambar panorama dan mata ikan.
  • Metadata dan mengubah ukuran: Model tidak memproses nama file atau metadata asli, dan gambar diubah ukurannya sebelum analisis, yang memengaruhi dimensi aslinya.
  • Penghitungan: Model mungkin memberikan perkiraan hitungan untuk objek dalam gambar.
  • CAPTCHAs: Untuk alasan keamanan, sistem tersedia untuk memblokir pengiriman CAPTCHAs.

Input file

Model dengan kemampuan penglihatan mendukung input PDF. File PDF dapat disediakan baik sebagai data yang dikodekan Base64 atau sebagai ID file. Untuk membantu model menafsirkan konten PDF, teks yang diekstrak dan gambar setiap halaman disertakan dalam konteks model. Ini berguna ketika informasi utama disampaikan melalui diagram atau konten non-tekstual.

Catatan

  • Semua teks dan gambar yang diekstrak dimasukkan ke dalam konteks model. Pastikan Anda memahami implikasi harga dan penggunaan token menggunakan PDF sebagai input.
  • Dalam satu permintaan API, Anda dapat menyertakan lebih dari satu file, tetapi setiap file harus di bawah 50 MB. Batas gabungan di semua file dalam permintaan adalah 50 MB.
  • Hanya model yang mendukung input teks dan gambar yang dapat menerima file PDF sebagai input.
  • Sebuah purposeuser_data saat ini tidak didukung. Sebagai solusi sementara, Anda harus mengatur tujuan ke assistants.

Mengonversi PDF ke Base64 dan menganalisis

Kirim PDF sebaris dengan mengodekan bytenya sebagai URI data base64. Model menerima teks yang diekstrak dan gambar yang dirender dari setiap halaman.

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)

Unggah PDF dan analisis

Unggah file PDF dengan purpose="assistants". Satu purpose dari user_data saat ini tidak didukung.

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)

Menggunakan server MCP jarak jauh

Anda dapat memperluas kemampuan model Anda dengan menghubungkannya ke alat yang dihosting di server Protokol Konteks Model Jarak Jauh (MCP). Server ini dikelola oleh pengembang dan organisasi dan mengekspos alat yang dapat diakses oleh klien yang kompatibel dengan MCP, seperti API Respons.

Model Context Protocol (MCP) adalah standar terbuka yang menentukan bagaimana aplikasi menyediakan alat dan data kontekstual ke model bahasa besar (LLM). Ini memungkinkan integrasi alat eksternal yang konsisten dan dapat diskalakan ke dalam alur kerja model.

Contoh berikut menunjukkan cara menggunakan server MCP jarak jauh untuk mengkueri informasi tentang repositori REST API Azure. Model mengambil dan menalar berdasarkan konten repositori secara waktu nyata.

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)

Alat MCP hanya berfungsi di Responses API, dan tersedia di semua model yang lebih baru (gpt-4o, gpt-4.1, dan model penalaran kami). Saat menggunakan alat MCP, Anda hanya membayar token yang digunakan saat mengimpor definisi alat atau melakukan panggilan alat—tidak ada biaya tambahan yang terlibat.

Persetujuan

Secara default, API Respons memerlukan persetujuan eksplisit sebelum data dibagikan dengan server MCP jarak jauh. Langkah persetujuan ini membantu memastikan transparansi dan memberi Anda kontrol atas informasi apa yang dikirim secara eksternal.

Sebaiknya tinjau semua data yang dibagikan dengan server MCP jarak jauh dan secara opsional mencatatnya untuk tujuan audit.

Saat diperlukan persetujuan, model mengembalikan item mcp_approval_request dalam hasil respons. Objek ini berisi detail permintaan yang tertunda dan memungkinkan Anda memeriksa atau memodifikasi data sebelum melanjutkan.

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

Untuk melanjutkan panggilan MCP jarak jauh, Anda harus menanggapi permintaan persetujuan dengan membuat objek respons baru yang menyertakan item mcp_approval_response. Objek ini mengonfirmasi niat Anda untuk mengizinkan model mengirim data yang ditentukan ke server MCP jarak jauh.

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)

Otentikasi

Penting

  • Klien MCP dalam API Respons memerlukan TLS 1.2 atau lebih tinggi.
  • TLS Bersama (mTLS) saat ini tidak didukung.
  • Tag layanan Azure saat ini tidak didukung untuk lalu lintas klien MCP.

Tidak seperti server MCP GitHub, sebagian besar server MCP jarak jauh memerlukan autentikasi. Alat MCP di API Respons mendukung header kustom, memungkinkan Anda terhubung dengan aman ke server ini menggunakan skema autentikasi yang mereka butuhkan.

Anda dapat menentukan header seperti kunci API, token akses OAuth, atau info masuk lainnya langsung dalam permintaan Anda. Header yang paling umum digunakan adalah Authorization header .

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)

Tugas latar belakang

Mode latar belakang memungkinkan Anda menjalankan tugas jangka panjang secara asinkron dengan model penalaran seperti o3 dan o1-pro. Ini berguna untuk tugas kompleks yang dapat memakan waktu beberapa menit untuk diselesaikan (misalnya, agen gaya Codex- atau Deep Research). Ketika permintaan dikirim dengan "background": true, tugas diproses secara asinkron, dan Anda melakukan polling untuk statusnya.

Memulai tugas latar belakang

Atur background=true pada permintaan untuk mengantre tugas. Layanan segera kembali dengan ID respons dan queued status — gunakan ID tersebut untuk melakukan polling, streaming, atau membatalkan tugas.

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)

Periksa status hingga selesai

Lanjutkan polling saat statusnya adalah queued atau in_progress. Setelah respons mencapai status akhir, respons tersebut dapat diambil.

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

Membatalkan tugas latar belakang

Batalkan tugas latar belakang yang sedang berjalan dengan endpoint cancel. Pembatalan bersifat idempotensi—panggilan berikutnya mengembalikan objek respons akhir.

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

Untuk melakukan streaming respons latar belakang, atur background dan stream ke true. Pola ini memungkinkan Anda melanjutkan streaming jika koneksi terputus. Lacak posisi Anda dengan sequence_number dari setiap acara.

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"]

Respons latar belakang saat ini memiliki latensi time-to-first-token yang lebih tinggi daripada respons sinkron. Penyempurnaan sedang berlangsung untuk mengurangi kesenjangan ini.

Keterbatasan

  • Mode latar belakang memerlukan store=true. Permintaan stateless tidak didukung.
  • Anda hanya dapat melanjutkan streaming jika permintaan asli disertakan stream=true.
  • Untuk membatalkan respons sinkron, hentikan koneksi secara langsung.

Melanjutkan streaming dari titik tertentu

Jika koneksi streaming terputus, Anda dapat melanjutkan dari peristiwa yang diketahui dengan meneruskan stream=true bersama starting_after=<sequence_number> pada GET ke respons. Layanan memutar ulang peristiwa yang dihasilkan setelah nomor urutan tersebut.

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"

Item penalaran yang terenkripsi

Saat Anda menggunakan Responses API dalam mode tanpa status (store=false), Anda tetap harus menjaga konteks penalaran di berbagai giliran percakapan. Untuk melakukan ini, sertakan item penalaran terenkripsi dalam permintaan Anda.

Untuk mempertahankan item penalaran antar-giliran, tambahkan reasoning.encrypted_content ke parameter include. Respons kemudian berisi versi terenkripsi dari jejak penalaran, yang dapat Anda teruskan ke permintaan di masa mendatang.

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)

API Respons memungkinkan pembuatan gambar sebagai bagian dari percakapan dan alur kerja multi-langkah. Ini mendukung input dan output gambar dalam konteks, dan mencakup alat bawaan untuk menghasilkan dan mengedit gambar.

Dibandingkan dengan API Gambar mandiri, Api Respons menawarkan dua keuntungan:

  • Streaming: Menampilkan output gambar parsial selama pembuatan untuk meningkatkan latensi yang dirasakan.
  • Input fleksibel: Terima ID file gambar sebagai input selain byte gambar mentah.

Catatan

Alat pembuatan gambar di API Respons didukung oleh gpt-image-1model seri, dan Anda dapat memanggilnya dari serangkaian model obrolan dan penalaran yang kompatibel. Untuk daftar model orkestrasi yang didukung saat ini, lihat bagian Model yang didukung nanti di artikel ini.

Alat pembuatan gambar saat ini tidak mendukung mode streaming. Untuk melakukan streaming gambar parsial, panggil API pembuatan gambar langsung di luar API Respons.

Gunakan API Respons untuk membangun pengalaman gambar percakapan dengan model Gambar 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]))

Model penalaran

Untuk contoh cara menggunakan model penalaran dengan API respons, lihat panduan model penalaran.

Penggunaan komputer

Penggunaan komputer dengan Playwright telah berpindah ke panduan model penggunaan komputer khusus.

Pemecahan masalah

  • 401/403: Jika Anda menggunakan Microsoft Entra ID, verifikasi bahwa token Anda ditetapkan untuk https://ai.azure.com/.default. Jika Anda menggunakan kunci API, konfirmasikan bahwa Anda menggunakan kunci yang benar untuk sumber daya.
  • 404: Konfirmasikan model cocok dengan nama penyebaran Anda.

Konten terkait

  • Last updated on