Caicaini
Начать

Эндпоинты

POST /v1/messages

Основной эндпойнт. Отправляешь список сообщений, получаешь ответ модели. Поддерживает системные подсказки, многоповоротные диалоги, изображения, инструменты, размышление и стриминг.

Базовый вызов

Три обязательных поля: model, max_tokens и messages. Поле system опционально, но его рекомендуется задавать, чтобы управлять тоном и ограничениями.

curl https://caicaini.com/v1/messages \
  -H "Authorization: Bearer cai_api_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "caicaini/sonnet",
    "max_tokens": 1024,
    "system": "You are a senior backend engineer. Be terse.",
    "messages": [
      {"role": "user", "content": "Why prefer queues over cron for retries?"}
    ]
  }'

Поля запроса

ПолеТипОписание
modelобязательноstringОдин из пяти виртуальных id. См. Модели.
max_tokensобязательноintegerЖёсткий потолок на количество токенов, которые модель может сгенерировать. Списываем за фактически использованные, но никогда больше этого потолка.
messagesобязательноarrayИстория диалога. Сообщения user и assistant чередуются, заканчиваются сообщением user.
systemstringСистемная подсказка. Появляется один раз в начале контекста. Управляет тоном, форматом вывода и ограничениями.
temperaturenumber 0–1По умолчанию 1. Меньшие значения делают модель более детерминированной.
top_pnumber 0–1Nucleus sampling. Лучше задавать либо temperature, либо top_p, но не оба сразу.
stop_sequencesstring[]До четырёх строк. Модель прекращает генерацию, как только сгенерирует любую из них.
streambooleanКогда true, ответ приходит как SSE-стрим. См. Стриминг.
toolsTool[]Описания функций, которые модель может вызывать. См. Инструменты.
tool_choiceobjectПринудить конкретный инструмент или { type: "any" }, чтобы заставить вызвать любой инструмент.
thinkingobjectВключает расширенное размышление на caicaini/opus. См. Размышление.
metadataobjectОпционально { user_id?: string }. Помогает в расследованиях злоупотреблений и в отчётности по пользователям.

Массив messages

У каждого сообщения есть role ("user" или "assistant") и content. content может быть строкой или массивом типизированных контент-блоков. Используй массив, когда в одном повороте нужно смешать изображения, результаты инструментов или несколько текстовых сегментов.

curl https://caicaini.com/v1/messages \
  -H "Authorization: Bearer cai_api_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "caicaini/auto",
    "max_tokens": 512,
    "messages": [
      {"role": "user",      "content": "Plan a 3-day Lisbon trip in October."},
      {"role": "assistant", "content": "Sure. Day 1: Alfama walking tour..."},
      {"role": "user",      "content": "Skip the tram. I want food only."}
    ]
  }'

Ответ

ответ · 200 OK
{
  "id": "msg_01H8fkx2N3p4q5r6s7t8u9v0wx",
  "type": "message",
  "role": "assistant",
  "content": [
    { "type": "text", "text": "Cron pretends a job is fire-and-forget..." }
  ],
  "model": "caicaini/sonnet",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 38,
    "output_tokens": 184,
    "cache_creation_input_tokens": 0,
    "cache_read_input_tokens": 0,
    "credits_consumed": 92
  }
}

Поля ответа

ПолеТипОписание
idstringУникальный id этого сообщения. Сохраняй на случай тикетов поддержки.
type"message"Для /v1/messages всегда "message".
role"assistant"В ответе всегда "assistant".
contentContentBlock[]Массив типизированных блоков. Минимум один. Перебирай их — допущения «только текст» ломаются с инструментами и размышлением.
modelstringВиртуальный id, который ты запросил. Названия нижележащих провайдеров мы не раскрываем.
stop_reasonstringОдно из "end_turn", "max_tokens", "stop_sequence", "tool_use".
usage.input_tokensintegerВходные токены (без учёта чтения из кеша).
usage.output_tokensintegerСгенерированные токены, включая токены блоков размышления.
usage.cache_creation_input_tokensintegerТокены, записанные в кеш промпта в этом повороте.
usage.cache_read_input_tokensintegerТокены, отданные из кеша промпта в этом повороте.
usage.credits_consumedintegerАвторитетная сумма списанных за этот поворот кредитов. Расширение Caicaini.

POST /v1/messages/count_tokens

Возвращает только число входных токенов для тела запроса, не запуская модель. Полезно для предварительной оценки бюджета и решений роутинга. Бесплатно, но лимиты те же, что у /v1/messages.

curl https://caicaini.com/v1/messages/count_tokens \
  -H "Authorization: Bearer cai_api_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "caicaini/sonnet",
    "messages": [
      {"role": "user", "content": "How many tokens is this prompt?"}
    ]
  }'

Лимиты

  • Тело запроса до 16 МБ. Большинство изображений умещается без проблем; очень тяжёлые vision-нагрузки лучше разбивать или предварительно суммаризировать на клиенте.
  • Длина диалога ограничена только окном контекста модели. См. context_window в ответе Модели.
  • max_tokens не может превышать max_output_tokens конкретной модели.
ДалееChat completions