Справочник API
Base URL: https://ci-ai.duckdns.org/v1 · авторизация: Authorization: Bearer <ключ>. Всё ниже соответствует спецификации OpenAI; вендорские расширения — в extra_body.
Аутентификация
Ключи начинаются с ciai_ и создаются в панели управления. Относитесь к ключу как к паролю: передавайте только по HTTPS, ротируйте из панели и ограничивайте каждый ключ моделями, которые нужны нагрузке.
Chat completions
POST /v1/chat/completions
Content-Type: application/json
{
"model": "auto", // или id из каталога, напр. "qwen3.8-27b"
"messages": [
{"role": "system", "content": "Ты лаконичный ассистент."},
{"role": "user", "content": "Сколько будет 17 * 23?"}
],
"stream": true,
"temperature": 0.2,
"tools": [],
"extra_body": {
"gateway": {
"fallback": ["deepseek-flash-4.1", "qwen-flash-next-3.8", "gpt-5"],
"cache": "auto",
"region": "eu"
}
}
}
"model": "auto" предоставляет выбор роутеру по политике вашего ключа (качество / цена / задержка). Ответы несут заголовки x-gateway-model, x-gateway-region и, где применимо, x-gateway-fallback и x-gateway-cache: HIT.
Локальный запуск open-weight моделей
Для qwen-flash-next-3.8, qwen3.8-27b и deepseek-flash-4.1 веса открыты: карточка модели в каталоге содержит ссылку на репозиторий весов и минимальные требования (для qwen3.8-27b — 24 ГБ VRAM в 4-битном квантовании). Локальный инференс не проходит через шлюз и не тарифицируется; ключ нужен, только когда пиковая нагрузка превышает возможности вашего GPU — включите "burst": "gateway" в extra_body.gateway, и перелив пойдёт в наш open-weight флот по тем же ценам каталога.
Эмбеддинги
POST /v1/embeddings
{ "model": "gemini-embedding-2", "input": ["текст riliz-заметок"] }
Список моделей
GET /v1/models
Authorization: Bearer <ключ>
Возвращает id, цены, размер контекста и флаги open_weights/runs_locally всех моделей, разрешённых ключу. Ответ кэшируется на 5 минут.
Модификаторы маршрутов и BYOK
Суффиксы к id модели: :fast — минимальная задержка, :cheap — минимальная цена, :eu — только EU-обработка, :exact — без фолбэков. Пример: "model": "deepseek-flash-4.1:fast". Неизвестный суффикс возвращает ошибку 400.
BYOK. На ступенях Starter и выше можно привязать свой ключ вендора в панели: запросы к этому вендору идут напрямую, комиссия шлюза не взимается, а фолбэки и кэш продолжают работать.
Стриминг (SSE)
Идентично OpenAI: stream: true выдаёт события chat.completion.chunk и завершается [DONE]. Чанки от фолбэк-апстримов сохраняют ту же форму событий — клиентам не нужно обрабатывать переключение.
Ошибки
| Статус | Код | Значение |
|---|---|---|
| 401 | invalid_key | Ключ отсутствует, отозван или повреждён |
| 402 | budget_exceeded | Достигнут жёсткий лимит ключа или аккаунта |
| 429 | rate_limited | Лимит запросов/мин; повторяйте с Retry-After |
| 502 | upstream_down | Все фолбэки не сработали; можно безопасно повторить |
Лимиты и квоты
Запросы/мин по ступеням — на странице Тарифы. Дневные квоты по токенам задаются на ключ в панели; при 80% квоты приходит почтовый алерт. Лимиты обнуляются в 00:00 UTC.
Сниппеты SDK
# Python — работает с официальным пакетом openai без изменений
from openai import OpenAI
client = OpenAI(
base_url="https://ci-ai.duckdns.org/v1",
api_key=os.environ["CIAI_KEY"],
)
r = client.chat.completions.create(model="auto",
messages=[{"role": "user", "content": "ping"}])
// Node — openai npm SDK
import OpenAI from "openai";
const client = new OpenAI({
baseURL: "https://ci-ai.duckdns.org/v1",
apiKey: process.env.CIAI_KEY,
});
const r = await client.chat.completions.create({
model: "deepseek-flash-4.1",
messages: [{ role: "user", content: "ping" }],
});
Вебхуки
Опциональные POST-колбэки на budget.warning, budget.exceeded и key.rotated. Полезные нагрузки подписаны HMAC X-Signature-256 с секретом ключа.
Журнал изменений
- — добавлены open-weight модели
qwen-flash-next-3.8,qwen3.8-27bиdeepseek-flash-4.1, включая режим локального запуска. - — у
gemini-3-proдобавлен режим контекста 1M. - — ключи кэша можно разделять по тенантам.
- — заголовок ответа
x-gateway-fallback.