Документация API

Быстрый старт

Первый запрос

curl https://api.clavis.to/v1/chat/completions \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

Python (OpenAI SDK)

from openai import OpenAI

client = OpenAI(
    api_key="sk-your-api-key",
    base_url="https://api.clavis.to/v1"
)

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

JavaScript / TypeScript (OpenAI SDK)

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: "sk-your-api-key",
  baseURL: "https://api.clavis.to/v1",
});

const response = await client.chat.completions.create({
  model: "gpt-4o",
  messages: [{ role: "user", content: "Hello!" }],
});
console.log(response.choices[0].message.content);

Аутентификация

Base URL

Замените base_url в любом OpenAI SDK, никаких других изменений не нужно.

Claude Code

1. Установите Node.js

# Через winget (встроен в Windows 10/11)
winget install OpenJS.NodeJS.LTS

# Проверка установки
node --version
npm --version

2. Установите Claude Code CLI

npm install -g @anthropic-ai/claude-code

# Проверка
claude --version

3. Создайте API-ключ

Перейдите в Dashboard → API-ключи, нажмите «Создать», скопируйте ключ (показывается один раз).

4. Настройте конфигурацию

Файл конфигурации: %USERPROFILE%\.claude\settings.json

# Создайте папку и файл
mkdir %USERPROFILE%\.claude
notepad %USERPROFILE%\.claude\settings.json

{
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "${KEY}",
    "ANTHROPIC_BASE_URL": "https://api.clavis.to",
    "API_TIMEOUT_MS": "600000"
  }
}

5. Запустите Claude Code

cd ваш-проект
claude

OpenAI CodeX

1. Установите CodeX CLI

npm install -g @openai/codex@latest
codex --version

2. Создайте файлы конфигурации

Создайте папку %USERPROFILE%\.codex\

config.toml

model_provider = "clavis"
model = "gpt-5.6-luna"
model_reasoning_effort = "high"
network_access = "enabled"
disable_response_storage = true

[model_providers.clavis]
name = "clavis"
base_url = "https://api.clavis.to/v1"
wire_api = "responses"
requires_openai_auth = true

auth.json

{
  "OPENAI_API_KEY": "${KEY}"
}

3. Запустите CodeX

cd ваш-проект
codex

Gemini CLI

1. Установите Gemini CLI

npm install -g @google/gemini-cli
gemini --version

2. Создайте конфигурацию

Создайте папку %USERPROFILE%\.gemini\

.env

GOOGLE_GEMINI_BASE_URL=https://api.clavis.to
GEMINI_API_KEY=${KEY}
GEMINI_MODEL=gemini-2.5-pro

settings.json

{
  "security": {
    "auth": { "selectedType": "gemini-api-key" }
  }
}

3. Запустите

gemini

SillyTavern

1. Установите SillyTavern

Скачайте и установите с GitHub. Запустите start.bat (Windows) или start.sh (macOS/Linux).

2. Настройте API

Откройте браузер http://localhost:8000 → кнопка «API» → выберите «Claude» (Anthropic Native):

JanitorAI

1. Откройте настройки API

Зайдите в чат с любым персонажем → три полоски (☰) в правом верхнем углу → пункт «Настройки» (API Settings) в открывшемся меню.

2. Провайдер → «Прокси»

Смените провайдера с Janitor на «Прокси» (Proxy), затем нажмите «+ Новая» (+ New), откроется форма новой конфигурации.

3. Заполните поля

API-ключ берётся в кабинете → «API-ключи». Нажмите «Добавить», затем перезагрузите страницу (F5), после этого можно общаться.

4. Какую модель вписать

На странице Модели выберите модель и пул, и вставьте идентификатор в поле «Модель» целиком, вместе с @пулом.

gemini-3.6-flash@gemini          // быстро и дёшево, длинный контекст
claude-sonnet-4-6@claudecodecheap // лучший слог, держит характер
deepseek-v4-flash@alibabacloud   // самый бюджетный вариант
aion-rp-llama-3.1-8b             // модель специально под ролеплей

Если чат не отвечает

• Сетевая ошибка / «Failed to fetch», сперва перезагрузите страницу: JanitorAI кеширует настройки прокси до перезагрузки. Затем проверьте, что URL заканчивается на /chat/completions.
• Отключите на janitorai.com блокировщики рекламы и «антитрекинг»-расширения, они режут запросы к сторонним доменам, и до нас запрос просто не доходит.
• 401, ключ скопирован не полностью или удалён в кабинете. 402, закончился баланс.
• 404, модель написана неточно: идентификатор нужен ровно такой, как на странице модели (регистр и @пул важны).
• Ответ обрывается на середине, увеличьте лимит токенов в настройках генерации JanitorAI.

Cline · Roo Code · Kilo Code

1. Установите расширение

Поставьте Cline, Roo Code или Kilo Code из маркетплейса VS Code (Extensions → поиск по названию).

2. Провайдер «OpenAI Compatible»

Откройте настройки расширения → API Provider → «OpenAI Compatible» и заполните:

Рекомендуемые модели для кодинга

claude-sonnet-4-6     // баланс цена / качество
claude-opus-4-8       // топ-качество для сложных задач
gpt-5.4               // сильный агентный кодинг
glm-4.7               // очень дёшево

Сравнить все модели по коду и цене на странице «Рейтинг». У одной модели бывает несколько пулов (дешевле/дороже) открой её страницу и выбери поставщика.

Пулы с id вида @gate-…, это сторонние поставщики нашего маркетплейса на их собственной инфраструктуре. Мы не можем утверждать, что запросы и ответы не логируются на их стороне, поэтому такие пулы помечены на сайте как сторонние. Запрос без явного указания пула к ним никогда не уходит.

Cherry Studio

Настройка API

Откройте Cherry Studio → Настройки → Провайдеры моделей → Добавить → OpenAI:

Рекомендуемые модели

claude-sonnet-4-6
gpt-4o
gemini-2.5-pro

🦞 OpenClaw

1. Установка

На macOS / Linux / WSL2 запустите официальный скрипт. Флаг --no-onboard пропускает мастер настройки после установки.

curl -fsSL https://openclaw.ai/install.sh | bash -s -- --no-onboard

openclaw --help

2. Запуск мастера

Запустите мастер и идите по шагам до настройки модели и аутентификации.

openclaw onboard

3. Кастомный провайдер

На шаге модели и аутентификации выберите Custom provider. Совместимость Anthropic или OpenAI. Provider ID clavis, API Key, ваш sk- токен Clavis.

Примеры моделей: gpt-5.5, claude-opus-4-7, gemini-2.5-pro. Актуальный список и цены, на странице «Рейтинг» / «Модели».

4. Завершение и проверка

Для первой настройки оставьте порт шлюза, режим привязки и фоновый сервис по умолчанию.

openclaw doctor
openclaw status
openclaw dashboard

Если дашборд отправляет сообщение и получает ответ модели, Clavis подключён успешно.

5. Установка скриптом (non-interactive)

Для деплой-скриптов и серверов, неинтерактивный режим. Здесь OpenAI-совместимый режим, поэтому Base URL содержит /v1.

export CUSTOM_API_KEY="${KEY}"

openclaw onboard --non-interactive \
  --mode local \
  --auth-choice custom-api-key \
  --custom-base-url "https://api.clavis.to/v1" \
  --custom-model-id "gpt-5.5" \
  --custom-provider-id "clavis" \
  --custom-compatibility openai \
  --secret-input-mode ref \
  --gateway-port 18789 \
  --gateway-bind loopback

6. Проверка конфига вручную

Можно отредактировать ~/.openclaw/openclaw.json. Модель по умолчанию указывается в формате provider/model, например clavis/gpt-5.5.

{
  "agents": {
    "defaults": {
      "model": { "primary": "clavis/gpt-5.5" }
    }
  },
  "models": {
    "providers": {
      "clavis": {
        "baseUrl": "https://api.clavis.to/v1",
        "apiKey": "${CUSTOM_API_KEY}",
        "api": "openai-completions",
        "models": [
          { "id": "gpt-5.5", "name": "gpt-5.5" }
        ]
      }
    }
  }
}

🪽 Hermes

Кастомный провайдер

Добавьте Clavis в настройках моделей/провайдеров Hermes:

📱 Мобильные и десктоп-клиенты

RikkaHUB, Android

Настройки → API Connections → добавьте «Custom OpenAI Compatible Provider»:

Модели: claude-opus-4-7, gpt-5.5, gemini-3.5-flash.

Tavo, Android / iOS

В настройках подключения укажите:

OMate, Android / iOS

Настройки → «API Configuration» / «Custom API»:

Chatbox, Windows / macOS / Linux / iOS / Android

Настройки → AI Model Settings → провайдер «OpenAI API». Внимание: здесь нужен API Host (без /v1), Chatbox добавит /v1 сам:

Chat Completions

Параметры запроса

Пример

curl https://api.clavis.to/v1/chat/completions \
  -H "Authorization: Bearer sk-..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4-6",
    "stream": true,
    "messages": [
      {"role": "system", "content": "You are a helpful assistant."},
      {"role": "user", "content": "Explain async/await in Python"}
    ]
  }'

Models

Пример ответа

{
  "object": "list",
  "data": [
    {
      "id": "gpt-4o",
      "owned_by": "OpenAI",
      "billing_type": "per_token",
      "pricing": {
        "input_per_1m_rub": 43.75,
        "output_per_1m_rub": 131.25
      },
      "context_window": 128000,
      "endpoints": ["openai"],
      "is_active": true
    }
  ]
}

Anthropic Messages API

Пример

import anthropic

client = anthropic.Anthropic(
    api_key="${KEY}",
    base_url="https://api.clavis.to",
)

message = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello!"}]
)
print(message.content[0].text)

Embeddings

Пример

curl https://api.clavis.to/v1/embeddings \
  -H "Authorization: Bearer sk-..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "text-embedding-3-small",
    "input": "The quick brown fox"
  }'

Code Edit, правка кода

Обязательные теги в content

• <|current_file_content|>, содержимое файла целиком
• <|code_to_edit|>, фрагмент, который надо переписать
• <|cursor|>, позиция курсора внутри этого фрагмента
• <|recently_viewed_code_snippets|>, <|edit_diff_history|>, необязательный контекст: что пользователь недавно смотрел и правил

Пример

curl https://api.clavis.to/v1/edit/completions \
  -H "Authorization: Bearer sk-..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "mercury-edit-2@inceptionlabs",
    "max_tokens": 256,
    "messages": [{
      "role": "user",
      "content": "<|current_file_content|>\ndef greet(name):\n    print(\"hi\")\n<|/current_file_content|>\n<|code_to_edit|>\ndef greet(name):\n    print(\"hi\")<|cursor|>\n<|/code_to_edit|>"
    }]
  }'

Ответ

{
  "id": "chatcmpl-...",
  "object": "edit.completion",
  "model": "mercury-edit-2@inceptionlabs",
  "choices": [{
    "index": 0,
    "finish_reason": "stop",
    "message": { "role": "assistant", "content": "def greet(name):\n    print(f\"hi {name}\")" }
  }],
  "usage": { "prompt_tokens": 208, "completion_tokens": 26, "total_tokens": 234 }
}

Fill-in-the-Middle, автодополнение

Параметры

• prompt, обязательный, текст до курсора
• suffix, текст после курсора
• max_tokens, по умолчанию 512, максимум 8192
• stop, top_p, top_k, frequency_penalty, presence_penalty, repetition_penalty, stream

Пример

curl https://api.clavis.to/v1/fim/completions \
  -H "Authorization: Bearer sk-..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "mercury-edit-2@inceptionlabs",
    "prompt": "def fibonacci(n: int) -> int:\n    if n <= 1:\n        return n\n    return ",
    "suffix": "\n\nprint(fibonacci(10))\n",
    "max_tokens": 256
  }'

Ответ

{
  "id": "cmpl-...",
  "object": "text_completion",
  "model": "mercury-edit-2@inceptionlabs",
  "choices": [{
    "index": 0,
    "finish_reason": "stop",
    "text": "fibonacci(n - 1) + fibonacci(n - 2)"
  }],
  "usage": { "prompt_tokens": 34, "completion_tokens": 14, "total_tokens": 48 }
}

Image Generation

Пример

curl https://api.clavis.to/v1/images/generations \
  -H "Authorization: Bearer sk-..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "dall-e-3",
    "prompt": "A sunset over mountains",
    "n": 1,
    "size": "1024x1024"
  }'

Management API, управление аккаунтом

Авторизация

curl https://api.clavis.to/v1/manage/self \
  -H "Authorization: Bearer clv-your-management-key"

Права доступа

Права выбираются при создании ключа. Запрос без нужного права получает 403 с указанием, какого именно права не хватает.

Эндпоинты

Ключ под конкретную модель

curl -X POST https://api.clavis.to/v1/manage/keys \
  -H "Authorization: Bearer clv-your-management-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "customer-42",
    "allowed_models": ["claude-opus-5"],
    "rpm_limit": 60,
    "spend_cap_rub": 500,
    "spend_window": "day"
  }'

Идентификатор без пула (claude-opus-5) разрешает любой пул этой модели, с пулом (claude-opus-5@gate1) — только его. Ответ содержит поле key с секретом: это единственный раз, когда он существует в открытом виде.

Сколько бесплатных запросов осталось

curl https://api.clavis.to/v1/manage/limits \
  -H "Authorization: Bearer clv-your-management-key"

{
  "free_pool": {
    "pool": "free-pool-1",
    "requests_used_today": 7,
    "requests_limit_per_day": 25,
    "requests_remaining": 18,
    "resets_at": "2026-08-18T00:00:00+00:00",
    "min_balance_rub": 1.0,
    "eligible": true
  },
  "api_keys": [
    { "id": "…", "name": "prod", "rpm_limit": 60, "spend_cap_rub": 500, "spend_window": "day" }
  ]
}

Баланс и доступность модели

import requests

H = {"Authorization": "Bearer clv-your-management-key"}
BASE = "https://api.clavis.to/v1/manage"

balance = requests.get(f"{BASE}/balance", headers=H).json()
print(balance["balance_rub"], balance["spent_today_rub"])

m = requests.get(f"{BASE}/models/claude-opus-5", headers=H).json()
print(m["pricing"]["input_rub_per_1m"], m["availability"]["uptime_percent"])
if not m["access"]["can_call"]:
    print("blocked:", m["access"]["blocked_reason"])

Счёт на пополнение

curl -X POST https://api.clavis.to/v1/manage/invoices \
  -H "Authorization: Bearer clv-your-management-key" \
  -H "Content-Type: application/json" \
  -d '{"amount_rub": 1000, "provider": "antilopay"}'

{
  "order_id": "clavis_9f2c…",
  "payment_url": "https://pay.antilopay.com/…",
  "amount_rub": 1000.0,
  "provider": "antilopay"
}

provider принимает antilopay (карты и СБП) или heleket (крипта). Статус оплаты потом читается через GET /v1/manage/invoices/:order_id.

Безопасность

Ключу можно задать срок жизни и список разрешённых IP или подсетей: запрос с другого адреса получит 403. Ключ управления не может выпустить другой ключ управления и не может сменить пароль, email или настройки 2FA, поэтому утечка не даёт закрепиться в аккаунте. Дата и адрес последнего запроса по каждому ключу видны в кабинете.

Биллинг и тарификация

Ошибки

Разбор ошибки 400

Быстрая диагностика

• invalid_request, неверная форма запроса. Проверьте URL, заголовки, JSON, имя модели, названия полей и диапазоны параметров.
• authentication_error, неверный ключ или заголовок авторизации. Claude-эндпоинт (/v1/messages) использует x-api-key, OpenAI, Authorization: Bearer.
• not_found, модель недоступна или имя с опечаткой. Скопируйте точный id со страницы /models.
• Поля из другого API. Не смешивайте схемы Chat Completions, Anthropic Messages, Responses и Gemini в одном запросе.
• context_length_exceeded, контекст слишком большой. Сократите историю/файлы или начните новую сессию.
• content_filter, блокировка фильтром безопасности. См. раздел «Фильтры безопасности» ниже.
• Неверная схема инструмента. Имена функций должны быть валидны, parameters, корректным JSON Schema, а каждое поле из required, присутствовать в properties.

Вызов инструментов (tools / function calling)

Вызов инструментов полностью поддерживается для моделей Claude, и через /v1/messages (нативный формат Anthropic), и через /v1/chat/completions (формат OpenAI). Работает как с базовым id (например claude-opus-4-5-20251101), так и с явным выбором пула через суффикс (…@pool); стриминг тоже поддержан.

Claude / Anthropic

• Передавайте anthropic-version: 2023-06-01 и max_tokens, без них Claude часто отвечает 400.
• В messages кладите только ходы user/assistant. Системную инструкцию, в верхнеуровневое поле system.
• Блок tool_result должен ссылаться на id предыдущего tool_use; неверный порядок или отсутствие id, ошибка валидации.
• Мультимодальные блоки должны следовать нативной структуре Claude (source, media_type, base64).
• При отладке убирайте необязательные сэмплинг-параметры (top_p, лишние stop_sequences).

OpenAI / Gemini

• Responses API использует input; Chat Completions, messages. Не путайте их.
• Мультимодальные поля зависят от эндпоинта, не отправляйте file_url/base64 туда, где они не поддержаны.
• Для structured output схема должна быть парсимой, а промпт, не противоречить ей.
• При 400 уберите продвинутые опциональные поля (stream_options, modalities) и повторите минимальный запрос.

Фильтры безопасности и ролплей

Что вы можете увидеть

• Прямой отказ, модель пишет, что не может помочь, или уводит в безопасную сторону.
• Пустой ответ, некоторые клиенты показывают пустое сообщение; это всё ещё может быть фильтр.
• Оборванный вывод, стриминг останавливается на середине без нормального завершения.
• Блокировка кандидатов, Gemini может вернуть finishReason: SAFETY или blockReason.
• Коды ошибок, content_filter / policy / safety / blocked.
• Отказ ещё до генерации. Пул alibabacloud проверяет текст запроса до того, как модель его увидит, и отвечает HTTP 400 с кодом content_filter. Токены в этом случае не расходуются, потому что генерации не было.

Почему отфильтрованные запросы всё равно тарифицируются

Модель уже обработала запрос: прочитала ввод, поняла контекст и провела классификацию безопасности, это расходует входные токены. Отказы и предупреждения тоже считаются как выходные токены, а при стриминге часть токенов уже сгенерирована. Официальные API возвращают usage за этот расход, и сервис обязан его учесть.

Что делать

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

Этот раздел, только техническое объяснение поведения API. Фильтры, отказы и блокировки определяются официальными моделями и их политиками; за соответствие ввода и использования применимым правилам отвечает пользователь.

FAQ / Решение проблем

Оплатил, но баланс не обновился

Чаще всего это короткая задержка между вебхуком платёжной системы и зачислением. Откройте «Историю операций» в личном кабинете и проверьте статус платежа. Если списание прошло, но баланс не пополнился в течение нескольких минут, напишите в поддержку для ручной сверки.

Claude Code: контекст переполнен

Выполните /clear, чтобы очистить текущий контекст и начать новый диалог. Для больших проектов делите работу на этапы, чтобы сессии не разрастались.

/clear

Токен скопирован не полностью

• Используйте иконку копирования рядом с ключом, она копирует значение целиком.
• Если выделяете вручную, выделите всю строку от sk- до конца.
• Убедитесь, что нет лишних пробелов и переносов строк перед вставкой в клиент.

Не устанавливается Node.js

• Установите Node.js 18 или новее.
• На Windows запускайте PowerShell или CMD от имени администратора.
• Переоткройте терминал после установки и проверьте версии.

node --version
npm --version

Таймаут запроса

• Используйте единый эндпоинт https://api.clavis.to (OpenAI-совместимый) или /v1/messages для Claude.
• Проверьте локальный прокси, фаервол и DNS.
• Убедитесь, что имя модели указано верно (точный id со страницы /models).
• Для длинных генераций включайте стриминг, чтобы соединение не простаивало.

Агент не вызывает инструменты (пустые аргументы)

Вызов инструментов поддержан для Claude и через /v1/messages, и через /v1/chat/completions, с базовым id или суффиксом пула, в стриминге и без. Если аргументы приходят пустыми, почти всегда дело в формате запроса со стороны клиента: не смешивайте схемы tools разных API и не отправляйте Claude-инструменты в формате OpenAI и наоборот. Начните с минимального запроса с одним инструментом и проверьте, что приходит корректный tool_use/tool_calls с аргументами.