端点

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	模型可生成 token 数的硬上限。我们按实际使用计费，但绝不会超过这个上限。
messages必填	array	对话历史。user 与 assistant 消息交替，并以 user 消息结尾。
system	string	系统提示。出现在上下文最顶端，仅一次。用来引导语气、输出格式和约束。
temperature	number 0–1	默认 1。值越低，模型越倾向于确定性输出。
top_p	number 0–1	核采样。建议只设置 temperature 或 top_p 之一，不要同时设置。
stop_sequences	string[]	最多四个字符串。模型一旦生成其中任意一个就停止。
stream	boolean	为 true 时，响应是 SSE 流。详见流式响应。
tools	Tool[]	模型可以调用的函数定义。详见工具。
tool_choice	object	强制使用某个工具，或设置 { type: "any" } 要求必须调用任意工具。
thinking	object	在 `caicaini/opus` 上启用扩展推理。详见深度思考。
metadata	object	可选 { 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
  }
}

响应字段

字段	类型	说明
id	string	本条消息的唯一 id。建议保留以便提工单排查。
type	"message"	/v1/messages 永远是 "message"。
role	"assistant"	响应里永远是 "assistant"。
content	ContentBlock[]	类型化内容块的数组。至少有一项。请遍历处理——只看 text 的假设在使用工具或思考时会出错。
model	string	你请求的虚拟 ID。我们不会暴露底层供应商名称。
stop_reason	string	"end_turn"、"max_tokens"、"stop_sequence"、"tool_use" 之一。
usage.input_tokens	integer	输入 token 数（不含缓存读取的部分）。
usage.output_tokens	integer	已生成的 token 数，包含 thinking 块的 token。
usage.cache_creation_input_tokens	integer	本轮写入提示缓存的 token 数。
usage.cache_read_input_tokens	integer	本轮从提示缓存读取的 token 数。
usage.credits_consumed	integer	本轮实际扣除的积分（权威值）。Caicaini 自有扩展。

POST /v1/messages/count_tokens

只返回请求体的输入 token 数，不会真正调用模型。可用于预算预估和路由决策。免费，但与 /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?"}
    ]
  }'