Документация 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": "sk-ваш-апи-ключ",
    "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-4.1"
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": "sk-ваш-апи-ключ"
}

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=sk-ваш-апи-ключ
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):

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               // очень дёшево

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

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="ВАШ_CLAVIS_API_КЛЮЧ"

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="sk-ваш-апи-ключ",
    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"
  }'

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"
  }'

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

Ошибки

Разбор ошибки 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.

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

Модель уже обработала запрос: прочитала ввод, поняла контекст и провела классификацию безопасности — это расходует входные токены. Отказы и предупреждения тоже считаются как выходные токены, а при стриминге часть токенов уже сгенерирована. Официальные 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 с аргументами.