Использование API ответов OpenAI Azure

Используйте API Azure OpenAI Responses для создания многоэтапных и отслеживающих состояние ответов. Он объединяет возможности завершений чата и 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 ответов. API версии 1 требуется для доступа к последним функциям— дополнительные сведения см. в жизненном цикле версии API. API ответов в настоящее время доступен в следующих регионах:

  • австралия восток
  • бразилияюг
  • canadacentral
  • canadaeast
  • Центральус
  • eastus
  • eastus2
  • francecentral
  • germanywestcentral
  • италия север
  • japaneast
  • koreacentral
  • northcentralus
  • norwayeast
  • Центральная Польша
  • southafricanorth
  • southcentralus
  • Юго-Восточная Азия
  • южная индия
  • spaincentral
  • Швецияцентр
  • свицерланднорт
  • 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 ответов.

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 дней. Удалите сохраненный ответ по идентификатору.

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)

Объединение ответов

Выстраивайте цепочку, передавая идентификатор предыдущего ответа в 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 ответа.

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_managementcompact_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 цепочка: передавайте только новое сообщение пользователя на каждом этапе и переносите последний идентификатор ответа вперед.

Пример

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 ответов может вернуть событие ошибки ( 500, 429 и аналогичные ошибки), если служба сталкивается с ошибкой, например, ограничения маркеров или проблемы синтаксического анализа. Приложения должны обнаруживать это событие и корректно останавливать или перезапускать потоковую передачу. Плата за токены, созданные во время неудачных потоковых ответов, не взимается.

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)

Управление защитными ограничениями и фильтрацией контента

Guardrails (фильтры содержимого) применяются на уровне развертывания и выполняются автоматически при каждом вызове API ответов, поэтому они защищают как входные данные, отправляемые, так и выходные данные, создаваемые моделью. Вы настраиваете защитные ограничения отдельно. Дополнительные сведения см. в разделе Настройка ограничений и контрольных механизмов. В этом разделе показано, как выявлять и обрабатывать результаты проверки защитных ограничений при вызове Responses API.

В Responses API результаты guardrails возвращаются иначе, чем в Chat Completions. Вместо полей prompt_filter_results и content_filter_results, которые возвращает chat completions, объект ответа содержит массив верхнего уровня content_filters. Каждая запись описывает один результат фильтра.

Поле 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 представляет собой расширение Microsoft Foundry, которое не является частью базовой схемы ответа OpenAI, поэтому пакеты SDK не предоставляют для него типизированное свойство. Прочитайте его как необработанное или дополнительное поле, как показано в следующих примерах.

Обнаружение заблокированных входных данных

Если защитные ограничения блокируют ваш ввод, API возвращает ошибку HTTP 400 с кодом content_filter. Перехватите эту ошибку, чтобы корректно обрабатывать заблокированные запросы.

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 код. Контейнеры могут включать отправленные файлы или файлы, созданные во время выполнения.

Чтобы создать контейнер, укажите "container": { "type": "auto", "file_ids": ["file-1", "file-2"] } в конфигурации средства при создании объекта Response. При этом автоматически создается новый контейнер или повторно используется активный объект из предыдущей code_interpreter_call в контексте модели. В выходных данных code_interpreter_call API будут содержаться 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 image/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-адрес файла изображения
  • URI данных, закодированный в Base64
  • Идентификатор файла, созданный с помощью API файлов

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

Отправьте изображение встроенно, закодировав его байты в виде URI данных Base64. Используйте этот шаблон, если изображение недоступно по общедоступному 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)

Идентификатор файла

Отправьте изображение с помощью purpose="vision"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")
)

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 изображений. Каждый отдельный файл изображения должен быть не более 50 МБ, а общий размер всех изображений в запросе должен быть не более 50 МБ.

Изображения должны соответствовать этим дополнительным требованиям:

  • Изображение должно иметь отношение к запросу; Модель не предназначена для не связанного визуального содержимого.
  • Изображения не должны содержать вредное или конфиденциальное содержимое, которое нарушает политики содержимого.
  • Файлы изображений не могут быть повреждены или недоступны для чтения. Если модель не может обработать изображение, запрос завершается сбоем.

Выберите уровень детализации изображения

Используйте свойство detail в части содержимого input_image, чтобы управлять тем, как модель обрабатывает изображение. Более низкий уровень детализации использует меньше токенов и обрабатывается быстрее, тогда как более высокий уровень детализации использует больше токенов, но позволяет модели улавливать более тонкие особенности.

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

В следующей таблице описан каждый уровень детализации.

Уровень детализации Description
low Модель использует версию изображения с более низким разрешением. Этот параметр использует наименьшие маркеры и создает самый быстрый ответ, но модель может пропустить подробные сведения.
high Модель использует версию изображения с более высоким разрешением. Этот параметр захватывает более подробные сведения, но использует больше маркеров и занимает больше времени для реагирования.
auto По умолчанию. Модель выбирает соответствующий уровень детализации на основе изображения и запроса.

Ограничения ввода изображений

Модели с поддержкой визуального зрения имеют следующие ограничения:

  • Медицинские изображения: модель не подходит для интерпретации специализированных медицинских изображений, таких как сканирование СТ и не следует использовать для медицинских консультаций.
  • Текст, отличный от английского языка: модель может не работать оптимально при обработке изображений, содержащих текст в алфавитах, отличных от латиницы, таких как японский или корейский.
  • Маленький текст: увеличьте текст в изображении, чтобы повысить удобочитаемость, но избежать обрезки важных деталей.
  • Поворот: модель может неправильно интерпретировать повёрнутый или перевёрнутый текст и изображения.
  • Визуальные элементы: модель может бороться с графами или текстом, в которых цвета или стили, такие как сплошные, дефисированные или пунктирные линии, различаются.
  • Пространственное обоснование: модель имеет трудности с задачами, которые требуют точной пространственной локализации, например идентификации шахматных позиций.
  • Точность. Модель может создавать неправильные описания или субтитры в некоторых случаях.
  • Форма изображения: модель имеет трудности с панорамными и рыбьими изображениями.
  • Метаданные и изменение размера: модель не обрабатывает исходные имена файлов или метаданные, а изображения изменяются перед анализом, что влияет на их исходные измерения.
  • Подсчет. Модель может дать приблизительное количество объектов в изображениях.
  • CAPTCHAs: По соображениям безопасности система применяется для блокировки отправки CAPTCHAs.

Ввод файла

Модели с возможностями визуального зрения поддерживают входные данные PDF. PDF-файлы можно предоставлять как данные в кодировке Base64, так и в виде идентификаторов файлов. Чтобы помочь моделям интерпретировать содержимое PDF, извлеченный текст и изображение каждой страницы включаются в контекст модели. Это полезно, если ключевые сведения передаются с помощью схем или нетекстового содержимого.

Примечание

  • Все извлеченные текст и изображения помещаются в контекст модели. Убедитесь, что вы понимаете последствия использования PDF в качестве входных данных с точки зрения ценообразования и использования токенов.
  • В одном запросе API можно включить несколько файлов, но каждый файл должен составлять до 50 МБ. Совокупное ограничение для всех файлов в запросе составляет 50 МБ.
  • Только модели, поддерживающие входные данные текста и изображения, могут принимать PDF-файлы в качестве входных данных.
  • В настоящее время purposeuser_data не поддерживается. В качестве временного обходного решения вам потребуется задать назначение assistants.

Преобразование PDF-файла в Base64 и анализ

Отправьте PDF-файл напрямую, закодировав его байты в виде data URI в кодировке base64. Модель получает как извлеченный текст, так и отрисованное изображение каждой страницы.

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-файла и анализ

Загрузите PDF-файл с помощью purpose="assistants". 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). Эти серверы поддерживаются разработчиками и организациями и предоставляют средства, к которым могут обращаться клиенты, совместимые с MCP, такие как API ответов.

Протокол контекста модели (MCP) — это открытый стандарт, определяющий, как приложения предоставляют средства и контекстные данные для больших языковых моделей (LLM). Она обеспечивает согласованную масштабируемую интеграцию внешних инструментов с рабочими процессами модели.

В следующем примере показано, как использовать удаленный сервер MCP для запроса сведений о репозитории REST API Azure. Модель извлекает и анализирует содержимое репозитория в режиме реального времени.

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)

Проверки подлинности

Важно

  • Клиент MCP в API ответов требует TLS 1.2 или более поздней версии.
  • Взаимная аутентификация TLS (mTLS) в настоящее время не поддерживается.
  • теги службы Azure в настоящее время не поддерживаются для трафика клиента MCP.

В отличие от сервера GITHUB MCP, большинство удаленных серверов MCP требуют проверки подлинности. Средство MCP в API ответов поддерживает пользовательские заголовки, что позволяет безопасно подключаться к этим серверам с помощью необходимой схемы проверки подлинности.

Вы можете указать заголовки, такие как ключи 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 в запросе, чтобы поставить задачу в очередь. Служба возвращается немедленно с идентификатором ответа и состоянием queued — используйте этот идентификатор для опроса, потоковой передачи или отмены задачи.

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"

Зашифрованные элементы рассуждений

При использовании Responses API в режиме без сохранения состояния (store=false) необходимо по-прежнему сохранять контекст рассуждений между ходами диалога. Для этого включите в свои запросы зашифрованные элементы рассуждений.

Чтобы сохранять элементы рассуждений между ходами, добавьте 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 ответов предлагает два преимущества:

  • Потоковая передача: отображение частичных выходных данных изображения в процессе генерации для улучшения восприятия задержки.
  • Гибкие входные данные: примите идентификаторы файлов изображений в качестве входных данных в дополнение к необработанным байтам изображений.

Примечание

Инструмент генерации изображений в Responses API поддерживается моделями серии 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