Справочник API¶

Claudin.io — это совместимый с OpenAI API. Если вы работали с OpenAI API, всё здесь покажется знакомым — просто укажите базовый URL Claudin.io и используйте модель claudinio.

Базовый URL¶

https://api.claudin.io

Маршруты в стиле OpenAI находятся в /v1.

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

Отправляйте ваш API-ключ с каждым запросом, используя любой из этих заголовков:

Authorization: Bearer YOUR_API_KEY

x-api-key: YOUR_API_KEY

Модель¶

Идентификатор модели	Контекстное окно
`claudinio`	256K токенов

Используйте claudinio везде. (Некоторые клиенты ожидают формат provider/model — для них используйте claudinio/claudinio.)

Эндпоинты¶

Метод и путь	Описание
`POST /v1/chat/completions`	Chat completions — основной эндпоинт
`POST /v1/completions`	Устаревшие текстовые completions
`POST /v1/messages`	Формат Anthropic Messages
`POST /v1/responses`	Responses API (Codex)
`POST /v1/embeddings`	Текстовые эмбеддинги
`GET /v1/models`	Список доступных моделей

Chat completions¶

curl https://api.claudin.io/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "claudinio",
    "messages": [
      {"role": "system", "content": "You are a helpful assistant."},
      {"role": "user", "content": "Write a haiku about proxies."}
    ],
    "temperature": 0.7
  }'

Поддерживаются стандартные параметры OpenAI: messages, temperature, top_p, max_tokens, stream, stop, tools / tool_choice (function calling), response_format и так далее. У двух из них есть ограничения, о которых стоит знать перед отправкой: max_tokens ограничивается нижним и верхним порогом, а n должно быть 1.

`max_tokens` и рассуждения¶

Модели Claudinio сначала рассуждают, а потом отвечают, и токены рассуждений учитываются в max_tokens — один и тот же бюджет покрывает внутреннюю цепочку рассуждений и видимый ответ. Поэтому небольшой max_tokens может быть почти полностью израсходован на рассуждения, оставив ответ обрезанным на полуслове.

Чтобы этого избежать, значения ниже 32000 автоматически повышаются до 32000. С другой стороны, значения выше 393216 понижаются до 393216 — максимума, который принимают модели, — потому что большее число отклоняется сразу, а не трактуется как «сколько угодно». Всё, что между этими значениями, передаётся без изменений, а опустить параметр всегда можно.

max_tokens — это потолок, а не резервирование: вы платите за фактически сгенерированные токены, поэтому щедрое значение ничего не стоит дополнительно.

Если вы разбираете структурированный вывод (JSON, XML, строгий формат), проверяйте finish_reason перед разбором — "length" означает, что ответ упёрся в лимит токенов и неполон, так что ошибка разбора ожидаема, а не является проблемой модели:

choice = response.choices[0]
if choice.finish_reason == "length":
    ...  # truncated — retry with a larger max_tokens
data = json.loads(choice.message.content)

Несколько completions (`n`)¶

Поддерживается только n = 1. Отправка n больше 1 возвращает 400 с "code": "unsupported_parameter"; опустить параметр всегда безопасно.

Модели Claudinio сначала рассуждают, а потом отвечают, и проход рассуждений порождает единую линию мысли — нет дешёвого способа разветвить её на несколько независимых кандидатов, поэтому апстримы и не предлагают такого. Если вам нужно больше одного кандидата, отправляйте запрос несколько раз (более высокая temperature даст разнообразие), и учтите, что каждый запрос тарифицируется отдельно.

Мы отклоняем n > 1, а не молча возвращаем единственный вариант: клиент, который запросил четыре и получил один, обычно падает позже, в собственном коде, без нашей ошибки, объясняющей причину.

Стриминг¶

Установите "stream": true, чтобы получать server-sent events в формате стриминга OpenAI (чанки data: {...}, завершающиеся data: [DONE]).

Вызов инструментов / функций¶

claudinio поддерживает вызовы инструментов. Передавайте tools и считывайте tool_calls из ответа — точно так же, как в OpenAI API. Именно это позволяет ему работать внутри агентных редакторов вроде Claude Code, Kilo и Cursor.

Мультимодальный ввод¶

claudinio — текстовая модель, но Claudin.io прозрачно обрабатывает блоки изображений, аудио и видео: если вы их отправляете, прокси конвертирует их в текстовые описания/транскрипции до того, как их увидит модель. Вам не нужно делать ничего особенного — отправляйте стандартные контент-блоки OpenAI, и всё заработает.

Ошибки¶

Ошибки следуют формату ошибок OpenAI:

{ "error": { "message": "…", "type": "…", "code": "…" } }

Статус	Значение	Что делать
`401`	Недействительный или отсутствующий API-ключ	Проверьте ключ и заголовок аутентификации
`403`	Эндпоинт не разрешён	Используйте один из поддерживаемых путей `/v1/*`
`402`	Нет активной подписки	Оформите подписку — повторные попытки не помогут
`429`	Достигнут лимит бюджета или ограничение частоты запросов	Дождитесь сброса окна (см. заголовок `Retry-After`) или перейдите на более дорогой тариф
`400`	Некорректный запрос	Проверьте ваш JSON / параметры — см. `max_tokens` и `n`
`5xx`	Сбой апстрима/провайдера	Повторяйте с экспоненциальной задержкой (backoff)

Детали провайдера скрыты намеренно

Сообщения об ошибках очищаются, чтобы не раскрывать нижележащего провайдера модели. Вы всегда будете видеть ошибки в брендинге Claudin.io и в формате OpenAI.

Исчерпание лимита бюджета¶

Когда вы исчерпываете защиту от перерасхода текущего окна, запросы возвращают 429 с заголовком Retry-After, указывающим, сколько секунд осталось до сброса окна. Ваша панель управления показывает точное время сброса и оставшийся бюджет. Делайте паузу согласно этому заголовку, а не повторяйте запрос сразу. О том, как работают окна, читайте в разделе Планы и лимиты.

Сообщение вместо `429`¶

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

Если вы строите автоматизацию, не читайте 2xx как «работа выполнена». Считайте ответ, сообщающий о достигнутом лимите, достигнутым лимитом и делайте паузу до обнуления окна. 429 выше остаётся поведением по умолчанию и именно его получает почти любой аккаунт.

Ограничение частоты запросов¶

Claudin.io не блокирует наглухо обычное использование. Агрессивные частоты запросов замедляются (прозрачный троттлинг), а не отклоняются, поэтому корректно ведущие себя клиенты никогда не страдают. На практике вам не нужно ничего делать — просто повторите запрос при редком 429.