Azure OpenAI 응답 API 사용

Azure OpenAI 응답 API를 사용하여 상태 저장 다중 턴 응답을 생성합니다. 채팅 완료와 Assistants API의 기능을 하나의 통합된 환경으로 결합합니다. 응답 API는 computer-use-preview 지원하는 모델도 지원합니다.

필수 구성 요소

  • 배포된 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 흐름)을 설정합니다.

지원되는 지역

이 문서의 예제를 실행하기 전에 리소스 지역이 응답 API를 지원하는지 확인합니다. v1 API는 최신 기능에 액세스하는 데 필요합니다. 자세한 내용은 API 버전 수명 주기를 참조하세요. 응답 API는 현재 다음 지역에서 사용할 수 있습니다.

  • australiaeast
  • brazilsouth
  • canadacentral
  • 캐나다이스트
  • eastus
  • eastus2
  • francecentral
  • 독일웨스트센트럴
  • italynorth
  • japaneast
  • koreacentral
  • northcentralus
  • 노르웨이 동부
  • polandcentral
  • southafricanorth
  • southcentralus
  • 동남 아시아
  • 남인도
  • spaincentral
  • swedencentral
  • switzerlandnorth
  • uaenorth
  • uksouth
  • westus
  • westus3

지원되는 모델

응답 API는 다음 모델을 지원합니다.

  • gpt-chat-latest (버전: 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)
  • o1 (버전: 2024-12-17)
  • o3-mini (버전: 2025-01-31)
  • o3 (버전: 2025-04-16)
  • o4-mini (버전: 2025-04-16)

지원되는 모든 지역에서 모든 모델을 사용할 수 있는 것은 아닙니다. 모델 영역 가용성에 대한 모델 페이지를 확인합니다. 전체 요청 및 응답 매개 변수 집합은 응답 API 참조 설명서를 참조하세요.

참고

현재 지원되지 않음:

  • 다중 턴 편집 및 스트리밍을 사용하여 이미지 생성
  • 이미지를 파일로 업로드한 다음 입력으로 참조할 수 없습니다.

다음과 같은 알려진 문제가 있습니다.

  • 이제 PDF를 입력 파일로 사용할 수 있지만 파일 업로드 용도를 user_data 설정하는 것은 현재 지원되지 않습니다.
  • 백그라운드 모드가 스트리밍과 함께 사용될 때 성능 문제가 발생합니다. Microsoft 이 문제를 해결하기 위해 노력하고 있습니다.

텍스트 응답 생성

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

응답을 함께 연결

이전 응답 ID 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_management 또는 compact_threshold에서 응답의 서버 측 압축을 직접 사용할 수도 있습니다.

  • 출력 토큰 수가 구성된 임계값을 초과하면 응답 API가 자동으로 압축을 실행합니다.
  • 이 모드에서는 별도로 호출 /responses/compact 할 필요가 없습니다.
  • 응답에는 암호화된 압축 항목이 포함됩니다.
  • 응답 만들기 요청에 store=false를 설정하면 서버 쪽 압축이 작동합니다.

압축 항목은 더 적은 토큰을 사용하여 필수 이전 상태 및 추론을 다음 턴으로 전달합니다. 그것은 불투명하고 인간이 읽을 수 있도록 의도되지 않았습니다.

상태 저장되지 않은 입력 배열 체인을 사용하는 경우, 출력 항목을 평소처럼 추가하십시오. 사용하는 previous_response_id경우 각 턴에 새 사용자 메시지만 전달합니다. 두 패턴 모두에서 압축 항목은 다음 창에 필요한 컨텍스트를 전달합니다.

팁

이전 입력 항목에 출력 항목을 추가한 후 가장 최근의 압축 항목 앞에 나온 항목을 삭제하여 요청을 더 작게 유지하고 긴 지연 시간을 줄일 수 있습니다. 최신 압축 항목은 대화를 계속하는 데 필요한 컨텍스트를 전달합니다. previous_response_id 체인을 사용하는 경우에는 수동으로 가지치기하지 마십시오.

흐름

  1. 평소처럼 responses을 호출합니다. context_management와 compact_threshold을 추가하여 서버 측 압축을 활성화하십시오.
  2. 출력이 임계값을 초과하면 서비스는 압축을 트리거하고, 출력 스트림에서 압축 항목을 내보내고, 유추를 계속하기 전에 컨텍스트를 정리합니다.
  3. 다음 패턴 중 하나를 사용하여 대화를 계속합니다.
    1. 무상태 입력 배열 연결: 압축 항목을 포함한 출력 항목을 다음 입력 배열에 추가합니다.
    2. previous_response_id 체이닝: 각 턴마다 새로운 사용자 메시지만 전달하고 최신 응답 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를 설정하여 생성되는 대로 응답을 스트리밍합니다. 서비스는 출력 토큰을 토큰별로 렌더링하는 데 사용할 수 있는 증분 이벤트를 내보냅니다.

참고

스트리밍하는 동안 서비스에서 토큰 제한 또는 구문 분석 문제와 같은 오류가 발생하는 경우 응답 API는 오류 이벤트(500429및 유사한 오류)를 반환할 수 있습니다. 애플리케이션은 이 이벤트를 감지하고 스트리밍을 정상적으로 중지하거나 다시 시작해야 합니다. 실패한 스트리밍 응답 중에 생성된 토큰에 대해서는 요금이 청구되지 않습니다.

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

함수 호출

응답 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를 호출할 때 가드레일 결과를 검색하고 처리하는 방법을 보여 줍니다.

응답 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 기본 OpenAI 응답 스키마의 일부가 아닌 Microsoft Foundry 확장이므로 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 배열을 읽어 입력 및 출력에 대한 가드레일 결과를 확인합니다.

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

가드레일 범주 및 심각도 수준에 대해 자세히 알아보려면 Guardrails 개요 및 주석 작업을 참조하세요.

코드 인터프리터

코드 인터프리터 도구를 사용하면 모델이 안전한 샌드박스 환경에서 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)

컨테이너

중요

코드 인터프리터에는 Azure OpenAI 사용에 대한 토큰 기반 요금 외에 추가 요금이 있습니다. 응답 API가 서로 다른 두 스레드에서 동시에 코드 인터프리터를 호출하는 경우 두 개의 코드 인터프리터 세션이 만들어집니다. 각 세션은 기본적으로 1시간 동안 활성화되며 유휴 시간 제한은 20분입니다.

코드 인터프리터 도구에는 모델이 Python 코드를 실행할 수 있는 완전히 샌드박스가 있는 가상 머신인 컨테이너가 필요합니다. 컨테이너는 실행 중에 생성된 업로드된 파일 또는 파일을 포함할 수 있습니다.

컨테이너를 만들려면 새 Response 개체를 만들 때 도구 구성에서 지정 "container": { "type": "auto", "file_ids": ["file-1", "file-2"] } 합니다. 그러면 새 컨테이너가 자동으로 만들어지거나 모델의 컨텍스트에서 이전 code_interpreter_call 활성 컨테이너를 다시 사용합니다. API의 출력에 포함된 code_interpreter_call 은 생성된 container_id 를 담고 있습니다. 이 컨테이너는 20분 동안 사용되지 않으면 만료됩니다.

파일 입력 및 출력

코드 인터프리터를 실행할 때 모델은 자체 파일을 만들 수 있습니다. 예를 들어 플롯을 생성하거나 CSV를 만들도록 요청하는 경우 컨테이너에 직접 이러한 이미지를 만듭니다. 다음 메시지 주석에서 이러한 파일을 인용합니다.

모델 입력의 모든 파일은 컨테이너에 자동으로 업로드됩니다. 컨테이너에 명시적으로 업로드할 필요는 없습니다.

지원되는 파일

파일 형식 MIME 형식
.c text/x-c
.cs text/x-csharp
.cpp text/x-c++
.csv text/csv
.doc application/msword
.docx application/vnd.openxmlformats-officedocument.wordprocessingml.document
.html text/html
.java text/x-java
.json application/json
.md text/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 text/plain
.css text/css
.js text/JavaScript
.sh application/x-sh
.ts application/TypeScript
.csv application/csv
.jpeg image/jpeg
.jpg image/jpeg
.gif image/gif
.pkl application/octet-stream
.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."}]
    }
  ]
}

이미지 입력

비전 지원 모델은 텍스트와 함께 이미지를 해석할 수 있습니다. 개체, 도형, 색 및 질감을 인식하고 이미지에 포함된 텍스트를 읽을 수 있으며, 이 문서의 뒷부분에 나열된 제한 사항에 따릅니다.

다음 방법 중 하나로 요청에 대한 입력으로 이미지를 제공할 수 있습니다.

  • 이미지 파일에 대한 정규화된 URL
  • Base64로 인코딩된 데이터 URI
  • 파일 API를 사용하여 만든 파일 ID

이미지 URL

공용 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 데이터 URI로 인코딩하여 이미지를 인라인으로 보냅니다. 이미지가 공용 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="vision"이미지를 업로드한 다음, 요청에서 반환된 파일 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="vision",
        )
        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

단일 요청에서 최대 100개의 이미지를 포함할 수 있습니다. 각 개별 이미지 파일은 50MB 미만이어야 하며 요청에 있는 모든 이미지의 결합 크기도 50MB 미만이어야 합니다.

이미지는 다음 추가 요구 사항을 충족해야 합니다.

  • 이미지는 프롬프트와 관련이 있어야 합니다. 모델은 관련 없는 시각적 콘텐츠용으로 설계되지 않았습니다.
  • 이미지에는 콘텐츠 정책을 위반하는 유해하거나 민감한 콘텐츠가 포함되어서는 안 됩니다.
  • 이미지 파일을 손상하거나 읽을 수 없습니다. 모델이 이미지를 처리할 수 없으면 요청이 실패합니다.

이미지 세부 정보 수준 선택

콘텐츠 파트의 detail 속성을 input_image 사용하여 모델이 이미지를 처리하는 방법을 제어합니다. 세부 정보가 낮을수록 토큰이 더 적고 속도가 빠르지만 더 자세한 내용은 더 많은 토큰을 사용하지만 모델에서 더 미세한 기능을 캡처할 수 있습니다.

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

다음 표에서는 각 세부 정보 수준에 대해 설명합니다.

상세 수준 Description
low 모델은 이미지의 해상도가 낮은 버전을 사용합니다. 이 옵션은 가장 적은 토큰을 사용하고 가장 빠른 응답을 생성하지만 모델에 세부 정보가 누락될 수 있습니다.
high 모델은 이미지의 고해상도 버전을 사용합니다. 이 옵션은 세부 정보를 캡처하지만 더 많은 토큰을 사용하고 응답하는 데 더 오래 걸립니다.
auto 기본값입니다. 모델은 이미지 및 프롬프트에 따라 적절한 세부 수준을 선택합니다.

이미지 입력 제한 사항

비전 지원 모델에는 다음과 같은 제한 사항이 있습니다.

  • 의료 이미지: 이 모델은 CT 스캔과 같은 특수 의료 이미지를 해석하는 데 적합하지 않으며 의학적 조언에 사용하면 안 됩니다.
  • 영어가 아닌 텍스트: 일본어 또는 한국어와 같이 라틴 문자가 아닌 알파벳으로 된 텍스트를 포함하는 이미지를 처리할 때 모델이 최적으로 수행되지 않을 수 있습니다.
  • 작은 텍스트: 이미지 내에서 텍스트를 확대하여 가독성을 향상하지만 중요한 세부 정보를 자르지 않도록 합니다.
  • 회전: 모델이 회전하거나 거꾸로 텍스트와 이미지를 잘못 해석할 수 있습니다.
  • 시각적 요소: 단색, 파선 또는 점선과 같은 색이나 스타일이 다른 그래프 또는 텍스트로 모델이 어려움을 겪을 수 있습니다.
  • 공간 추론: 모델은 체스 위치 식별과 같은 정확한 공간 지역화가 필요한 작업에 어려움을 겪습니다.
  • 정확도: 모델은 경우에 따라 잘못된 설명 또는 캡션을 생성할 수 있습니다.
  • 이미지 모양: 모델은 파노라마 및 어안 이미지에 어려움을 겪습니다.
  • 메타데이터 및 크기 조정: 모델은 원래 파일 이름 또는 메타데이터를 처리하지 않으며, 이미지는 분석 전에 크기가 조정되어 원래 차원에 영향을 줍니다.
  • 계산: 모델은 이미지의 개체에 대한 대략적인 개수를 제공할 수 있습니다.
  • CAPTCHA: 안전상의 이유로 CAPTCHA 제출을 차단하는 시스템이 마련되어 있습니다.

파일 입력

비전 기능이 있는 모델은 PDF 입력을 지원합니다. PDF 파일은 Base64로 인코딩된 데이터 또는 파일 ID로 제공할 수 있습니다. 모델이 PDF 콘텐츠를 해석하는 데 도움이 되도록 추출된 텍스트와 각 페이지의 이미지가 모델의 컨텍스트에 포함됩니다. 이는 다이어그램 또는 텍스트가 아닌 콘텐츠를 통해 키 정보를 전달할 때 유용합니다.

참고

  • 추출된 모든 텍스트와 이미지는 모델의 컨텍스트에 배치됩니다. PDF를 입력으로 사용할 때의 가격 책정 및 토큰 사용량에 미치는 영향을 이해해야 합니다.
  • 단일 API 요청에서 둘 이상의 파일을 포함할 수 있지만 각 파일은 50MB 미만이어야 합니다. 요청의 모든 파일에 대한 결합된 제한은 50MB입니다.
  • 텍스트 및 이미지 입력을 모두 지원하는 모델만 PDF 파일을 입력으로 수락할 수 있습니다.
  • 현재 purpose의 user_data는 지원되지 않습니다. 임시 해결 방법으로 용도 assistants를 .로 설정해야 합니다.

PDF를 Base64로 변환 및 분석

바이트를 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)

원격 MCP 서버 사용

모델 기능을 MCP(원격 모델 컨텍스트 프로토콜) 서버에 호스트되는 도구에 연결하여 확장할 수 있습니다. 이러한 서버는 개발자와 조직에서 유지 관리하며 응답 API와 같은 MCP 호환 클라이언트에서 액세스할 수 있는 도구를 노출합니다.

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 이상이 필요합니다.
  • mTLS(상호 TLS)는 현재 지원되지 않습니다.
  • 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)

백그라운드 응답을 스트리밍하려면 background 및 stream를 모두 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"

암호화된 추론 항목

상태 비저장 모드(store=false)에서 응답 API를 사용하는 경우 대화 턴 간에 추론 컨텍스트를 유지해야 합니다. 이렇게 하려면 요청에 암호화된 추론 항목을 포함합니다.

여러 턴에 걸쳐 추론 항목을 유지하려면 reasoning.encrypted_content 매개변수에 include를 추가합니다. 그러면 응답에 향후 요청에 전달할 수 있는 추론 추적의 암호화된 버전이 포함됩니다.

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를 사용하면 대화 및 다단계 워크플로의 일부로 이미지를 생성할 수 있습니다. 컨텍스트 내에서 이미지 입력 및 출력을 지원하며 이미지를 생성하고 편집하기 위한 기본 제공 도구가 포함되어 있습니다.

독립 실행형 이미지 API에 비해 응답 API는 다음 두 가지 이점을 제공합니다.

  • 스트리밍: 생성 중에 부분 이미지 출력을 표시하여 인식된 대기 시간을 개선합니다.
  • 유연한 입력: 이미지 파일 ID를 원시 이미지 바이트 외에 입력으로 허용합니다.

참고

응답 API의 이미지 생성 도구는 -series 모델에서 지원 gpt-image-1되며 호환되는 채팅 및 추론 모델 집합에서 호출할 수 있습니다. 지원되는 오케스트레이션 모델의 현재 목록은 이 문서의 뒷부분에 있는 지원되는 모델 섹션을 참조하세요.

이미지 생성 도구는 현재 스트리밍 모드를 지원하지 않습니다. 부분 이미지를 스트리밍하려면 응답 API 외부에서 직접 이미지 생성 API 를 호출합니다.

응답 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에서 컴퓨터 사용을 전용 컴퓨터 사용 모델 가이드로 이동했습니다.

문제 해결

  • 401/403: Microsoft Entra ID 사용하는 경우 토큰의 범위가 https://ai.azure.com/.default 지정되어 있는지 확인합니다. API 키를 사용하는 경우 리소스에 올바른 키를 사용하고 있는지 확인합니다.
  • 404: model이(가) 배포 이름과 일치하는지 확인하십시오.

관련 콘텐츠

  • Last updated on