Использование Chat Completions
Совместимые с OpenAI чат-запросы и потоковые ответы.
Обновлено
Отправьте минимальный рабочий запрос
Выберите доступную чат-модель из GET /v1/models и сначала отправьте обычный, не потоковый запрос:
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" }
]
}'Пример успешного ответа:
{
"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:.
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]:
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 и получение стоимости генерации, не повторную генерацию.