Responses и Conversations

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

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

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

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:

{
  "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 поддерживает переносимое состояние через previous_response_id и Conversations.

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

Responses по умолчанию сохраняются. Передайте возвращённый ID в поле previous_response_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",
    "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:

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

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:

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.

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