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

Что ты получишь#

Caicaini API даёт программный доступ к нашим моделям через один HTTP-эндпойнт. Форма запроса повторяет индустриальную конвенцию Messages API, поэтому всё, что в неё целит — твой клиент, сторонняя обёртка или сырой fetch — работает без изменений.

Аутентификация — bearer-токен. Биллинг идёт из отдельного пула apiCredits, который ты пополняешь напрямую — твои подписочные кредиты никогда не трогаются API-трафиком и наоборот.

1. Создай API-ключ#

Войди в аккаунт, открой /developers/keys и нажми Create key. Ключи начинаются с префикса cai_api_ и показываются один раз — скопируй полный ключ в менеджер паролей или переменную окружения, прежде чем закрыть диалог.

2. Экспортируй ключ#

Сохрани ключ в shell, чтобы он не попал в систему контроля версий. Все примеры ниже читают CAICAINI_API_KEY.

export CAICAINI_API_KEY="cai_api_..."

3. Отправь сообщение#

Минимально валидное тело запроса — model, max_tokens и messages. Если хочешь, чтобы умный роутер выбрал модель за тебя, используй caicaini/auto — полный список смотри в Моделях.

curl https://caicaini.com/v1/messages \
  -H "Authorization: Bearer cai_api_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "caicaini/auto",
    "max_tokens": 256,
    "messages": [
      {"role": "user", "content": "Write a haiku about overdue invoices."}
    ]
  }'

4. Прочитай ответ#

Каждый успешный ответ несёт id, массив блоков content (сначала текст, затем любые вызовы инструментов или блоки размышления), итоговую model, stop_reason и объект usage, который точно говорит, сколько кредитов стоил этот поворот.

{
  "id": "msg_01H8fkx2N3p4q5r6s7t8u9v0wx",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Inbox keeps glowing — / payment terms net thirty days, / silence net forever."
    }
  ],
  "model": "caicaini/auto",
  "stop_reason": "end_turn",
  "usage": {
    "input_tokens": 14,
    "output_tokens": 23,
    "cache_creation_input_tokens": 0,
    "cache_read_input_tokens": 0,
    "credits_consumed": 12
  }
}

Поле usage.credits_consumed — это расширение Caicaini. Оно авторитетное — сколько здесь, столько и было списано с твоего баланса apiCredits.

Куда дальше#

1. Стримь ответ с "stream": true, чтобы рендерить токены по мере прихода.
2. Добавь инструменты, и пусть модель вызывает функции в твоём коде.
3. Отправляй изображения как контент-блоки для визуального рассуждения.
4. Обрабатывай ошибки, чтобы случайный 429 или 529 не ронял твою джобу.