Справочник 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]. Чанки от фолбэк-апстримов сохраняют ту же форму событий — клиентам не нужно обрабатывать переключение.

Ошибки

СтатусКодЗначение
401invalid_keyКлюч отсутствует, отозван или повреждён
402budget_exceededДостигнут жёсткий лимит ключа или аккаунта
429rate_limitedЛимит запросов/мин; повторяйте с Retry-After
502upstream_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 с секретом ключа.

Журнал изменений