Quickstart

What you get#

The Caicaini API gives you programmatic access to our hosted models behind a single HTTP endpoint. The shape of the request mirrors the industry-standard Messages API convention, so anything that targets that shape — your own client, a third-party wrapper, or raw fetch — works without changes.

Auth is a bearer token. Billing comes from a separate apiCredits pool you top up directly — your subscription credits are never touched by API traffic, and vice versa.

1. Mint an API key#

Sign in, then visit /developers/keys and click Create key. Keys start with the prefix cai_api_ and are shown once — copy the full key into a password manager or environment variable before closing the dialog.

2. Export the key#

Save the key to your shell so it stays out of source control. The examples below all read from CAICAINI_API_KEY.

export CAICAINI_API_KEY="cai_api_..."

3. Send a message#

The minimum valid request body is model, max_tokens, and messages. Use caicaini/auto if you want the smart router to pick a model for you — see Models for the full list.

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. Read the response#

Every successful response carries an id, an array of content blocks (text first, then any tool calls or thinking blocks), the resolved model, a stop_reason, and a usage object that tells you exactly how many credits this turn cost.

{
  "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
  }
}

The usage.credits_consumed field is a Caicaini extension. It is authoritative — what you see here is what was deducted from your apiCredits balance.

Where to go next#

1. Stream the response with "stream": true to render tokens as they arrive.
2. Add tools and let the model call functions in your code.
3. Send images as content blocks for visual reasoning.
4. Handle errors so a transient 429 or 529 does not crash your job.