Chat Completions

POST /v1/chat/completions — это OpenAI-совместимый эндпоинт. Он требует API-ключ со скоупом chat:write и лимитируется по каждому ключу.

Beta: mock-провайдер

В beta этот эндпоинт обслуживает mock-провайдер. Он возвращает детерминированный ответ и не вызывает OpenAI, Anthropic, DeepSeek, Zhipu или Kimi. Путь биллинга (резервирование → расчёт) настоящий и выполняется при каждом вызове.

Запрос

# Используйте id модели из GET /v1/models (platform admin должен сначала создать модель и прайс).
curl -X POST https://api.runne.run/v1/chat/completions \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer rn_live_…' \
  -d '{
    "model": "<model-id-from-v1-models>",
    "messages": [{"role": "user", "content": "Hello"}],
    "max_tokens": 1000
  }'

Поле	Тип	Обязательно	Примечания
model	string	да	"provider/model"; должен совпадать с id из GET /v1/models (модели по умолчанию нет)
messages	array	да	мин. 1; role ∈ system | user | assistant
max_tokens	int	нет	положительное, по умолчанию 1000

messages[].content должен быть строкой (в beta мульти-частный контент не поддерживается).

Ответ

{
  "id": "chatcmpl-mock-…",
  "object": "chat.completion",
  "created": 1750000000,
  "model": "mock-model",
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "This is a mock response for demonstration purposes." },
      "finish_reason": "stop"
    }
  ],
  "usage": { "prompt_tokens": 2, "completion_tokens": 50, "total_tokens": 52 }
}

Mock-ответ всегда возвращает completion_tokens: min(max_tokens, 50) и model: "mock-model".

Биллинг в токенах

Каждый запрос проходит полный конвейер биллинга:

1. Оценка — пессимистичная стоимость из длины сообщения (chars/4) плюс max_tokens по выходной ставке модели.
2. Резервирование — атомарно уменьшает баланс (возвращает 402 insufficient_balance, если баланса недостаточно).
3. Вызов провайдера (в beta — mock).
4. Расчёт — вычисляет фактическую стоимость:
   • фактическая ≤ оценочной → возвращается разница;
   • фактическая > оценочной → списывается дефицит (воркспейс приостанавливается, если дефицит покрыть нечем).

Запрос биллится на воркспейс, которому принадлежит API-ключ. Каждый запрос пишет usage_record плюс строки реестра (reservation, settlement/refund/debit).

Ошибки

Статус	Когда
401	ключ отсутствует/невалиден/отозван
403	у ключа нет chat:write, либо воркспейс/клиент приостановлены
404	неизвестная модель или нет прайса для модели
402	недостаточно баланса для резервирования или покрытия дефицита
429	превышен лимит на ключ

Полная таксономия — в разделе Ошибки.

Каталог моделей

GET /v1/models возвращает активные модели с текущим прайсом за 1k токенов:

curl https://api.runne.run/v1/models

Используйте возвращённый id как поле model. В beta каталог изначально пуст — platform admin должен сначала создать модель и её прайс. Модели по умолчанию нет: значение, которого нет в каталоге, возвращает 404 (нет прайса). Формат ответа — в разделе Эндпоинты.

Связанное

• API-ключи — скоуп chat:write.
• Лимиты и квоты — лимиты и квоты.
• Архитектура — реестр и путь дефицита.