provod.ai / docs
API

Использование Chat Completions

Совместимые с OpenAI чат-запросы и потоковые ответы.

Обновлено

Отправьте минимальный рабочий запрос

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

Terminal
export PROVOD_API_KEY="sk_..."

curl --fail-with-body --silent --show-error https://api.provod.ai/v1/chat/completions \
  -H "Authorization: Bearer $PROVOD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-5.4",
    "messages": [
      { "role": "user", "content": "Reply with ok" }
    ]
  }'

Пример успешного ответа:

Response
{
  "id": "chatcmpl_example",
  "object": "chat.completion",
  "created": 1786651200,
  "model": "openai/gpt-5.4",
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "ok" },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 8,
    "completion_tokens": 1,
    "total_tokens": 9
  }
}

Текст ассистента находится в choices[0].message.content. Перед выводом о полноте ответа проверьте finish_reason, а для модели, которая возвращает статистику, используйте объект usage.

Чат-сообщение отправляется и возвращается как последовательность частей ответа.

Совместимый с OpenAI чат по адресу /v1/chat/completions.

Ограничивайте ответ только при необходимости

Текущий контракт запроса принимает либо max_completion_tokens, либо прежнее название max_tokens как положительное целое число. Передавайте только одно поле. Возможность использовать лимит и способ его обработки зависят от выбранной модели, поэтому сверяйтесь с её supported_parameters, а не считайте одно из названий универсальным обходным путём.

Если оба поля отсутствуют, сервис использует текущую настройку по умолчанию при подготовке запроса и резерва. Она не означает максимальную длину ответа для всех моделей. Чтобы задать собственную границу, передайте одно поддерживаемое поле и проверьте finish_reason в ответе.

Добавьте потоковую передачу после проверки

Потоковая передача отдаёт ответ частями, не дожидаясь полного JSON. Chat Completions использует Server-Sent Events (SSE) — текстовый формат, в котором каждое событие передаётся записью data:.

Terminal
export PROVOD_API_KEY="sk_..."

curl --no-buffer --fail-with-body --silent --show-error https://api.provod.ai/v1/chat/completions \
  -H "Authorization: Bearer $PROVOD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-5.4",
    "messages": [
      { "role": "user", "content": "Reply with ok" }
    ],
    "stream": true
  }'

Каждое JSON-событие добавляет данные из choices[0].delta; успешный поток заканчивается буквальным маркером [DONE]:

SSE
data: {"id":"chatcmpl_example","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"role":"assistant"},"finish_reason":null}]}

data: {"id":"chatcmpl_example","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":"ok"},"finish_reason":null}]}

data: {"id":"chatcmpl_example","object":"chat.completion.chunk","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}

data: [DONE]

Обрабатывайте три варианта завершения: JSON-ошибку с HTTP-статусом не из диапазона 2xx до начала SSE, SSE-событие с ошибкой и закрытие соединения до [DONE]. Публичный код ошибки — это предназначенное для клиента значение error.code в ответе; используйте его для диагностики и решения о повторе.

Не повторяйте вслепую уже начавшийся ответ

Повтор с ограниченной экспоненциальной задержкой допустим только до получения результата. Если текст уже пришёл, сохраните частичный ответ и предложите пользователю или приложению решить, нужно ли продолжение: автоматический повтор может продублировать работу и расходы, а подтверждённое использование прерванного потока может быть оплачено.

Получите JSON по схеме

Понадобятся Bash, curl и jq. Задайте AI_API_KEY и MODEL_ID модели, для которой каталог и контракт подтверждают поддержку response_format с JSON Schema и строгого режима. Само наличие модели в каталоге этого не гарантирует. Пример делает один платный запрос; ожидаемый результат — объект с единственным логическим полем ready. Схема не отменяет проверку отказа модели, завершения ответа и полученного JSON в приложении.

set -euo pipefail
: "${AI_API_KEY:?Set the API key for your workspace}"
: "${MODEL_ID:?Choose a model supporting strict JSON Schema}"
API_BASE="${API_BASE:-https://api.provod.ai}"

REQUEST_JSON="$(jq -n --arg model "$MODEL_ID" '{
  model: $model,
  messages: [{role: "user", content: "Return ready as true."}],
  response_format: {
    type: "json_schema",
    json_schema: {
      name: "readiness", strict: true,
      schema: {type: "object", properties: {ready: {type: "boolean"}},
               required: ["ready"], additionalProperties: false}
    }
  }
}')"
RESPONSE_JSON="$(curl --fail-with-body --silent --show-error "$API_BASE/v1/chat/completions" \
  -H "Authorization: Bearer $AI_API_KEY" \
  -H "Content-Type: application/json" --data-binary "$REQUEST_JSON")"

jq -e '
  .choices[0]
  | if .finish_reason == "stop" and (.message.content | type) == "string"
    then .message.content | fromjson
    else error("No completed text response; inspect the response") end
  | if keys == ["ready"] and (.ready | type) == "boolean"
    then . else error("Unexpected response shape") end
' <<<"$RESPONSE_JSON"

Управление ключами и точные расходы

Для запросов к моделям используйте обычный API-ключ. Отдельный управляющий ключ нужен для создания ключей, лимитов и аналитики своего пространства. Chat Completions и Responses возвращают фактическое списание в usage.cost с usage.currency; точная строка — provod.billing.total_charge. После обрыва используйте сохранённый x-generation-id и получение стоимости генерации, не повторную генерацию.

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

На этой странице