Chat Completions
Вызов POST /v1/chat/completions — члены запроса, роли в разговоре, форма ответа и указатели на поток, инструменты и структурированный вывод.
Быстро
Направьте OpenAI-совместимый клиент на https://api.kumorouter.com/v1, дайте ему ключ и назовите модель. Потолок вывода обязателен: max_tokens или max_completion_tokens.
curl https://api.kumorouter.com/v1/chat/completions \
-H "Authorization: Bearer $KUMO_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "<model>",
"max_tokens": 128,
"messages": [{ "role": "user", "content": "Объясни токены одной строкой." }]
}'Члены запроса
Тело — один JSON-объект. Члена, которого нет в таблице, эта поверхность не принимает: лишний член отвергается, а не игнорируется.
modelОбязателен. Модель, которой отвечать: каноническое имя или псевдоним, который несёт опубликованный каталог. Ответ возвращает это же имя обратно.messagesОбязателен. Разговор по порядку, от одного до 512 ходов.max_tokensПотолок вывода в том написании, которое шлют давно живущие клиенты.max_completion_tokensТот же потолок в нынешнем написании. Шлите один из двух или оба с одинаковым значением; запрос без обоих отвергается.streamОтвечать ли потоком. `true` даёт `text/event-stream`.stream_optionsТолько вместе со `stream: true`. Единственный член — `include_usage`.toolsИнструменты, которые этот ход может вызвать; до 128 объявлений.tool_choiceТребование вызвать один названный из объявленных инструментов. Без него выбирает модель.response_formatТребование структурированного вывода: именованная JSON-схема.Ходы разговора
У хода есть role и content. Роли четыре: system, user, assistant, tool.
content — это текст хода либо null. null законен на ходе ассистента, весь ответ которого был вызовом инструмента: именно в такой форме OpenAI-совместимый клиент переигрывает свою историю обратно. На ходе tool в content лежит результат работы инструмента.
Эта поверхность несёт текст. Ход не собирается из частей и не принимает картинок: content — строка или null, и другой формы у него нет.
Два члена принадлежат обмену с инструментом.
tool_callsВызовы, которые сделал этот ход ассистента, переигранные обратно в разговор, чтобы результату было на что отвечать. Вызовы делает только ассистент.tool_call_idВызов, на который отвечает этот результат. Обязателен на ходе `tool` и отвергается на всех остальных: поставщик сопоставляет результаты вызовам по нему, а не по позиции.Как выглядит целый круг с инструментом →
Ответ
Массив choices содержит ровно один элемент — попросить больше эта поверхность не даёт, — и index у этого элемента всегда ноль.
idЛичность запроса в Kumo. Её и называйте в обращении в поддержку.objectВсегда `chat.completion`.createdМомент ответа, целыми секундами эпохи Unix.modelИмя, которое назвал запрос, возвращённое ровно тем же: назвавший псевдоним читает обратно псевдоним.choicesОтвет. `message` с ролью `assistant` и `finish_reason`.usageЧто, по сообщению поставщика, потратил запрос. Отсутствует, если поставщик не сообщил расхода вовсе.finish_reason принимает четыре значения: stop, length, tool_calls, content_filter.
В message кроме content может прийти refusal — собственный отказ модели отвечать. Это ответ, а не ошибка: запрос обслужен и оплачен как любой другой.
usage считает prompt_tokens, completion_tokens и total_tokens; prompt_tokens_details.cached_tokens — часть входных токенов, а не добавка к ним.
{
"id": "chatcmpl-8f2b7e10c9",
"object": "chat.completion",
"created": 1756900000,
"model": "<model>",
"choices": [
{
"index": 0,
"message": {
"role": "assistant",
"content": "Токены — это небольшие куски текста, которые модель читает и пишет."
},
"finish_reason": "stop"
}
],
"usage": {
"prompt_tokens": 12,
"completion_tokens": 18,
"total_tokens": 30
}
}