---
title: Справочник API
description: Каждая операция шлюза Kumo, сгенерированная из опубликованного описания API: адрес, способ аутентификации, содержимое запроса и то, что приходит в ответ.
keywords: api, справочник, эндпоинты, операции, openapi
group: gateway
generated: from the published API description this build was compiled against
---

Эта страница сгенерирована из описания API, против которого собрана эта сборка, — поэтому она говорит, на что шлюз отвечает, а не на что его когда-то описали отвечающим. Каждый член ниже — член провода. Формулировки самих операций процитированы из описания API и потому остаются английскими: перевод создал бы второе утверждение о проводе, за которым не следит ни одна проверка.

## POST /v1/chat/completions {#chat-completions-create keywords="Create a chat completion."}

:::deflist
| поле | значение |
| --- | --- |
| Метод | **POST** |
| Путь | /v1/chat/completions |
| Аутентификация | Authorization: Bearer <key> |
| Операция | public.chat_completions.create |
:::

OpenAI-совместимый чат: отправляете разговор, получаете одно завершение или поток чанков в ответ.

Create a chat completion.

- **Протокол**: нативный OpenAI Chat Completions, а не перевод другого протокола — члены запроса, форма ответа, словарь `usage` и конверт ошибки принадлежат этому протоколу.
- **Стриминг**: при `stream: true` ответ приходит как `text/event-stream` — события `chat.completion.chunk`, при `stream_options.include_usage` отдельный чанк с `usage`, затем финальный кадр `[DONE]`; отказ до первого события оформляется обычной JSON-ошибкой этого протокола.
- **Аутентификация**: ключ Kumo передаётся заголовком `Authorization: Bearer`.
- **Потолок вывода**: `max_tokens` и `max_completion_tokens` необязательны и взаимозаменяемы — запрос, не назвавший ни одного, отвечается под опубликованным умолчанием в 32768 токенов вывода, против которого и берётся резерв; назвать оба с разными значениями — отказ, а не правило старшинства.

:::code-group
```json title=Запрос
{
  "max_tokens": 128,
  "messages": [
    {
      "role": "user"
    }
  ],
  "model": "<model>"
}
```
```json title=Ответ
{
  "choices": [
    {
      "finish_reason": "stop",
      "index": 1,
      "message": {
        "content": "<content>",
        "role": "assistant"
      }
    }
  ],
  "created": 1,
  "id": "<id>",
  "model": "<model>",
  "object": "chat.completion"
}
```
:::

Запрос несёт:

:::matrix
| член | что это |
| --- | --- |
| `max_completion_tokens` | integer, необязателен — The output ceiling, in the current spelling. |
| `max_tokens` | integer, необязателен — The output ceiling, in the spelling long-established clients send. |
| `messages` | array of [ChatMessage](#schema-chatmessage), обязателен — The conversation, in order. |
| `model` | string, обязателен — The model to answer with: a canonical name or an alias the published catalog carries. |
| `n` | integer, необязателен — How many completions to answer with. |
| `reasoning_effort` | string, необязателен — Accepted and NOT CARRIED: this states how much reasoning to spend on the answer, as OpenAI-compatible clients fill it in for reasoning models, but no supplier request on this platform has a member for a reasoning budget, so the answer comes back at whatever budget the model itself defaults to. |
| `response_format` | [ChatResponseFormat](#schema-chatresponseformat), необязателен — A structured output requirement. |
| `stop` | array of string, необязателен — Sequences whose appearance ends the answer, at most four, as a LIST — the bare-string spelling this protocol also defines is not accepted on this surface and is refused rather than ignored. |
| `stream` | boolean, необязателен — Whether to stream the answer. |
| `stream_options` | [ChatStreamOptions](#schema-chatstreamoptions), необязателен — Options that apply only when stream is true. |
| `temperature` | number, необязателен — How much randomness to use, from 0 to 2 — this protocol's own interval, and not the [0, 1] of the Anthropic Messages surface. |
| `tool_choice` | "auto" or "none" or "required" or object, необязателен — What this request requires of its tool list, in either spelling this protocol defines: the bare mode word "auto", "none" or "required", or an object naming one declared tool. |
| `tools` | array of [ChatTool](#schema-chattool), необязателен — The tools this turn may call. |
| `top_p` | number, необязателен — Nucleus sampling, from 0 to 1. |
| `user` | string, необязателен — An opaque label for the end user this request is made on behalf of, as OpenAI-compatible clients send it. |
:::

### ChatMessage {#schema-chatmessage}

:::matrix
| член | что это |
| --- | --- |
| `cache_control` | ChatCacheControl, необязателен — Accepted and NOT CARRIED: this marks the turn as a prompt-cache anchor, the way OpenAI-compatible clients write it when they address an Anthropic model, but the supplier wire this protocol is served by has no member for an anchor, so the cached-token counts in usage come back as though it had not been sent. |
| `content` | string or array of ChatContentPart, необязателен — The turn's text, in either spelling this protocol defines: a bare string, or a list of typed parts joined in order. |
| `name` | string, необязателен — The tool this result came from, as OpenAI-compatible clients write it on a tool turn. |
| `role` | "system" or "developer" or "user" or "assistant" or "tool", обязателен — Who is speaking. |
| `tool_call_id` | string, необязателен — The call this result answers. |
| `tool_calls` | array of ChatToolCall, необязателен — The calls this assistant turn made, replayed back into the conversation so that a tool result has something in the history to answer. |
:::

### ChatResponseFormat {#schema-chatresponseformat}

:::matrix
| член | что это |
| --- | --- |
| `json_schema` | StructuredSchema, необязателен — The named schema an answer must satisfy. |
| `type` | string, обязателен — The kind of format. |
:::

### ChatStreamOptions {#schema-chatstreamoptions}

:::matrix
| член | что это |
| --- | --- |
| `include_usage` | boolean, необязателен — Whether the stream ends with a usage chunk — an event with an empty choices array carrying only usage — before the terminal [DONE] frame. |
:::

### ChatTool {#schema-chattool}

:::matrix
| член | что это |
| --- | --- |
| `function` | ChatToolFunction, обязателен |
| `type` | "function", обязателен — The kind of tool. |
:::

Ответ:

| что | форма |
| --- | --- |
| `application/json` | ChatCompletionsReply |
| `text/event-stream` | ChatCompletionsChunk |
| `при отказе` | ChatCompletionsError |

### ChatCompletionsReply {#schema-chatcompletionsreply}

:::matrix
| член | что это |
| --- | --- |
| `choices` | array of [ReplyChoice](#schema-replychoice), обязателен — The answer. |
| `created` | integer, обязателен — The instant this completion was answered, as whole seconds since the Unix epoch. |
| `id` | string, обязателен — This request's Kumo identity. |
| `model` | string, обязателен — The model this request named, echoed back exactly as it was sent. |
| `object` | "chat.completion", обязателен — The kind of object this is. |
| `usage` | [ReplyUsage](#schema-replyusage), необязателен — What the supplier reported this request consumed. |
:::

### ReplyChoice {#schema-replychoice}

:::matrix
| член | что это |
| --- | --- |
| `finish_reason` | "stop" or "length" or "tool_calls" or "content_filter", обязателен — Why the model stopped. |
| `index` | integer, обязателен — The position of this choice. |
| `message` | ReplyMessage, обязателен |
:::

### ReplyUsage {#schema-replyusage}

:::matrix
| член | что это |
| --- | --- |
| `completion_tokens` | integer, необязателен — Output tokens the supplier counted. |
| `prompt_tokens` | integer, необязателен — Input tokens the supplier counted, including any it served from its own cache. |
| `prompt_tokens_details` | PromptTokensDetails, необязателен — How the input divides, when the supplier said. |
| `total_tokens` | integer, необязателен — Input and output together. |
:::

### ChatCompletionsChunk {#schema-chatcompletionschunk}

:::matrix
| член | что это |
| --- | --- |
| `choices` | array of [ChunkChoice](#schema-chunkchoice), обязателен — This chunk's delta. |
| `created` | integer, обязателен — The instant this completion was answered, as whole seconds since the Unix epoch. |
| `id` | string, обязателен — This request's Kumo identity, identical on every chunk of one stream. |
| `model` | string, обязателен — The model this request named, echoed back exactly as it was sent, on every chunk. |
| `object` | "chat.completion.chunk", обязателен — The kind of object this is. |
| `usage` | [ReplyUsage](#schema-replyusage), необязателен — Present only on the usage chunk — the last event before [DONE] when stream_options.include_usage asked for one — and absent from every content chunk. |
:::

### ChunkChoice {#schema-chunkchoice}

:::matrix
| член | что это |
| --- | --- |
| `delta` | ChunkDelta, обязателен |
| `finish_reason` | "stop" or "length" or "tool_calls" or "content_filter", обязателен — Why the model stopped, stated once on the chunk that closes the answer and null until then. |
| `index` | integer, обязателен — The position of this choice. |
:::

### ReplyUsage

`ReplyUsage` — см. выше.

### ChatCompletionsError {#schema-chatcompletionserror}

:::matrix
| член | что это |
| --- | --- |
| `error` | [ChatCompletionsErrorBody](#schema-chatcompletionserrorbody), обязателен |
:::

### ChatCompletionsErrorBody {#schema-chatcompletionserrorbody}

:::matrix
| член | что это |
| --- | --- |
| `code` | string, необязателен — The machine-readable reason. |
| `message` | string, обязателен — What went wrong, in a fixed safe sentence. |
| `param` | string, необязателен — The request member at fault, when one member is at fault. |
| `type` | "invalid_request_error" or "not_found_error" or "authentication_error" or "permission_error" or "rate_limit_error" or "api_error", обязателен — The class of failure, in this protocol's own closed vocabulary. |
:::

## POST /v1/embeddings {#embeddings-create keywords="Create embedding vectors for a batch of inputs."}

:::deflist
| поле | значение |
| --- | --- |
| Метод | **POST** |
| Путь | /v1/embeddings |
| Аутентификация | Authorization: Bearer <key> |
| Операция | public.embeddings.create |
:::

Превратить пакет входов в векторы, по одному вектору на вход.

Create embedding vectors for a batch of inputs.

- **Протокол**: возвращает по одному вектору на вход, в том же порядке, что и во входном пакете; тарифицируются только входные токены.
- **Потолок**: у пакета есть предел числа входов и суммарного размера в байтах — запрос за этими пределами отклоняется до обращения к провайдеру.
- **Формат ответа**: `encoding_format` обязателен и должен быть `"base64"` — векторы приходят как base64 от little-endian float32; запрос формата `"float"` или без указания формата отклоняется по имени.
- **Стриминг**: у этой операции его нет.

:::code-group
```json title=Запрос
{
  "encoding_format": "base64",
  "input": [
    "<input>"
  ],
  "model": "<model>"
}
```
```json title=Ответ
{
  "data": [
    {
      "embedding": "<embedding>",
      "index": 1,
      "object": "embedding"
    }
  ],
  "model": "<model>",
  "object": "list",
  "usage": {
    "prompt_tokens": 1,
    "total_tokens": 1
  }
}
```
:::

Запрос несёт:

:::matrix
| член | что это |
| --- | --- |
| `encoding_format` | "base64", обязателен — Must be "base64": this surface does not serve the protocol's "float" default. |
| `input` | array of string, обязателен — The batch of inputs to embed, at most 128 members and 131072 bytes in total. |
| `model` | string, обязателен — The catalog model to embed with, as the customer names it. |
:::

Ответ:

| что | форма |
| --- | --- |
| `application/json` | EmbeddingsResponseBody |
| `при отказе` | EmbeddingsError |

### EmbeddingsResponseBody {#schema-embeddingsresponsebody}

:::matrix
| член | что это |
| --- | --- |
| `data` | array of [EmbeddingsVector](#schema-embeddingsvector), обязателен — One vector per input, in the order the inputs were given. |
| `model` | string, обязателен — The model the vectors were produced with. |
| `object` | "list", обязателен — Always "list". |
| `usage` | [EmbeddingsUsage](#schema-embeddingsusage), обязателен — What the request cost. |
:::

### EmbeddingsVector {#schema-embeddingsvector}

:::matrix
| член | что это |
| --- | --- |
| `embedding` | string, обязателен — The vector components as base64-encoded little-endian float32 values, which is this protocol's own "base64" encoding format. |
| `index` | integer, обязателен — The position of the input this vector is for. |
| `object` | "embedding", обязателен — Always "embedding". |
:::

### EmbeddingsUsage {#schema-embeddingsusage}

:::matrix
| член | что это |
| --- | --- |
| `prompt_tokens` | integer, обязателен — The input tokens charged for this request. |
| `total_tokens` | integer, обязателен — The total tokens charged, which on this surface equals prompt_tokens. |
:::

### EmbeddingsError {#schema-embeddingserror}

:::matrix
| член | что это |
| --- | --- |
| `error` | [EmbeddingsErrorBody](#schema-embeddingserrorbody), обязателен — The failure. |
:::

### EmbeddingsErrorBody {#schema-embeddingserrorbody}

:::matrix
| член | что это |
| --- | --- |
| `code` | string, обязателен — The machine-readable reason, shared with every Kumo surface. |
| `message` | string, обязателен — A safe description of the failure. |
| `request_id` | string, необязателен — The Kumo request identifier, for support. |
| `type` | string, обязателен — The class of failure. |
:::

## POST /v1/images/generations {#images-generate keywords="Generate images from a prompt."}

:::deflist
| поле | значение |
| --- | --- |
| Метод | **POST** |
| Путь | /v1/images/generations |
| Аутентификация | Authorization: Bearer <key> |
| Операция | public.images.generate |
:::

Сгенерировать одно или несколько изображений по текстовому промпту.

Generate images from a prompt.

- **Протокол**: конверты запроса, ответа и ошибки совместимы с OpenAI — отказ несёт `error.message`, `error.type` и `error.code`, а не REST-конверт Kumo.
- **Тарификация**: списывается за единицу изображения через то же ядро допуска, резервирования и расчёта, что и у остальных поверхностей моделей.
- **Не поддерживается**: редактирование и вариации изображений эта операция не обслуживает.

:::code-group
```json title=Запрос
{
  "model": "<model>",
  "prompt": "<prompt>"
}
```
```json title=Ответ
{
  "created": 1,
  "data": [
    {}
  ]
}
```
:::

Запрос несёт:

:::matrix
| член | что это |
| --- | --- |
| `model` | string, обязателен — The public model name to generate with. |
| `n` | integer, необязателен — How many images to generate. |
| `prompt` | string, обязателен — The prompt to generate an image from. |
| `size` | string, необязателен — The image size as WIDTHxHEIGHT, for example 1024x1024. |
:::

Ответ:

| что | форма |
| --- | --- |
| `application/json` | ImagesResponseBody |
| `при отказе` | ImagesErrorBody |

### ImagesResponseBody {#schema-imagesresponsebody}

:::matrix
| член | что это |
| --- | --- |
| `created` | integer, обязателен — When the images were generated, as a Unix timestamp in seconds. |
| `data` | array of [ImagesDataEntry](#schema-imagesdataentry), обязателен — The generated images, in the order the supplier answered them. |
:::

### ImagesDataEntry {#schema-imagesdataentry}

:::matrix
| член | что это |
| --- | --- |
| `b64_json` | string, необязателен — The image bytes, base64-encoded. |
| `url` | string, необязателен — A URL the image can be fetched from. |
:::

### ImagesErrorBody {#schema-imageserrorbody}

:::matrix
| член | что это |
| --- | --- |
| `error` | [ImagesErrorPayload](#schema-imageserrorpayload), обязателен — The refusal, in the OpenAI-compatible error shape. |
:::

### ImagesErrorPayload {#schema-imageserrorpayload}

:::matrix
| член | что это |
| --- | --- |
| `code` | string, обязателен — The machine-readable reason. |
| `message` | string, обязателен — A safe human-readable description of the refusal. |
| `param` | string, обязателен — Always null: this surface never names a field of the request. |
| `type` | string, обязателен — The coarse OpenAI error class. |
:::

## POST /v1/messages {#anthropic-messages-create keywords="Create a message."}

:::deflist
| поле | значение |
| --- | --- |
| Метод | **POST** |
| Путь | /v1/messages |
| Аутентификация | Authorization: Bearer <key> or x-api-key: <key> |
| Операция | public.anthropic_messages.create |
:::

Протокол Anthropic Messages: отправляете разговор в его собственной форме, получаете одно сообщение или поток событий.

Create a message.

- **Протокол**: нативный Anthropic Messages — `max_tokens` обязателен и без значения по умолчанию, системный промпт передаётся отдельным членом запроса, а инструменты несут `input_schema` без обёртки function.
- **Стриминг**: при `stream: true` ответ приходит как `text/event-stream` с именованными событиями протокола — `message_start`, блоки контента, `message_delta`, `message_stop`; отказ после начала потока выражается ошибкой внутри потока, без `message_stop`.
- **Аутентификация**: ключ Kumo передаётся заголовком `Authorization: Bearer` или, как в нативном API, самим значением в заголовке `x-api-key` — любой из них впускает вызывающего, и оба называют один и тот же ключ.
- **Игнорируемые члены**: `metadata`, `thinking`, `output_config` и `context_management` принимаются, но не влияют на ответ — каждый называет это в собственном описании.

:::code-group
```json title=Запрос
{
  "max_tokens": 128,
  "messages": [
    {
      "content": "<content>",
      "role": "user"
    }
  ],
  "model": "<model>"
}
```
```json title=Ответ
{
  "content": [
    {
      "type": "text"
    }
  ],
  "id": "<id>",
  "model": "<model>",
  "role": "<role>",
  "stop_reason": "end_turn",
  "type": "<type>"
}
```
:::

Запрос несёт:

:::matrix
| член | что это |
| --- | --- |
| `context_management` | object, необязателен — This protocol's context-management configuration, as the beta spells it. |
| `max_tokens` | integer, обязателен — The maximum number of tokens to generate. |
| `messages` | array of [MessagesInputMessage](#schema-messagesinputmessage), обязателен — The conversation, oldest turn first. |
| `metadata` | [MessagesMetadata](#schema-messagesmetadata), необязателен — This protocol's request metadata. |
| `model` | string, обязателен — The catalog model to answer with, as the customer names it. |
| `output_config` | object, необязателен — This protocol's output-effort configuration, as the beta spells it. |
| `stop_sequences` | array of string, необязателен — Sequences that end the answer when the model produces one. |
| `stream` | boolean, необязателен — Stream the answer as this protocol's own named events over text/event-stream: message_start, content_block_start, content_block_delta, content_block_stop, message_delta, message_stop. |
| `system` | string or array of [MessagesSystemBlock](#schema-messagessystemblock), необязателен — The system prompt, beside the conversation rather than as a turn of it. |
| `temperature` | number, необязателен — How much randomness to use, from 0 to 1. |
| `thinking` | object, необязателен — This protocol's extended-thinking configuration, as the beta spells it. |
| `tool_choice` | [MessagesToolChoice](#schema-messagestoolchoice), необязателен — Forces one of the declared tools. |
| `tools` | array of [MessagesTool](#schema-messagestool), необязателен — The tools this turn may call. |
| `top_k` | integer, необязателен — Keep only the K most likely tokens when sampling. |
| `top_p` | number, необязателен — Nucleus sampling, from 0 to 1. |
:::

### MessagesInputMessage {#schema-messagesinputmessage}

:::matrix
| член | что это |
| --- | --- |
| `content` | string or array of MessagesContentBlock, обязателен — What the turn says. |
| `role` | "user" or "assistant" or "system", обязателен — Who is speaking. |
:::

### MessagesMetadata {#schema-messagesmetadata}

:::matrix
| член | что это |
| --- | --- |
| `user_id` | string, необязателен — An opaque identifier the caller keeps for its own end user. |
:::

### MessagesSystemBlock {#schema-messagessystemblock}

:::matrix
| член | что это |
| --- | --- |
| `cache_control` | MessagesCacheControl, необязателен — Marks this block as a prompt-cache anchor. |
| `text` | string, обязателен — The block's text. |
| `type` | "text", обязателен — Always "text". |
:::

### MessagesToolChoice {#schema-messagestoolchoice}

:::matrix
| член | что это |
| --- | --- |
| `disable_parallel_tool_use` | boolean, необязателен — Whether at most one tool may be called in one answer; the default is that several may be. |
| `name` | string, необязателен — The tool to force. |
| `type` | "auto" or "any" or "tool" or "none", обязателен — What the request requires: "auto" leaves the choice to the model, "any" requires a call to some declared tool, "tool" requires a call to the one "name" states, and "none" forbids a call while the declarations stay visible. |
:::

### MessagesTool {#schema-messagestool}

:::matrix
| член | что это |
| --- | --- |
| `allowed_callers` | array of string, необязателен — The beta's list of tools permitted to call this one. |
| `cache_control` | MessagesCacheControl, необязателен — Marks this declaration as a prompt-cache anchor; the tool list is part of the cached prefix. |
| `defer_loading` | boolean, необязателен — The beta's request to load this declaration only when it is first needed. |
| `description` | string, необязателен — What the tool does. |
| `eager_input_streaming` | boolean, необязателен — The beta's request to begin streaming this tool's arguments before they are complete. |
| `input_examples` | array of object, необязателен — The beta's example arguments for this tool, each the JSON object input_schema describes. |
| `input_schema` | object, необязателен — The tool's parameters, as the JSON Schema the caller wrote for its own tool. |
| `max_uses` | integer, необязателен — The beta's ceiling on how many times a server-side tool may run. |
| `name` | string, обязателен — The tool's name. |
| `strict` | boolean, необязателен — The beta's request that the arguments conform exactly to input_schema. |
| `type` | string, необязателен — The kind of declaration. |
:::

Ответ:

| что | форма |
| --- | --- |
| `application/json` | MessagesReply |
| `text/event-stream` | MessagesStreamEvent |
| `при отказе` | MessagesError |

### MessagesReply {#schema-messagesreply}

:::matrix
| член | что это |
| --- | --- |
| `content` | array of [MessagesReplyBlock](#schema-messagesreplyblock), обязателен — The answer's blocks, in order. |
| `id` | string, обязателен — The Kumo request identifier for this answer. |
| `model` | string, обязателен — The model the customer named. |
| `role` | string, обязателен — Always "assistant". |
| `stop_reason` | "end_turn" or "max_tokens" or "stop_sequence" or "tool_use", обязателен — Why the answer ended. |
| `type` | string, обязателен — Always "message". |
| `usage` | [MessagesReplyUsage](#schema-messagesreplyusage), необязателен — What the request cost, exactly as this platform settles it. |
:::

### MessagesReplyBlock {#schema-messagesreplyblock}

:::matrix
| член | что это |
| --- | --- |
| `id` | string, необязателен — On a tool use, its identifier. |
| `input` | object, необязателен — On a tool use, the arguments as the JSON object the supplier produced. |
| `name` | string, необязателен — On a tool use, the tool called. |
| `text` | string, необязателен — On a text block, the text. |
| `type` | "text" or "tool_use", обязателен — Which kind of block this is. |
:::

### MessagesReplyUsage {#schema-messagesreplyusage}

:::matrix
| член | что это |
| --- | --- |
| `cache_creation_input_tokens` | integer, обязателен — Input tokens written to the prompt cache. |
| `cache_read_input_tokens` | integer, обязателен — Input tokens served from the prompt cache. |
| `input_tokens` | integer, обязателен — Input tokens charged, excluding cache reads and writes. |
| `output_tokens` | integer, обязателен — Output tokens charged. |
:::

### MessagesStreamEvent {#schema-messagesstreamevent}

:::matrix
| член | что это |
| --- | --- |
| `content_block` | [MessagesStreamBlock](#schema-messagesstreamblock), необязателен — On content_block_start, the opening block. |
| `delta` | [MessagesStreamDelta](#schema-messagesstreamdelta), необязателен — On content_block_delta, the fragment; on message_delta, the closing facts. |
| `error` | [MessagesErrorBody](#schema-messageserrorbody), необязателен — On error, the failure, in this protocol's own envelope. |
| `index` | integer, необязателен — On the block events, which block. |
| `message` | [MessagesStreamMessage](#schema-messagesstreammessage), необязателен — On message_start, the opening envelope: the answer's identity and the account's input half. |
| `type` | "message_start" or "content_block_start" or "content_block_delta" or "content_block_stop" or "message_delta" or "message_stop" or "ping" or "error", обязателен — Which event this is; it is also the SSE frame's event name. |
| `usage` | [MessagesReplyUsage](#schema-messagesreplyusage), необязателен — On message_delta, what the request cost — exactly as this platform settles it, and exactly what the unary reply would state. |
:::

### MessagesStreamBlock {#schema-messagesstreamblock}

:::matrix
| член | что это |
| --- | --- |
| `id` | string, необязателен — On a tool use, its identifier. |
| `input` | object, необязателен — On a tool use, the opening input — the empty object; the arguments arrive as input_json_delta fragments. |
| `name` | string, необязателен — On a tool use, the tool called. |
| `text` | string, необязателен — On a text block, the opening text — empty; the text arrives as deltas. |
| `type` | "text" or "tool_use", обязателен — Which kind of block opened. |
:::

### MessagesStreamDelta {#schema-messagesstreamdelta}

:::matrix
| член | что это |
| --- | --- |
| `partial_json` | string, необязателен — On input_json_delta, the fragment of the call's input object, as partial JSON text. |
| `stop_reason` | "end_turn" or "max_tokens" or "stop_sequence" or "tool_use", необязателен — On message_delta, why the answer ended. |
| `text` | string, необязателен — On text_delta, the fragment of the answer's text. |
| `type` | "text_delta" or "input_json_delta", необязателен — On content_block_delta, which fragment this is; absent on message_delta. |
:::

### MessagesErrorBody {#schema-messageserrorbody}

:::matrix
| член | что это |
| --- | --- |
| `code` | string, необязателен — The machine-readable reason, shared with every Kumo surface. |
| `message` | string, обязателен — A safe description of the failure. |
| `param` | string, необязателен — The member the failure is about, when it is about one. |
| `type` | "invalid_request_error" or "not_found_error" or "authentication_error" or "permission_error" or "rate_limit_error" or "api_error" or "overloaded_error", обязателен — The class of failure. |
:::

### MessagesStreamMessage {#schema-messagesstreammessage}

:::matrix
| член | что это |
| --- | --- |
| `content` | array of [MessagesReplyBlock](#schema-messagesreplyblock), обязателен — Always empty here: the blocks arrive as events. |
| `id` | string, обязателен — The Kumo request identifier for this answer, identical on every event of one stream. |
| `model` | string, обязателен — The model the customer named. |
| `role` | string, обязателен — Always "assistant". |
| `type` | string, обязателен — Always "message". |
| `usage` | [MessagesReplyUsage](#schema-messagesreplyusage), обязателен — The account's input half, as the supplier stated it on opening; the closing message_delta states the settled whole. |
:::

### MessagesReplyUsage

`MessagesReplyUsage` — см. выше.

### MessagesError {#schema-messageserror}

:::matrix
| член | что это |
| --- | --- |
| `error` | [MessagesErrorBody](#schema-messageserrorbody), обязателен — The failure. |
| `type` | "error", обязателен — Always "error". |
:::

### MessagesErrorBody

`MessagesErrorBody` — см. выше.

## POST /v1/messages/count_tokens {#anthropic-messages-count-tokens keywords="Count message input tokens."}

:::deflist
| поле | значение |
| --- | --- |
| Метод | **POST** |
| Путь | /v1/messages/count_tokens |
| Аутентификация | Authorization: Bearer <key> or x-api-key: <key> |
| Операция | public.anthropic_messages.count_tokens |
:::

Посчитать, сколько токенов потратил бы запрос Messages, не тратя их.

Count message input tokens.

- **Протокол**: возвращает детерминированную локальную оценку числа входных токенов для подмножества членов запроса Messages — `model`, `messages`, `system`, `tools`, `tool_choice`, `thinking`, `metadata`, `context_management` — без обращения к провайдеру, без резервирования и без списаний с баланса.
- **Аутентификация**: тот же ключ, что и у `/v1/messages` — заголовком `Authorization: Bearer` или `x-api-key`.
- **Отклоняемые члены**: всё, что относится только к генерации, — `max_tokens`, `stream`, `output_config`, `stop_sequences`, `temperature`, `top_p` — на этой операции отклоняется.

:::code-group
```json title=Запрос
{
  "messages": [
    {
      "content": "<content>",
      "role": "user"
    }
  ],
  "model": "<model>"
}
```
```json title=Ответ
{
  "estimated": true,
  "input_tokens": 1
}
```
:::

Запрос несёт:

:::matrix
| член | что это |
| --- | --- |
| `context_management` | object, необязателен — This protocol's context-management configuration, as the beta spells it. |
| `messages` | array of [MessagesInputMessage](#schema-messagesinputmessage), обязателен — The conversation, oldest turn first. |
| `metadata` | [MessagesMetadata](#schema-messagesmetadata), необязателен — This protocol's request metadata. |
| `model` | string, обязателен — The catalog model to answer with, as the customer names it. |
| `system` | string or array of [MessagesSystemBlock](#schema-messagessystemblock), необязателен — The system prompt, beside the conversation rather than as a turn of it. |
| `thinking` | object, необязателен — This protocol's extended-thinking configuration, as the beta spells it. |
| `tool_choice` | [MessagesToolChoice](#schema-messagestoolchoice), необязателен — Forces one of the declared tools. |
| `tools` | array of [MessagesTool](#schema-messagestool), необязателен — The tools this turn may call. |
:::

### MessagesInputMessage

`MessagesInputMessage` — см. выше.

### MessagesMetadata

`MessagesMetadata` — см. выше.

### MessagesSystemBlock

`MessagesSystemBlock` — см. выше.

### MessagesToolChoice

`MessagesToolChoice` — см. выше.

### MessagesTool

`MessagesTool` — см. выше.

Ответ:

| что | форма |
| --- | --- |
| `application/json` | AnthropicTokenCountReply |
| `при отказе` | MessagesError |

### AnthropicTokenCountReply {#schema-anthropictokencountreply}

:::matrix
| член | что это |
| --- | --- |
| `estimated` | boolean, обязателен — Always true until an exact local tokenizer is available. |
| `input_tokens` | integer, обязателен — The deterministic local estimate of input tokens. |
:::

### MessagesError

`MessagesError` — см. выше.

### MessagesErrorBody

`MessagesErrorBody` — см. выше.

## GET /v1/models {#models-list keywords="List enabled, evidence-backed models."}

:::deflist
| поле | значение |
| --- | --- |
| Метод | **GET** |
| Путь | /v1/models |
| Аутентификация | None — this operation is open. |
| Операция | public.models.list |
:::

Перечислить все модели, на которые шлюз отвечает прямо сейчас.

List enabled, evidence-backed models.

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

```json title=Ответ
{
  "catalog_revision": 1,
  "data": [
    {
      "banner_seed": 1,
      "canonical_name": "<canonical_name>",
      "capabilities": [
        {
          "modality_code": "text_generation",
          "protocol_code": "responses",
          "status": "enabled",
          "streaming_status": "unsupported",
          "strict_semantics_status": "unsupported",
          "structured_output_mode": "none",
          "structured_output_status": "unsupported",
          "structured_output_streaming_status": "unsupported",
          "tools_status": "unsupported"
        }
      ],
      "description_en": "<description_en>",
      "description_ru": "<description_ru>",
      "display_name_en": "<display_name_en>",
      "display_name_ru": "<display_name_ru>",
      "id": "<id>",
      "modality_codes": [
        "text_generation"
      ],
      "model_id": "<model_id>",
      "object": "model",
      "protocol_codes": [
        "responses"
      ],
      "supplier_count": 1,
      "vendor": {
        "code": "<code>",
        "display_name_en": "<display_name_en>",
        "display_name_ru": "<display_name_ru>",
        "id": "<id>"
      }
    }
  ],
  "loaded_at": "<loaded_at>",
  "object": "list",
  "stale": true
}
```

Запрос не несёт тела.

Ответ:

| что | форма |
| --- | --- |
| `application/json` | PublicModelCatalog |
| `при отказе` | ErrorEnvelope |

### PublicModelCatalog {#schema-publicmodelcatalog}

:::matrix
| член | что это |
| --- | --- |
| `catalog_revision` | integer, обязателен — The append-only catalog revision. |
| `data` | array of [PublicCatalogModel](#schema-publiccatalogmodel), обязателен |
| `loaded_at` | string, обязателен |
| `object` | "list", обязателен |
| `stale` | boolean, обязателен — True only when a database refresh failed; the response then retains revision diagnostics but advertises no model capabilities. |
:::

### PublicCatalogModel {#schema-publiccatalogmodel}

:::matrix
| член | что это |
| --- | --- |
| `aliases` | array of string, необязателен |
| `banner_seed` | integer, обязателен — The seed of the model's halftone banner. |
| `canonical_name` | string, обязателен |
| `capabilities` | array of ModelCapability, обязателен |
| `context_window_tokens` | integer, необязателен — How many tokens this model accepts in one request. |
| `description_en` | string, обязателен |
| `description_ru` | string, обязателен |
| `display_name_en` | string, обязателен |
| `display_name_ru` | string, обязателен |
| `header_badge` | "top" or "value" or "fast", необязателен — The card this model fills in the header models panel. |
| `id` | string, обязателен — The name an API request names this model by — the canonical name, so an OpenAI-compatible client that lists models and sends back data[].id as model is answered. |
| `max_output_tokens` | integer, необязателен — How many tokens this model may answer with in one call. |
| `modality_codes` | array of "text_generation" or "embeddings" or "image_generation", обязателен |
| `model_id` | string, обязателен — The catalog's UUID for this model, the key that pricing, key scopes and usage rows join on. |
| `object` | "model", обязателен |
| `protocol_codes` | array of "responses" or "chat_completions" or "anthropic_messages" or "embeddings" or "images", обязателен |
| `released_on` | string, необязателен — The day this model's maker released it, as yyyy-mm-dd. |
| `showcase_position` | integer, необязателен — The model's place on the landing model carousel, ascending. |
| `supplier_count` | integer, обязателен — How many distinct suppliers currently carry this model. |
| `typical_request` | CatalogTypicalRequest, необязателен — What one average request to this model actually spends, measured over the platform's own finished traffic. |
| `vendor` | CatalogVendor, обязателен |
:::

### ErrorEnvelope {#schema-errorenvelope}

:::matrix
| член | что это |
| --- | --- |
| `error` | [ErrorBody](#schema-errorbody), обязателен — The envelope payload. |
:::

### ErrorBody {#schema-errorbody}

:::matrix
| член | что это |
| --- | --- |
| `code` | string, обязателен — Machine-readable error code. |
| `field_details` | array of FieldDetail, необязателен — Per-field rejections, when the error is a validation error. |
| `limit` | LimitDetail, необязателен — Present when the error is a limit or funding-source rejection. |
| `message` | string, обязателен — Safe human-readable fallback. |
| `promotion` | PromotionDetail, необязателен — Present when the error is a named promotion refusal. |
| `request_id` | string, обязателен — Matches the X-Request-Id response header. |
| `version` | string, обязателен — Envelope version. |
:::

## POST /v1/responses {#responses-create keywords="Create a response."}

:::deflist
| поле | значение |
| --- | --- |
| Метод | **POST** |
| Путь | /v1/responses |
| Аутентификация | Authorization: Bearer <key> |
| Операция | public.responses.create |
:::

Более новый протокол OpenAI Responses: отправляете входные элементы, получаете один объект ответа или поток событий.

Create a response.

- **Протокол**: нативный OpenAI Responses — входные и выходные элементы, словарь `usage` и конверт ошибки принадлежат этому протоколу, а не переведены из другого.
- **Стриминг**: при `stream: true` ответ приходит как `text/event-stream` с именованными событиями протокола — `response.created`, элементы вывода и их дельты, затем ровно одно финальное событие: `response.completed` или `response.failed`.
- **Потолок вывода**: `max_output_tokens` необязателен — если он не указан, действует опубликованное по умолчанию конечное значение, а явный ноль отклоняется как запрос нулевого вывода.
- **Игнорируемые члены**: `parallel_tool_calls`, `reasoning`, `include`, `prompt_cache_key`, `client_metadata` и `text.verbosity` принимаются, но не влияют на ответ; `store` допускает только `false`, а `previous_response_id` проверяется лишь на владение и не продолжает контекст на стороне сервера.

:::code-group
```json title=Запрос
{
  "input": "<input>",
  "model": "<model>"
}
```
```json title=Ответ
{
  "created_at": 1,
  "id": "<id>",
  "model": "<model>",
  "object": "response",
  "output": [
    {
      "type": "message"
    }
  ],
  "status": "completed"
}
```
:::

Запрос несёт:

:::matrix
| член | что это |
| --- | --- |
| `client_metadata` | object, необязателен — Metadata the client keeps about its own session. |
| `include` | array of string, необязателен — Extra members the caller asks the answer to carry. |
| `input` | string or array of [ResponsesInputItem](#schema-responsesinputitem), обязателен — The conversation, in either spelling this protocol defines: a bare string, or a list of typed items in order. |
| `instructions` | string, необязателен — The system prompt, as this protocol carries it: a member of the request rather than a turn of the conversation. |
| `max_output_tokens` | integer, необязателен — The output ceiling. |
| `model` | string, обязателен — The model to answer with: a canonical name or an alias the published catalog carries. |
| `parallel_tool_calls` | boolean, необязателен — Whether the model may make several tool calls in one turn. |
| `previous_response_id` | string, необязателен — A response of this organization that this request follows. |
| `prompt_cache_key` | string, необязателен — An opaque key the caller uses to group requests for prompt caching. |
| `reasoning` | object, необязателен — This protocol's reasoning configuration. |
| `store` | boolean, необязателен — Whether the supplier should retain this response for later retrieval. |
| `stream` | boolean, необязателен — Whether to stream the answer. |
| `text` | [ResponsesTextConfig](#schema-responsestextconfig), необязателен — How the answer's text is shaped. |
| `tool_choice` | "auto" or "none" or "required" or object, необязателен — What this request requires of its tool list, as a bare mode word or as an object naming one declared tool. |
| `tools` | array of [ResponsesTool](#schema-responsestool), необязателен — The tools this turn may call. |
:::

### ResponsesInputItem {#schema-responsesinputitem}

:::matrix
| член | что это |
| --- | --- |
| `action` | object, необязателен — What a supplier-side search DID, as the supplier described it and as this surface published it. |
| `arguments` | string, необязателен — The arguments the call was made with, as the JSON text the model produced. |
| `call_id` | string, необязателен — The call this item is or answers. |
| `content` | string or array of ResponsesInputContentPart, необязателен — The text of a message item, and the reasoning prose of a reasoning item, in either spelling this protocol defines: a bare string, or a list of typed parts. |
| `encrypted_content` | string, необязателен — The supplier's own encrypted record of a reasoning item, as it was given to the client. |
| `id` | string, необязателен — The identity this item carried when the caller last saw it. |
| `input` | string, необязателен — The model's FREEFORM answer to a custom tool, as the text it produced: a patch, a query, whatever the tool's own grammar admits. |
| `name` | string, необязателен — The tool that was called. |
| `namespace` | string, необязателен — The group the called tool was declared in, on a function_call or a custom_tool_call, when the request that produced the call declared its tools in namespaces. |
| `output` | string or array of ResponsesInputContentPart, необязателен — The result of running the tool, in either spelling this protocol defines: a bare string, or a list of parts of kind input_text, which is what a tool result's parts are. |
| `role` | "system" or "user" or "developer" or "assistant", необязателен — Who is speaking. |
| `status` | string, необязателен — How far the item got, in this protocol's own vocabulary and carried as the caller stated it. |
| `summary` | array of ResponsesInputContentPart, необязателен — A reasoning item's summary, in parts of kind summary_text. |
| `tools` | array of ResponsesToolNamespace, необязателен — The namespaced tool declarations of an additional_tools item. |
| `type` | "message" or "function_call" or "function_call_output" or "additional_tools" or "custom_tool_call" or "custom_tool_call_output" or "reasoning" or "web_search_call", необязателен — Which kind of item this is. |
:::

### ResponsesTextConfig {#schema-responsestextconfig}

:::matrix
| член | что это |
| --- | --- |
| `format` | ResponsesTextFormat, необязателен — The named schema an answer must satisfy. |
| `verbosity` | "low" or "medium" or "high", необязателен — How much the answer should say. |
:::

### ResponsesTool {#schema-responsestool}

:::matrix
| член | что это |
| --- | --- |
| `description` | string, необязателен — What the tool does. |
| `execution` | string, необязателен — Which side runs a TOOL_SEARCH — the reference spells "client" and "server". |
| `external_web_access` | boolean, необязателен — Whether a WEB_SEARCH may reach the open web. |
| `filters` | ResponsesWebSearchFilters, необязателен — What a WEB_SEARCH is limited to. |
| `format` | ResponsesToolFormat, необязателен — How a CUSTOM tool's freeform answer is shaped. |
| `name` | string, необязателен — The tool's name, as it will come back on the call. |
| `parameters` | object, необязателен — The tool's parameters, as the JSON Schema the caller wrote for its own tool. |
| `search_content_types` | array of string, необязателен — Which kinds of content a WEB_SEARCH may return. |
| `search_context_size` | string, необязателен — How much search context a WEB_SEARCH should gather. |
| `strict` | boolean, необязателен — Whether the supplier must enforce the parameter schema rather than be encouraged toward it. |
| `type` | "function" or "custom" or "tool_search" or "web_search", обязателен — The kind of tool. |
| `user_location` | ResponsesWebSearchLocation, необязателен — Where a WEB_SEARCH should answer as though it were. |
:::

Ответ:

| что | форма |
| --- | --- |
| `application/json` | ResponsesReply |
| `text/event-stream` | ResponsesStreamEvent |
| `при отказе` | ResponsesError |

### ResponsesReply {#schema-responsesreply}

:::matrix
| член | что это |
| --- | --- |
| `created_at` | integer, обязателен — The instant this response was answered, as whole seconds since the Unix epoch. |
| `id` | string, обязателен — This request's Kumo identity. |
| `model` | string, обязателен — The model this request named, echoed back exactly as sent. |
| `object` | "response", обязателен — The kind of object this is. |
| `output` | array of [ResponsesOutputItem](#schema-responsesoutputitem), обязателен — What the model produced, in order, as typed items. |
| `status` | "completed" or "incomplete", обязателен — How the answer ended. |
| `usage` | [ResponsesUsage](#schema-responsesusage), необязателен — What the supplier reported this request consumed. |
:::

### ResponsesOutputItem {#schema-responsesoutputitem}

:::matrix
| член | что это |
| --- | --- |
| `action` | object, необязателен — What a supplier-side search DID, as the supplier described it. |
| `arguments` | string, необязателен — The arguments, as the JSON text the supplier produced. |
| `call_id` | string, необязателен — The call's identity, to quote when answering it on the next turn. |
| `content` | array of [ResponsesOutputContentPart](#schema-responsesoutputcontentpart), необязателен — The message's content, in parts, and a reasoning item's own reasoning text, in parts of kind reasoning_text. |
| `encrypted_content` | string, необязателен — The supplier's own encrypted record of a reasoning item. |
| `id` | string, необязателен — The item's own identity, as the supplier stated it. |
| `input` | string, необязателен — The model's freeform answer to a CUSTOM tool, as the text it produced. |
| `name` | string, необязателен — The tool that was called. |
| `namespace` | string, необязателен — The group the called tool was declared in, on a function_call or a custom_tool_call, when this request declared its tools in namespaces. |
| `role` | "assistant", необязателен — Who is speaking. |
| `status` | string, необязателен — How far a supplier-side search has got, and how far a reasoning item got. |
| `summary` | array of [ResponsesOutputContentPart](#schema-responsesoutputcontentpart), необязателен — A reasoning item's summary, in parts of kind summary_text. |
| `type` | "message" or "function_call" or "custom_tool_call" or "web_search_call" or "reasoning", обязателен — Which kind of item this is. |
:::

### ResponsesUsage {#schema-responsesusage}

:::matrix
| член | что это |
| --- | --- |
| `input_tokens` | integer, необязателен — Input tokens the supplier counted, including any it served from its own cache. |
| `input_tokens_details` | ResponsesInputTokensDetails, необязателен — How the input divides, when the supplier said. |
| `output_tokens` | integer, необязателен — Output tokens the supplier counted. |
| `total_tokens` | integer, необязателен — Input and output together. |
:::

### ResponsesStreamEvent {#schema-responsesstreamevent}

:::matrix
| член | что это |
| --- | --- |
| `content_index` | integer, необязателен — The index of the content part this event is about, within its own output item. |
| `delta` | string, необязателен — The fragment a delta event carries: text on response.output_text.delta, the model's own refusal on response.refusal.delta, argument text on response.function_call_arguments.delta, and a custom tool's freeform input on response.custom_tool_call_input.delta. |
| `item` | [ResponsesOutputItem](#schema-responsesoutputitem), необязателен — The item, on response.output_item.added — opened, so a call carries its identity and no arguments yet — on response.output_item.done, finished, and on the three web_search_call stage events, carrying the status the search has reached. |
| `output_index` | integer, необязателен — The index of the output item this event is about. |
| `part` | [ResponsesOutputContentPart](#schema-responsesoutputcontentpart), необязателен — The content part, on response.content_part.added — opened, so it carries its kind and no text yet — and on response.content_part.done, assembled, carrying exactly the text the fragments between the two events delivered. |
| `response` | [ResponsesStreamSnapshot](#schema-responsesstreamsnapshot), необязателен — The response, on the response-scoped events: opening on response.created, complete with output and usage on response.completed, and carrying this protocol's error envelope on response.failed. |
| `sequence_number` | integer, обязателен — This event's position in the stream that carried it, counting from zero and rising by one on every event the customer is sent. |
| `type` | "response.created" or "response.output_item.added" or "response.content_part.added" or "response.output_text.delta" or "response.refusal.delta" or "response.function_call_arguments.delta" or "response.custom_tool_call_input.delta" or "response.web_search_call.in_progress" or "response.web_search_call.searching" or "response.web_search_call.completed" or "response.content_part.done" or "response.output_item.done" or "response.completed" or "response.failed", обязателен — Which event this is. |
:::

### ResponsesOutputItem

`ResponsesOutputItem` — см. выше.

### ResponsesOutputContentPart {#schema-responsesoutputcontentpart}

:::matrix
| член | что это |
| --- | --- |
| `refusal` | string, необязателен — The model's own refusal, on a refusal part. |
| `text` | string, необязателен — The answer's text, on an output_text part, and the reasoning prose on a summary_text or reasoning_text part. |
| `type` | "output_text" or "refusal" or "summary_text" or "reasoning_text", обязателен — The kind of part. |
:::

### ResponsesStreamSnapshot {#schema-responsesstreamsnapshot}

:::matrix
| член | что это |
| --- | --- |
| `created_at` | integer, обязателен — The instant this response was answered, as whole seconds since the Unix epoch. |
| `error` | [ResponsesErrorBody](#schema-responseserrorbody), необязателен — This protocol's own error envelope, on response.failed. |
| `id` | string, обязателен — This request's Kumo identity, identical on every event of one stream. |
| `model` | string, обязателен — The model this request named, echoed back exactly as sent, on every snapshot. |
| `object` | "response", обязателен — The kind of object this is. |
| `output` | array of [ResponsesOutputItem](#schema-responsesoutputitem), необязателен — What the model produced, in order, on response.completed. |
| `status` | "in_progress" or "completed" or "incomplete" or "failed", обязателен — Where the answer stands. |
| `usage` | [ResponsesUsage](#schema-responsesusage), необязателен — What the supplier reported this request consumed, on response.completed. |
:::

### ResponsesError {#schema-responseserror}

:::matrix
| член | что это |
| --- | --- |
| `error` | [ResponsesErrorBody](#schema-responseserrorbody), обязателен |
:::

### ResponsesErrorBody {#schema-responseserrorbody}

:::matrix
| член | что это |
| --- | --- |
| `code` | string, необязателен — The machine-readable reason. |
| `message` | string, обязателен — What went wrong, in a fixed safe sentence. |
| `param` | string, необязателен — The request member at fault, when one member is at fault. |
| `type` | "invalid_request_error" or "not_found_error" or "authentication_error" or "permission_error" or "rate_limit_error" or "api_error", обязателен — The class of failure, in this protocol's own closed vocabulary. |
:::

> Каждая операция выше выпущена из описания API, против которого собрана эта сборка. О том, как получить всю эту документацию одним Markdown-документом, — на [машиночитаемой странице](/ru/machine-readable).