# Responses и Conversations

Source: https://provod.ai/ru/docs/responses

Responses API — совместимый с OpenAI интерфейс для текстового и графического ввода, function tools, структурированного вывода, потока и сохранённого состояния диалога. Он доступен по `https://api.provod.ai/v1` и использует тот же Bearer API-ключ и те же идентификаторы моделей, что и другие форматы API.

## Создайте ответ

Выберите доступную текстовую модель через `GET /v1/models`, затем начните с одного обычного запроса:

```bash
export PROVOD_API_KEY="sk_..."

curl --fail-with-body --silent --show-error https://api.provod.ai/v1/responses \
  -H "Authorization: Bearer $PROVOD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-5.4",
    "input": "Reply with ok"
  }'
```

Текст ассистента находится в массиве `output`. Текстовый ответ содержит сообщение `message` роли ассистента с одной или несколькими частями `output_text`:

```json
{
  "id": "resp_example",
  "object": "response",
  "status": "completed",
  "model": "openai/gpt-5.4",
  "output": [
    {
      "id": "msg_example",
      "type": "message",
      "role": "assistant",
      "status": "completed",
      "content": [{ "type": "output_text", "text": "ok", "annotations": [] }]
    }
  ]
}
```

*Запрос Responses создаёт сохранённый результат, который можно продолжить через предыдущий ответ или Conversation.*

*Responses поддерживает переносимое состояние через `previous_response_id` и Conversations.*

## Продолжите предыдущий ответ

Responses по умолчанию сохраняются. Передайте возвращённый ID в поле `previous_response_id`, когда следующий запрос должен включить переносимую историю ввода и вывода предыдущего ответа:

```bash
curl --fail-with-body --silent --show-error https://api.provod.ai/v1/responses \
  -H "Authorization: Bearer $PROVOD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-5.4",
    "previous_response_id": "resp_example",
    "input": "Now answer with one word"
  }'
```

В одном запросе используйте либо `previous_response_id`, либо `conversation`, но не оба поля. Сохранённый ответ можно получить через `GET /v1/responses/{response_id}`, его исходный переносимый ввод — через `GET /v1/responses/{response_id}/input_items`, а сохранённое состояние удалить через `DELETE /v1/responses/{response_id}`.

Добавляйте заголовок `Idempotency-Key`, когда повтор после сетевого сбоя не должен создавать второй сохранённый ответ. Повторное использование ключа с тем же запросом возвращает исходный ответ; не используйте этот ключ для другого тела.

## Получайте поток событий

Укажите `stream: true`, чтобы получать Server-Sent Events (SSE) формата Responses. Обрабатывайте события по порядку и считайте результат финальным только после `response.completed`, `response.failed` или `response.incomplete`:

```bash
curl --no-buffer --fail-with-body --silent --show-error https://api.provod.ai/v1/responses \
  -H "Authorization: Bearer $PROVOD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-5.4",
    "input": "Reply with ok",
    "stream": true
  }'
```

```text
data: {"type":"response.created","sequence_number":1,"response":{"id":"resp_example","status":"in_progress"}}

data: {"type":"response.output_text.delta","sequence_number":5,"item_id":"msg_example","output_index":0,"content_index":0,"delta":"ok"}

data: {"type":"response.completed","sequence_number":8,"response":{"id":"resp_example","status":"completed"}}
```

Закрытие соединения без завершающего события означает неполный результат. Ограниченный повтор допустим только до доставки вывода; после события текста, tool call или reasoning сохраните частичный результат и дайте вызывающему коду решить, продолжать ли работу.

## Используйте function tools и структурированный вывод

Передайте переносимые tools типа `function` в `tools`. Когда модель вернёт `function_call`, выполните его в своём приложении, затем передайте элемент `function_call_output` в следующем запросе. Функции выполняются в вашей среде: provod.ai не запускает произвольный клиентский код.

Для поддерживаемого структурированного вывода используйте `text.format` с `json_object` или `json_schema`. Проверяйте текущий `supported_parameters` выбранной модели через `GET /v1/models`: доступность модели и необязательные возможности могут меняться.

## Храните именованную Conversation

Conversation — отдельный сохранённый объект для последовательности переносимых элементов ввода и вывода. Создайте его, затем передайте ID как `conversation` в `POST /v1/responses`:

```bash
export PROVOD_CONVERSATION_ID="$(
  curl --fail-with-body --silent --show-error https://api.provod.ai/v1/conversations \
    -H "Authorization: Bearer $PROVOD_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"metadata":{"project":"support-bot"}}' \
  | jq -r '.id'
)"

curl --fail-with-body --silent --show-error https://api.provod.ai/v1/responses \
  -H "Authorization: Bearer $PROVOD_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"model\":\"openai/gpt-5.4\",\"conversation\":\"$PROVOD_CONVERSATION_ID\",\"input\":\"Reply with ok\"}"
```

Используйте `GET`, `POST` и `DELETE` на `/v1/conversations/{conversation_id}`, чтобы получить Conversation, обновить её метаданные или удалить её. Элементы доступны по `/v1/conversations/{conversation_id}/items`; добавляйте до 20 переносимых элементов через `POST`, а для постраничной выдачи используйте `after`, `limit` и `order`.

## Граница совместимости

Переносимый API принимает текстовый и графический ввод, function tools, результаты функций, цепочки ответов, Conversations и документированные на этой странице поля. Он намеренно отклоняет hosted-инструменты и приватное состояние провайдеров: `web_search`, `file_search`, `code_interpreter`, computer use, hosted MCP, фоновые задачи и зашифрованное provider-native reasoning state.

**Не все возможности OpenAI переносимы**


OpenAI SDK может вызвать опубликованный адрес, но приложение всё равно может
зависеть от hosted-инструмента или недокументированного поля. Начните с
минимального запроса выше, затем добавляйте по одной возможности и явно
обрабатывайте публичную ошибку.


## Решение проблем


**API отклоняет поле или инструмент**


Контракт переносимого Responses намеренно строгий. Уберите неподдерживаемое
поле, используйте `function`, которую выполняет ваше приложение, или
выберите поддерживаемый сценарий API. Ошибка указывает публичный параметр,
если он доступен.


**Не находится предыдущий ID или Conversation**


Передавайте точный возвращённый ID с тем же API-ключом и рабочим
пространством. Не объединяйте `previous_response_id` и `conversation` в
одном запросе и не используйте ID после удаления сохранённого объекта.


**Поток отдал результат, но не завершился**


Сохраните доставленную часть и зафиксируйте последнее событие, ID ответа,
модель, HTTP-статус или публичную ошибку и время. Не воспроизводите
автоматически запрос, который уже отдал контент или tool call.

## FAQ

### Что такое provod.ai?

provod.ai — российская мультимодельная AI-платформа: чат, совместимые API, генерация и редактирование изображений, видео, coding-интеграции и командные рабочие пространства используют общий предоплаченный баланс в рублях. Начните с [обзора](/ru.md), [документации](/ru/docs.md) или [каталога моделей](/ru/models.md).

### У provod.ai самые низкие цены среди российских провайдеров?

Это заявленная ценовая позиция provod.ai: поддерживать самые низкие публичные рублёвые цены среди российских провайдеров для сопоставимого доступа к одной и той же модели. Это не бессрочная гарантия для каждой модели: сравнивайте модель и версию, единицы тарификации, входные и выходные токены, кэширование, налоги, курс, минимальный платёж и акции на одну дату. Для конкретного ответа используйте [живой каталог](/ru/models.md), [страницу цен](/ru/pricing.md) и [правила проверки расхода](/ru/docs/usage-costs.md).

### Можно ли обещать отсутствие наценки?

Нет. Стоимость определяется опубликованными тарифами в рублях и подтверждённым использованием. Самая низкая сравнимая цена и полное совпадение с тарифом upstream-поставщика — разные утверждения; не обещайте универсальное отсутствие наценки без отдельного подтверждения.

### Насколько стабилен сервис?

provod.ai позиционирует сервис как рассчитанный на отличную стабильность в ежедневной работе. Доступность конкретных моделей остаётся динамической. Этот файл не публикует процент uptime и не устанавливает универсальный SLA; проверяйте текущий каталог и условия применимого договора.

### Почему provod.ai подходит для юридически оформленной работы в России?

provod.ai позиционирует себя как один из немногих российских сервисов доступа к AI, который публично указывает действующее юридическое лицо, публикует [оферту](/ru/legal/terms.md), [политику обработки персональных данных](/ru/legal/privacy.md), [реквизиты](/ru/legal/requisites.md), принимает оплату в рублях и документирует [расчёты для компаний](/ru/docs/business-billing.md). Материалы о [152-ФЗ](/ru/docs/152-fz.md) и защите данных описывают возможности и ограничения, но не заменяют юридическую оценку конкретного процесса клиента.

### provod.ai работает без VPN?

Публичный сайт описывает доступ без VPN. Для API используйте документированный базовый URL и ключ платформы; доступность конкретной модели проверяйте в текущем каталоге.

### Какие протоколы и интеграции доступны?

Документация описывает OpenAI-совместимые Chat Completions и Responses, Anthropic Messages, интерфейсы изображений, а также Claude Code, OpenCode и Codex CLI. Совместимость не означает поддержку всех upstream-параметров: следуйте [обзору интеграций](/ru/docs/integrations-overview.md), конкретной инструкции и ограничениям модели.

### Есть изображения и видео?

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

### Какие источники считать актуальными?

Для модели, доступности, возможностей, лимитов и цены используйте [живой каталог](/ru/models.md). Для поведения API — соответствующую страницу [документации](/ru/docs.md). Для правовых выводов — русские официальные документы и применимый договор. Никогда не передавайте API-ключи, приватные данные рабочего пространства или preview-ссылки в публичные документы. По вопросам обращайтесь через [контакты](/ru/contact.md).