Responses

Быстро

Тот же ключ и тот же base URL, что у остальных операций шлюза. Разговор едет в input, а системный промпт — в instructions.

curl https://api.kumorouter.com/v1/responses \
  -H "Authorization: Bearer $KUMO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<model>",
    "instructions": "Отвечай одним предложением.",
    "input": [
      {
        "type": "message",
        "role": "user",
        "content": [{ "type": "input_text", "text": "Объясни токены." }]
      }
    ]
  }'

Чем он отличается

Это отдельный протокол, а не другое написание Chat Completions. Пять различий видны сразу.

• Разговор — это input: один упорядоченный список типизированных элементов. Ход, вызов инструмента и результат вызова — три вида элемента, а не члены одного сообщения.
• Системный промпт — это instructions, член запроса. Он становится ведущим системным ходом разговора, впереди всех элементов input.
• Ответ — это output: список элементов, а не choices.
• Ответ заявляет status — стадию жизненного цикла, completed или incomplete, — а не причину остановки. Два словаря не переводятся друг в друга.
• Потолок вывода необязателен: запрос без max_output_tokens отвечается по опубликованному умолчанию этой поверхности в 32768 токенов. Явный ноль отвергается: это просьба не выводить ничего.

Часть членов протокола эта поверхность принимает и не пересылает, и каждый говорит об этом сам: parallel_tool_calls, reasoning, prompt_cache_key, client_metadata и text.verbosity. Они не отвергаются и не исполняются молча — они не делают ничего. include — наполовину из них: значения, под которые эта поверхность публикует ответ, пересылаются, остальные не делают ничего.

Члены запроса

Виды элементов входа

Второй ход

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

Ответ

Части элемента message бывают двух видов: output_text — текст ответа, refusal — собственный отказ модели отвечать.

Элемент reasoning — собственный отчёт модели о том, как она пришла к ответу; рассуждающая модель ставит его первым, перед сообщением, которое он объясняет. Он несёт id, обязательный summary частями summary_text — присутствующий и пустой, если модель ничего не резюмировала, — необязательный content частями reasoning_text, encrypted_content, если вы попросили его через include, и status. Платформа ничего из этого не читает и ничего не хранит. Отправьте его обратно во `input` на следующем ходу, в тех же членах, в которых он опубликован: именно этого протокол просит от клиента, который несёт свой контекст сам, и именно это позволяет рассуждающей модели продолжить с того места, где она остановилась.

{
  "id": "resp-4d19a0b7c2",
  "object": "response",
  "created_at": 1756900000,
  "model": "<model>",
  "status": "completed",
  "output": [
    {
      "type": "message",
      "role": "assistant",
      "content": [{ "type": "output_text", "text": "Токены — куски текста, которыми модель меряет ввод и вывод." }]
    }
  ],
  "usage": { "input_tokens": 14, "output_tokens": 21, "total_tokens": 35 }
}

Поток

"stream": true даёт text/event-stream в именованных событиях этого протокола: сначала response.created, затем элементы вывода и их дельты, затем ровно одно завершающее событие — response.completed с готовым телом и расходом либо response.failed с конвертом ошибки этого протокола.

Все события и правило завершающего кадра →

Что дальше