KodikRouter

https://kodikrouter.ru/docs
Admin
KodikRouter is an OpenAI-compatible API gateway that provides access to hundreds of LLMs with...
Tokens:15,191
Snippets:142
Trust Score:4.9
Update:1 month ago
Show doc for...
Tokens:
Raw
### Initialize and use OpenAI SDK

Source: https://kodikrouter.ru/docs/integrations

Basic setup and completion request for Python and Node.js environments.

```python
from openai import OpenAI

client = OpenAI(
    base_url="https://api.kodikrouter.ru/v1",
    api_key="sk-kr_live_xxxxxxxxxx",
)

response = client.chat.completions.create(
    model="anthropic/claude-sonnet-4.6",
    messages=[{"role": "user", "content": "Напиши хайку про Python."}],
)
print(response.choices[0].message.content)
```

```typescript
import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.kodikrouter.ru/v1",
  apiKey: process.env.KODIKROUTER_API_KEY!,
});

const result = await client.chat.completions.create({
  model: "openai/gpt-5.5",
  messages: [{ role: "user", content: "Hello!" }],
});

console.log(result.choices[0].message.content);
```

--------------------------------

### Full API Request Example

Source: https://kodikrouter.ru/docs/gateway

Demonstrates a complete POST request body including standard OpenAI parameters and custom KodikRouter routing extensions.

```json
{
  "model": "anthropic/claude-sonnet-4",
  "messages": [
    {"role": "system", "content": "You are a concise assistant."},
    {"role": "user", "content": "Объясни event loop одним абзацем."}
  ],
  "temperature": 0.3,
  "max_tokens": 512,
  "stream": false,
  "route": "fallback",
  "models": [
    "anthropic/claude-sonnet-4",
    "openai/gpt-4o",
    "meta-llama/llama-3.1-70b-instruct"
  ],
  "provider": {
    "allow_fallbacks": true,
    "ignore": ["azure"]
  },
  "user": "user_123"
}
```

--------------------------------

### Configure Structured Output Request

Source: https://kodikrouter.ru/docs/structured

Example of a request payload using the json_schema response format to extract structured product data.

```json
{
  "model": "openai/gpt-4o",
  "messages": [
    { "role": "user",
      "content": "Extract: MacBook Pro 14\" M3 Pro, $1999, 18GB RAM" }
  ],
  "response_format": {
    "type": "json_schema",
    "json_schema": {
      "name": "product",
      "strict": true,
      "schema": {
        "type": "object",
        "properties": {
          "name":      { "type": "string" },
          "price_usd": { "type": "number" },
          "ram_gb":    { "type": "integer" },
          "category":  { "type": "string", "enum": ["laptop","phone","tablet"] }
        },
        "required": ["name", "price_usd", "ram_gb", "category"],
        "additionalProperties": false
      }
    }
  }
}
```

--------------------------------

### GET /v1/models

Source: https://kodikrouter.ru/docs/auth

Verify your API key by making a request to the models endpoint.

```APIDOC
## GET /v1/models

### Description
Use this endpoint to verify that your API key is valid and authorized to access the system.

### Method
GET

### Endpoint
https://api.kodikrouter.ru/v1/models

### Request Example
curl -s https://api.kodikrouter.ru/v1/models -H "Authorization: Bearer $KODIK_API_KEY"
```

--------------------------------

### Implicit Caching Example

Source: https://kodikrouter.ru/docs/caching

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

```json
{
  "model": "openai/gpt-4.1",
  "messages": [
    { "role": "system",  "content": "<длинный стабильный system prompt>" },
    { "role": "user",    "content": "Что такое TypeScript?" }
  ]
}
```

--------------------------------

### GET /v1/models

Source: https://kodikrouter.ru/docs

Retrieves a list of models available to the authenticated API key.

```APIDOC
## GET /v1/models

### Description
Retrieves a list of models available to the authenticated API key.

### Method
GET

### Endpoint
/v1/models
```

--------------------------------

### Rate Limit Response Headers

Source: https://kodikrouter.ru/docs/ratelimits

Example of HTTP response headers indicating current rate limit status.

```http
HTTP/1.1 200 OK
X-RateLimit-Limit: 500
X-RateLimit-Remaining: 487
X-RateLimit-Reset: 1747832045
X-KodikRouter-Request-Id: sr_req_7k3m9x2p
```

--------------------------------

### Vision: URL-based Images

Source: https://kodikrouter.ru/docs/documents

Example of sending an image URL to a multimodal model.

```APIDOC
## Vision: URL-based Images

### Description
Sends an image URL to a multimodal model for analysis.

### Request Body
- **model** (string) - Required - The model identifier.
- **messages** (array) - Required - List of message objects containing content with type 'image_url'.
```

--------------------------------

### API Response Structure

Source: https://kodikrouter.ru/docs/examples

Example of a successful JSON response from the chat completions endpoint.

```json
{
  "id": "chatcmpl-9xT2pQr1",
  "object": "chat.completion",
  "created": 1747832000,
  "model": "openai/gpt-4o",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Привет! Чем могу помочь?"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 8,
    "completion_tokens": 12,
    "total_tokens": 20
  }
}
```

--------------------------------

### GET /v1/usage/activity

Source: https://kodikrouter.ru/docs/integrations

Retrieves recent usage activity logs for the authenticated account.

```APIDOC
## GET /v1/usage/activity

### Description
Fetches a list of recent API requests including status, latency, cost, and error codes.

### Method
GET

### Endpoint
https://api.kodikrouter.ru/v1/usage/activity

### Parameters
#### Query Parameters
- **limit** (integer) - Optional - The number of records to return (e.g., limit=20).
```

--------------------------------

### GET /v1/catalog/models

Source: https://kodikrouter.ru/docs

Retrieves the public catalog of models with filtering and facets.

```APIDOC
## GET /v1/catalog/models

### Description
Retrieves the public catalog of models with filtering and facets.

### Method
GET

### Endpoint
/v1/catalog/models
```

--------------------------------

### GET /v1/models

Source: https://kodikrouter.ru/docs/base

Retrieves a list of models available to the current API key.

```APIDOC
## GET /v1/models

### Description
Returns a list of models that are accessible with the provided API key.

### Method
GET

### Endpoint
/v1/models
```

--------------------------------

### GET /v1/models/{model_id}

Source: https://kodikrouter.ru/docs/base

Retrieves metadata for a specific model.

```APIDOC
## GET /v1/models/{model_id}

### Description
Fetches metadata for a specific model identified by its ID.

### Method
GET

### Endpoint
/v1/models/{model_id}

### Parameters
#### Path Parameters
- **model_id** (string) - Required - The unique identifier of the model.
```

--------------------------------

### GET /v1/catalog/models

Source: https://kodikrouter.ru/docs/base

Retrieves the public catalog of models with filtering and facets.

```APIDOC
## GET /v1/catalog/models

### Description
Returns the public catalog of available models, supporting filtering and facets.

### Method
GET

### Endpoint
/v1/catalog/models
```

--------------------------------

### GET /v1/models/{model_id}

Source: https://kodikrouter.ru/docs

Retrieves metadata for a specific model.

```APIDOC
## GET /v1/models/{model_id}

### Description
Retrieves metadata for a specific model.

### Method
GET

### Endpoint
/v1/models/{model_id}

### Parameters
#### Path Parameters
- **model_id** (string) - Required - The unique identifier of the model.
```

--------------------------------

### PDF and Document Processing

Source: https://kodikrouter.ru/docs/documents

Example of processing a PDF document by providing a signed URL and enabling the file-parser plugin.

```APIDOC
## PDF and Document Processing

### Description
Processes a PDF document by providing a signed URL from object storage and utilizing the 'file-parser' plugin to extract text.

### Request Body
- **model** (string) - Required - The model identifier.
- **messages** (array) - Required - List of message objects containing content with type 'file'.
- **plugins** (array) - Required - List of plugins, including 'file-parser'.
```

--------------------------------

### Configure Aider via Environment Variables

Source: https://kodikrouter.ru/docs/integrations

Set the API base and key as environment variables to authenticate Aider with KodikRouter.

```bash
export OPENAI_API_BASE="https://api.kodikrouter.ru/v1"
export OPENAI_API_KEY="sk-kr_live_xxxxxxxxxx"

aider --model openai/anthropic/claude-sonnet-4.6
```

--------------------------------

### Настройка Continue.dev через config.yaml

Source: https://kodikrouter.ru/docs/integrations

Определение моделей в конфигурационном файле Continue. Убедитесь, что в интерфейсе выбран Local Config.

```yaml
name: KodikRouter
version: 1.0.0
schema: v1

models:
  - name: Claude Sonnet via KodikRouter
    provider: openai
    model: anthropic/claude-sonnet-4.6
    apiBase: https://api.kodikrouter.ru/v1
    apiKey: sk-kr_live_xxxxxxxxxx
    capabilities:
      - tool_use
      - image_input
    roles:
      - chat
      - edit
      - apply

  - name: GPT-5.5 via KodikRouter
    provider: openai
    model: openai/gpt-5.5
    apiBase: https://api.kodikrouter.ru/v1
    apiKey: sk-kr_live_xxxxxxxxxx
    roles:
      - chat
      - edit

  - name: Qwen Coder Plus
    provider: openai
    model: qwen/qwen3-coder-plus
    apiBase: https://api.kodikrouter.ru/v1
    apiKey: sk-kr_live_xxxxxxxxxx
    roles:
      - autocomplete

  - name: text-embedding-3-small
    provider: openai
    model: openai/text-embedding-3-small
    apiBase: https://api.kodikrouter.ru/v1
    apiKey: sk-kr_live_xxxxxxxxxx
    roles:
      - embed
```

--------------------------------

### Configure tool calling

Source: https://kodikrouter.ru/docs/integrations

Define function schemas and pass them to the completion request to enable tool usage.

```python
tools = [{
    "type": "function",
    "function": {
        "name": "get_weather",
        "parameters": {
            "type": "object",
            "properties": {"city": {"type": "string"}},
            "required": ["city"],
        },
    },
}]

resp = client.chat.completions.create(
    model="anthropic/claude-sonnet-4.6",
    messages=[{"role": "user", "content": "Погода в Москве?"}],
    tools=tools,
)
```

--------------------------------

### Configure OpenAI Codex CLI

Source: https://kodikrouter.ru/docs/integrations

Set up the Codex CLI using environment variables or a TOML configuration file.

```bash
export OPENAI_BASE_URL="https://api.kodikrouter.ru/v1"
export OPENAI_API_KEY="sk-kr_live_xxxxxxxxxx"

codex --model openai/gpt-5.5
```

```toml
[provider]
base_url = "https://api.kodikrouter.ru/v1"
api_key  = "sk-kr_live_xxxxxxxxxx"

[model]
default = "openai/gpt-5.5"
```

--------------------------------

### Run Aider in Architect Mode

Source: https://kodikrouter.ru/docs/integrations

Configure separate models for planning and code generation to optimize for quality and cost.

```bash
aider --architect \
  --model        openai/anthropic/claude-opus-4.6 \
  --editor-model openai/deepseek/deepseek-v3.2 \
  --editor-edit-format editor-diff
```

--------------------------------

### OpenAI-Compatible API Configuration

Source: https://kodikrouter.ru/docs/integrations

Details for configuring standard OpenAI-compatible clients to work with the KodikRouter gateway.

```APIDOC
## OpenAI-Compatible API Integration

### Description
KodikRouter acts as an OpenAI-compatible HTTP API. You can use any AI agent or IDE extension that supports a custom OpenAI Base URL to access 400+ models from providers like OpenAI, Anthropic, Google, DeepSeek, Qwen, and Mistral.

### Base URL
`https://api.kodikrouter.ru/v1`

### Authentication
- **Authorization Header**: `Bearer sk-kr_live_...` (or `sk-kr_test_...` for sandbox)

### Supported Protocols
- OpenAI Chat Completions
- Embeddings
- Models
- SSE (Streaming)
- Tool calls (model dependent)
- Vision (model dependent)

### Usage Example (OpenAI SDK)
```python
from openai import OpenAI

client = OpenAI(
    api_key="sk-kr_live_xxxxxxxxxx",
    base_url="https://api.kodikrouter.ru/v1"
)

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Hello!"}]
)
```
```

--------------------------------

### Implement streaming responses

Source: https://kodikrouter.ru/docs/integrations

Enable streaming by setting the stream parameter to True and iterating over chunks.

```python
stream = client.chat.completions.create(
    model="anthropic/claude-sonnet-4.6",
    messages=[{"role": "user", "content": "Stream a sonnet."}],
    stream=True,
)
for chunk in stream:
    delta = chunk.choices[0].delta.content
    if delta:
        print(delta, end="", flush=True)
```

--------------------------------

### Integrate with LangChain

Source: https://kodikrouter.ru/docs/integrations

Configure the ChatOpenAI class to point to the KodikRouter base URL.

```python
from langchain_openai import ChatOpenAI

llm = ChatOpenAI(
    base_url="https://api.kodikrouter.ru/v1",
    api_key="sk-kr_live_xxxxxxxxxx",
    model="anthropic/claude-sonnet-4.6",
)
```

--------------------------------

### Configure Aider via YAML Configuration

Source: https://kodikrouter.ru/docs/integrations

Use a project-specific .aider.conf.yml file to define API credentials and model mappings.

```yaml
openai-api-base: https://api.kodikrouter.ru/v1
openai-api-key: sk-kr_live_xxxxxxxxxx
model: openai/anthropic/claude-sonnet-4.6
weak-model: openai/openai/gpt-4o-mini
editor-model: openai/anthropic/claude-sonnet-4.6
editor-edit-format: editor-diff
```

--------------------------------

### Enable Streaming

Source: https://kodikrouter.ru/docs/examples

Use the stream parameter to receive responses in chunks via SSE.

```python
stream = client.chat.completions.create(
    model="anthropic/claude-sonnet-4",
    messages=[{"role": "user", "content": "Напиши хайку про код"}],
    stream=True,
)
for chunk in stream:
    delta = chunk.choices[0].delta.content or ""
    print(delta, end="", flush=True)
```

--------------------------------

### List available models via API

Source: https://kodikrouter.ru/docs/integrations

Retrieve a list of supported models using a cURL request with an authorization header.

```bash
curl -s https://api.kodikrouter.ru/v1/models \
  -H "Authorization: Bearer sk-kr_live_xxxxxxxxxx" \
  | jq '.data[] | .id' | head
```

--------------------------------

### Set API Key Environment Variable

Source: https://kodikrouter.ru/docs/examples

Configure the authentication key for the KodikRouter API.

```bash
export KODIK_API_KEY="sk-sr_live_xxxxxxxxxxxxxxxx"
```

--------------------------------

### Configure Claude Code with Proxy

Source: https://kodikrouter.ru/docs/integrations

Deploy a proxy to translate Anthropic Messages API requests to the OpenAI-compatible KodikRouter format.

```bash
# 1. Один раз поднимаем прокси
git clone https://github.com/fuergaosi233/claude-code-proxy
cd claude-code-proxy
echo "OPENAI_API_KEY=sk-kr_live_xxxxxxxxxx"          > .env
echo "OPENAI_BASE_URL=https://api.kodikrouter.ru/v1" >> .env
echo "BIG_MODEL=anthropic/claude-opus-4.6"           >> .env
echo "MIDDLE_MODEL=anthropic/claude-sonnet-4.6"      >> .env
echo "SMALL_MODEL=anthropic/claude-haiku-4.6"        >> .env
python start_proxy.py  # дефолтный порт 8082

# 2. Указываем Claude Code на прокси
export ANTHROPIC_BASE_URL="http://localhost:8082"
export ANTHROPIC_API_KEY="any-value"  # прокси его игнорирует

claude
```

--------------------------------

### Integrate with LlamaIndex

Source: https://kodikrouter.ru/docs/integrations

Configure the LlamaIndex OpenAI wrapper to use the KodikRouter endpoint.

```python
from llama_index.llms.openai import OpenAI

llm = OpenAI(
    api_base="https://api.kodikrouter.ru/v1",
    api_key="sk-kr_live_xxxxxxxxxx",
    model="anthropic/claude-sonnet-4.6",
)
```

--------------------------------

### Enable Streaming

Source: https://kodikrouter.ru/docs/streaming

To enable streaming, set the 'stream' parameter to true in your request. The response will be delivered as a stream of events with 'Content-Type: text/event-stream'.

```APIDOC
## POST /chat/completions

### Description
Enables streaming for chat completions by setting the `stream` parameter to `true`.

### Parameters
#### Request Body
- **stream** (boolean) - Required - Set to `true` to enable Server-Sent Events.
- **stream_options** (object) - Optional - Configuration for the stream. Include `{"include_usage": true}` to receive final token usage statistics in the last chunk.
```

--------------------------------

### Send First API Request

Source: https://kodikrouter.ru/docs/examples

Perform a POST request to the chat completions endpoint using cURL.

```bash
curl -X POST https://api.kodikrouter.ru/v1/chat/completions \
  -H "Authorization: Bearer $KODIK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-4o",
    "messages": [
      {"role": "user", "content": "Привет!"}
    ]
  }'
```

--------------------------------

### POST /v1/chat/completions

Source: https://kodikrouter.ru/docs/gateway

Creates a chat completion request using the KodikRouter gateway, supporting standard OpenAI parameters and custom routing extensions.

```APIDOC
## POST /v1/chat/completions

### Description
Creates a chat completion request. The gateway accepts standard OpenAI parameters and adds custom extensions for routing and security.

### Method
POST

### Endpoint
/v1/chat/completions

### Parameters
#### Request Body
- **model** (string) - Required - ID of the model in provider/model-name format
- **messages** (array) - Required - Array of messages (system, user, assistant, tool)
- **stream** (boolean) - Optional - Enable streaming via Server-Sent Events (default: false)
- **temperature** (number) - Optional - Creativity setting (0 to 2, default: 1.0)
- **top_p** (number) - Optional - Nucleus sampling (default: 1.0)
- **max_tokens** (integer) - Optional - Maximum tokens in the response
- **stop** (string|array) - Optional - Stop sequences (up to 4)
- **response_format** (object) - Optional - JSON / JSON Schema for structured output
- **tools** (array) - Optional - Array of available tools
- **tool_choice** (string|object) - Optional - Tool selection strategy (default: "auto")
- **presence_penalty** (number) - Optional - Penalty for repeating topics (-2 to 2, default: 0)
- **frequency_penalty** (number) - Optional - Penalty for repeating tokens (-2 to 2, default: 0)
- **seed** (integer) - Optional - Determinism setting
- **user** (string) - Optional - End-user identifier for analytics
- **provider** (object) - Optional - Routing settings (allow_fallbacks, only, ignore)
- **route** (string) - Optional - Routing strategy (e.g., "fallback")
- **models** (array) - Optional - List of models for fallback chains
- **plugins** (array) - Optional - Gateway plugins (file-parser, web-search, guardrails)

### Request Example
{
  "model": "anthropic/claude-sonnet-4",
  "messages": [
    {"role": "system", "content": "You are a concise assistant."},
    {"role": "user", "content": "Объясни event loop одним абзацем."}
  ],
  "temperature": 0.3,
  "max_tokens": 512,
  "stream": false,
  "route": "fallback",
  "models": [
    "anthropic/claude-sonnet-4",
    "openai/gpt-4o",
    "meta-llama/llama-3.1-70b-instruct"
  ],
  "provider": {
    "allow_fallbacks": true,
    "ignore": ["azure"]
  },
  "user": "user_123"
}
```

--------------------------------

### Process PDF Documents with file-parser

Source: https://kodikrouter.ru/docs/documents

Provide a signed URL to a document in object storage and enable the file-parser plugin to extract text content.

```json
{
  "model": "openai/gpt-4o",
  "messages": [{
    "role": "user",
    "content": [
      { "type": "text", "text": "Суммируй договор и выдели ключевые пункты." },
      { "type": "file",
        "file": { "url": "https://storage.example.com/contract.pdf", "name": "contract.pdf" } }
    ]
  }],
  "plugins": [{ "id": "file-parser" }]
}
```

--------------------------------

### Tool Calling Workflow

Source: https://kodikrouter.ru/docs/tools

The three-step process for integrating external functions: defining the tool, receiving the model's tool call request, and returning the function output.

```APIDOC
## Tool Calling Workflow

### Description
This workflow allows the model to interact with external functions. It consists of defining the tool, receiving a tool call request from the model, and providing the result back to the model.

### Step 1: Define Tool
Send the `messages`, `tools`, and `tool_choice` parameters to the model.

### Step 2: Receive Tool Call
The model returns the function name and JSON arguments.

### Step 3: Return Result
Append a message with `role: tool` containing the function output and repeat the request.

### Tool Choice Control
- `auto`: Default, model decides whether to call a tool or respond with text.
- `none`: Model must respond with text.
- `required`: Model must call at least one tool.
- `{type:"function", function:{name:"..."}}`: Model must call a specific function.
```

--------------------------------

### Запрос с включенной статистикой использования

Source: https://kodikrouter.ru/docs/streaming

Добавьте stream_options с include_usage: true для получения финальной статистики по токенам.

```json
{
  "model": "openai/gpt-4o",
  "stream": true,
  "stream_options": { "include_usage": true },
  "messages": [{"role":"user","content":"Hi"}]
}
```

--------------------------------

### Формат JSON-ответа при ошибке

Source: https://kodikrouter.ru/docs/errors

Стандартная структура тела ответа при возникновении ошибки, включающая код, сообщение и идентификатор запроса.

```json
{
  "error": {
    "code": "rate_limited",
    "message": "Rate limit exceeded. Please retry after 2 seconds.",
    "type": "rate_limit_error",
    "request_id": "sr_req_7k3m9x2p",
    "param": null,
    "details": []
  }
}
```

--------------------------------

### Handle model tool call response

Source: https://kodikrouter.ru/docs/tools

The model returns a tool_calls array containing the function name and arguments to be executed.

```json
{
  "choices": [{
    "message": {
      "role": "assistant",
      "content": null,
      "tool_calls": [
        {
          "id": "call_abc123",
          "type": "function",
          "function": {
            "name": "get_weather",
            "arguments": "{\"city\":\"Tokyo\",\"units\":\"celsius\"}"
          }
        }
      ]
    },
    "finish_reason": "tool_calls"
  }]
}
```

--------------------------------

### POST /v1/chat/completions

Source: https://kodikrouter.ru/docs/base

Generates text responses or chat completions, supporting streaming via SSE.

```APIDOC
## POST /v1/chat/completions

### Description
Generates text, chat responses, or streaming output using the specified model.

### Method
POST

### Endpoint
/v1/chat/completions

### Request Body
- **model** (string) - Required - The ID of the model to use.
- **messages** (array) - Required - A list of messages comprising the conversation.
```

--------------------------------

### Return tool execution result

Source: https://kodikrouter.ru/docs/tools

Execute the function locally and send the result back to the model using the 'tool' role.

```python
tool_result = get_weather(city="Tokyo", units="celsius")

followup = client.chat.completions.create(
    model="anthropic/claude-sonnet-4",
    messages=[
        {"role": "user", "content": "Какая погода в Токио?"},
        assistant_message,
        {
            "role": "tool",
            "tool_call_id": "call_abc123",
            "content": json.dumps(tool_result),
        },
    ],
    tools=tools,
)
print(followup.choices[0].message.content)
```

--------------------------------

### Отмена стриминга в TypeScript

Source: https://kodikrouter.ru/docs/streaming

Используйте AbortController для прерывания HTTP-соединения и остановки генерации.

```typescript
const controller = new AbortController();
setTimeout(() => controller.abort(), 2000);

const stream = await client.chat.completions.create(
  { model: "openai/gpt-4o", stream: true, messages: [...] },
  { signal: controller.signal },
);
```

--------------------------------

### POST /v1/chat/completions

Source: https://kodikrouter.ru/docs

Generates text responses or handles chat interactions, including support for streaming via SSE.

```APIDOC
## POST /v1/chat/completions

### Description
Generates text responses or handles chat interactions, including support for streaming via SSE.

### Method
POST

### Endpoint
/v1/chat/completions

### Request Body
- **model** (string) - Required - The ID of the model to use (e.g., "openai/gpt-4o").
- **messages** (array) - Required - A list of messages comprising the conversation history.

### Request Example
{
  "model": "openai/gpt-4o",
  "messages": [
    {"role": "user", "content": "Привет!"}
  ]
}
```

--------------------------------

### Включение стриминга в Python

Source: https://kodikrouter.ru/docs/streaming

Используйте параметр stream=True в методе create для активации потоковой передачи.

```python
stream = client.chat.completions.create(
    model="openai/gpt-4o",
    messages=[{"role": "user", "content": "Count from 1 to 5 slowly."}],
    stream=True,
)
for chunk in stream:
    content = chunk.choices[0].delta.content or ""
    print(content, end="", flush=True)
```

--------------------------------

### Configure a Fallback Chain

Source: https://kodikrouter.ru/docs/routing

Defines a sequence of models to attempt sequentially if the primary model fails with retryable errors.

```json
{
  "model": "anthropic/claude-sonnet-4",
  "messages": [{ "role": "user", "content": "Summarize this article." }],
  "route": "fallback",
  "models": [
    "anthropic/claude-sonnet-4",
    "openai/gpt-4o",
    "meta-llama/llama-3.1-70b-instruct"
  ]
}
```

--------------------------------

### Настройка Cline через settings.json

Source: https://kodikrouter.ru/docs/integrations

Конфигурация расширения Cline для VS Code через файл настроек.

```json
{
  "cline.apiProvider": "openai",
  "cline.openAiBaseUrl": "https://api.kodikrouter.ru/v1",
  "cline.openAiApiKey": "sk-kr_live_xxxxxxxxxx",
  "cline.openAiModelId": "anthropic/claude-sonnet-4.6"
}
```

--------------------------------

### Define a tool for the model

Source: https://kodikrouter.ru/docs/tools

Provide the model with a tool definition using JSON Schema within the request body.

```json
{
  "model": "anthropic/claude-sonnet-4",
  "messages": [
    { "role": "user", "content": "Какая погода в Токио прямо сейчас?" }
  ],
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "get_weather",
        "description": "Текущая погода для города",
        "parameters": {
          "type": "object",
          "properties": {
            "city":  { "type": "string", "description": "Город, напр. Tokyo" },
            "units": { "type": "string", "enum": ["celsius","fahrenheit"] }
          },
          "required": ["city"]
        }
      }
    }
  ],
  "tool_choice": "auto"
}
```

--------------------------------

### Parse Structured Output with Pydantic

Source: https://kodikrouter.ru/docs/structured

Using Pydantic models with the OpenAI client to automatically parse structured responses into typed objects.

```python
from pydantic import BaseModel
from openai import OpenAI

class Product(BaseModel):
    name: str
    price_usd: float
    ram_gb: int
    category: str

client = OpenAI(base_url="https://api.kodikrouter.ru/v1", api_key=...)

result = client.chat.completions.parse(
    model="openai/gpt-4o",
    messages=[{"role": "user", "content": "MacBook Pro 14 M3 Pro, $1999, 18GB"}],
    response_format=Product,
)
product: Product = result.choices[0].message.parsed
print(product.name, product.price_usd)
```

--------------------------------

### Setting 1-hour TTL

Source: https://kodikrouter.ru/docs/caching

Пример конфигурации TTL для продления жизни кэша до 1 часа.

```json
{
  "type": "text",
  "text": "<длинная инструкция>",
  "cache_control": { "type": "ephemeral", "ttl": "1h" }
}
```

--------------------------------

### Реализация стратегии повторов (retry) на Python

Source: https://kodikrouter.ru/docs/errors

Пример функции с экспоненциальным backoff и джиттером для обработки ошибок 429, 502, 503 и 504.

```python
import time, random
from openai import OpenAI, APIError, RateLimitError

client = OpenAI(base_url="https://api.kodikrouter.ru/v1", api_key=...)

def chat_with_retry(messages, model, max_attempts=5):
    for attempt in range(max_attempts):
        try:
            return client.chat.completions.create(model=model, messages=messages)
        except RateLimitError as e:
            wait = min(2 ** attempt, 30) + random.random()
            time.sleep(wait)
        except APIError as e:
            if e.status_code in (502, 503, 504) and attempt < max_attempts - 1:
                time.sleep(min(2 ** attempt, 30) + random.random())
                continue
            raise
    raise RuntimeError("exhausted retries")
```

--------------------------------

### Handling 429 Errors with Backoff

Source: https://kodikrouter.ru/docs/ratelimits

Implementation of an exponential backoff strategy with jitter to handle rate limit exhaustion.

```typescript
async function callWithBackoff(fn: () => Promise<Response>) {
  for (let attempt = 0; attempt < 5; attempt++) {
    const res = await fn();
    if (res.status !== 429) return res;
    const retryAfter = Number(res.headers.get("retry-after") ?? 1);
    const jitter = Math.random() * 500;
    await new Promise((r) => setTimeout(r, retryAfter * 1000 + jitter));
  }
  throw new Error("rate limited: exhausted retries");
}
```

--------------------------------

### Idempotency

Source: https://kodikrouter.ru/docs/errors

To ensure single-execution of operations like billing, include an Idempotency-Key header with a UUID. Subsequent requests with the same key will return the original response without additional charges.

```APIDOC
## Idempotency

### Headers
- **Idempotency-Key** (string) - Required for guaranteed single-execution operations. Use a UUID.

### Request Example
POST /v1/chat/completions HTTP/1.1
Authorization: Bearer sk-sr_live_...
Content-Type: application/json
Idempotency-Key: 9a1b2c3d-4e5f-6789-abcd-ef0123456789
```

--------------------------------

### Chat Completions API

Source: https://kodikrouter.ru/docs/integrations

The Chat Completions endpoint allows users to send messages to supported models and receive generated responses. It supports standard OpenAI SDK patterns including streaming and tool calling.

```APIDOC
## POST /v1/chat/completions

### Description
Sends a list of messages to the model to generate a chat completion. This endpoint is compatible with the OpenAI SDK.

### Endpoint
https://api.kodikrouter.ru/v1/chat/completions

### Request Body
- **model** (string) - Required - The ID of the model to use (e.g., "anthropic/claude-sonnet-4.6").
- **messages** (array) - Required - A list of messages comprising the conversation so far.
- **stream** (boolean) - Optional - If set, partial message deltas will be sent.
- **tools** (array) - Optional - A list of tools the model may call.

### Request Example (Python)
```python
from openai import OpenAI

client = OpenAI(
    base_url="https://api.kodikrouter.ru/v1",
    api_key="sk-kr_live_xxxxxxxxxx",
)

response = client.chat.completions.create(
    model="anthropic/claude-sonnet-4.6",
    messages=[{"role": "user", "content": "Напиши хайку про Python."}],
)
```
```

--------------------------------

### Проверка API-ключа через cURL

Source: https://kodikrouter.ru/docs/auth

Пример запроса к эндпоинту /v1/models для проверки работоспособности ключа.

```bash
curl -s https://api.kodikrouter.ru/v1/models \
  -H "Authorization: Bearer $KODIK_API_KEY" | jq '.data | length'
```

--------------------------------

### POST /v1/embeddings

Source: https://kodikrouter.ru/docs

Generates vector representations for input text.

```APIDOC
## POST /v1/embeddings

### Description
Generates vector representations for input text.

### Method
POST

### Endpoint
/v1/embeddings
```

--------------------------------

### POST /v1/embeddings

Source: https://kodikrouter.ru/docs/base

Generates vector representations for input text.

```APIDOC
## POST /v1/embeddings

### Description
Creates vector embeddings for the provided input text.

### Method
POST

### Endpoint
/v1/embeddings
```

--------------------------------

### Automatic Model Selection

Source: https://kodikrouter.ru/docs/routing

Use the auto-routing feature to let the gateway select the optimal model based on cost and quality.

```APIDOC
## Automatic Model Selection

### Description
Set the model parameter to 'kodikrouter/auto' to enable automatic selection of the best model for the request.

### Request Body
- **model** (string) - Set to "kodikrouter/auto".
```

--------------------------------

### Использование заголовка Idempotency-Key

Source: https://kodikrouter.ru/docs/errors

Пример HTTP-запроса с заголовком для обеспечения идемпотентности операций.

```http
POST /v1/chat/completions HTTP/1.1
Authorization: Bearer sk-sr_live_...
Content-Type: application/json
Idempotency-Key: 9a1b2c3d-4e5f-6789-abcd-ef0123456789
```

--------------------------------

### Structured Output Response

Source: https://kodikrouter.ru/docs/structured

The resulting JSON object returned by the model based on the provided schema.

```json
{
  "name": "MacBook Pro 14 M3 Pro",
  "price_usd": 1999,
  "ram_gb": 18,
  "category": "laptop"
}
```

--------------------------------

### Anthropic Auto-cache for Chat

Source: https://kodikrouter.ru/docs/caching

Использование верхнеуровневого cache_control для автоматического продвижения точки кэширования в диалогах.

```json
{
  "model": "anthropic/claude-sonnet-4.6",
  "cache_control": { "type": "ephemeral" },
  "messages": [
    {
      "role": "system",
      "content": [
        { "type": "text", "text": "<очень длинный стабильный system prompt>" }
      ]
    },
    {
      "role": "user",
      "content": [
        { "type": "text", "text": "Опиши изменения в проекте за неделю." }
      ]
    }
  ]
}
```

--------------------------------

### Служебные HTTP-заголовки маскирования

Source: https://kodikrouter.ru/docs/masking

Пример ответа шлюза, содержащего метаданные о количестве замаскированных сущностей и задержке обработки.

```http
HTTP/1.1 200 OK
X-KodikRouter-Masked-Entity-Count: 4
X-KodikRouter-Latency-Mask-Ms: 14
X-KodikRouter-Provider: openai
```

--------------------------------

### Настройка Roo Code через settings.json

Source: https://kodikrouter.ru/docs/integrations

Конфигурация расширения Roo Code для VS Code через файл настроек.

```json
{
  "roo-cline.apiProvider": "openai-compatible",
  "roo-cline.openAiBaseUrl": "https://api.kodikrouter.ru/v1",
  "roo-cline.openAiApiKey": "sk-kr_live_xxxxxxxxxx",
  "roo-cline.openAiModelId": "anthropic/claude-sonnet-4.6"
}
```

--------------------------------

### Send Image URL to Vision Model

Source: https://kodikrouter.ru/docs/documents

Use the image_url type within the content array to provide an image via a public URL.

```json
{
  "model": "openai/gpt-4o",
  "messages": [{
    "role": "user",
    "content": [
      { "type": "text", "text": "Что изображено?" },
      { "type": "image_url",
        "image_url": { "url": "https://example.com/photo.jpg", "detail": "high" } }
    ]
  }]
}
```

--------------------------------

### Send Base64 Encoded Image

Source: https://kodikrouter.ru/docs/documents

Convert a local image file to a base64 string and include it in the request using the data URI scheme.

```python
import base64
img_b64 = base64.b64encode(open("photo.jpg", "rb").read()).decode()

response = client.chat.completions.create(
    model="openai/gpt-4o",
    messages=[{
        "role": "user",
        "content": [
            {"type": "text", "text": "Что изображено?"},
            {"type": "image_url",
             "image_url": {"url": f"data:image/jpeg;base64,{img_b64}"}},
        ],
    }],
)
```

--------------------------------

### Anthropic Breakpoint Caching

Source: https://kodikrouter.ru/docs/caching

Ручная установка контрольных точек кэширования на конкретных блоках контента.

```json
{
  "model": "anthropic/claude-sonnet-4.6",
  "messages": [
    {
      "role": "system",
      "content": [
        {
          "type": "text",
          "text": "<длинная стабильная инструкция, ≥1024 токенов>",
          "cache_control": { "type": "ephemeral" }
        }
      ]
    },
    {
      "role": "user",
      "content": [
        { "type": "text", "text": "Краткий вопрос к этому контексту." }
      ]
    }
  ]
}
```

--------------------------------

### Authentication Header

Source: https://kodikrouter.ru/docs/auth

All requests to the API must include the secret key in the Authorization header using the Bearer scheme.

```APIDOC
## Authentication

### Description
All requests to the API must contain your secret key in the `Authorization` header. Keys are personal and tied to an organization.

### Header
- **Authorization** (string) - Required - Bearer <your_secret_key>

### Example
Authorization: Bearer sk-sr_live_xxxxxxxxxxxxxxxx
```

--------------------------------

### Заголовок авторизации HTTP

Source: https://kodikrouter.ru/docs/auth

Формат заголовка, который должен присутствовать во всех запросах к API.

```http
Authorization: Bearer sk-sr_live_xxxxxxxxxxxxxxxx
```

--------------------------------

### Provider Filtering

Source: https://kodikrouter.ru/docs/routing

Control which providers are eligible for a request using allow-lists and block-lists.

```APIDOC
## Provider Filtering

### Description
Filters the available providers for a specific request to ensure compliance or cost management.

### Request Body
- **provider.only** (string[]) - Optional - A white-list of allowed providers.
- **provider.ignore** (string[]) - Optional - A list of providers to exclude.
- **provider.allow_fallbacks** (boolean) - Optional - Whether to allow fallback models in the chain (default: true).
```

--------------------------------

### Error Response Format

Source: https://kodikrouter.ru/docs/errors

All errors are returned with an HTTP status code and a consistent JSON body. The 'request_id' field is provided to assist in debugging and log tracking.

```APIDOC
## Error Response Format

### Response
- **error** (object) - The error details object
  - **code** (string) - Machine-readable error code
  - **message** (string) - Human-readable error description
  - **type** (string) - Error category
  - **request_id** (string) - Unique identifier for the request
  - **param** (string|null) - Parameter associated with the error
  - **details** (array) - Additional error details

### Response Example
{
  "error": {
    "code": "rate_limited",
    "message": "Rate limit exceeded. Please retry after 2 seconds.",
    "type": "rate_limit_error",
    "request_id": "sr_req_7k3m9x2p",
    "param": null,
    "details": []
  }
}
```

--------------------------------

### Filter Providers

Source: https://kodikrouter.ru/docs/routing

Restricts request routing to specific providers or excludes them using allowlists and blocklists.

```json
{
  "model": "openai/gpt-4o",
  "messages": [{ "role": "user", "content": "Hi" }],
  "provider": {
    "only":   ["openai", "anthropic"],
    "ignore": ["azure"],
    "allow_fallbacks": true
  }
}
```

--------------------------------

### Формат чанка SSE

Source: https://kodikrouter.ru/docs/streaming

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

```json
data: {"id":"chatcmpl-9xT","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"role":"assistant"},"finish_reason":null}]}

data: {"id":"chatcmpl-9xT","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":"1"},"finish_reason":null}]}

data: {"id":"chatcmpl-9xT","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":", 2"},"finish_reason":null}]}

data: {"id":"chatcmpl-9xT","object":"chat.completion.chunk","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}

data: [DONE]
```
Tokens:
Raw