Build on Kitsune.

The installer asks for your key, reads the catalogue, and writes each agent's config with every model your key can use. It only touches files in your home directory, and it backs up anything it rewrites.

curl -fsSL https://kitsune.cv/install | bash

Flags: --agent, --all, --list, --yes, --dry-run, --force. An agent already pointed at a different endpoint is skipped until you pass --force.

Every request needs an Authorization: Bearer header. Keys are created in the console, can carry a spend cap and expiry, and are revoked instantly. Legacy sk-dr-… keys created before the rename still authenticate.

Header

Authorization: Bearer kts-…

Key format

kts- + 48 hexadecimal characters

Billing

One rail — pay as you go, charged from the account balance.

CORS

No CORS headers are sent. Call the API from a server, not from another origin in a browser.

Prices and capabilities come from the live catalog. A model with no cache price bills cached prompt tokens at the input price — the cache column reads = input.

Get the same list programmatically from GET /v1/catalog (public) or GET /v1/models (key-scoped).

Send model and messages. A message has a role and content: system, developer, user, assistant or tool. Content is a string or an array of content parts for images.

Response

The assistant reply is in choices[0].message.content. Usage is reported by the model and billed for that turn.

{
  "id": "chatcmpl-7f2c1b1e",
  "object": "chat.completion",
  "created": 1762300000,
  "model": "minimax-m3.1-flash",
  "choices": [{
    "index": 0,
    "message": {
      "role": "assistant",
      "content": "HTTP caching stores responses so later requests can reuse them."
    },
    "finish_reason": "stop"
  }],
  "usage": {
    "prompt_tokens": 21,
    "completion_tokens": 38,
    "total_tokens": 59,
    "prompt_tokens_details": { "cached_tokens": 0 }
  }
}

Set stream: true. Content arrives in choices[0].delta.content, thinking in delta.reasoning_content, and tool calls as indexed fragments in delta.tool_calls. The stream ends with data: [DONE].

data: {"choices":[{"index":0,"delta":{"role":"assistant","content":"HTTP "},"finish_reason":null}]}

data: {"choices":[{"index":0,"delta":{"content":"caching "},"finish_reason":null}]}

data: {"choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}

data: {"choices":[],"usage":{"prompt_tokens":21,"completion_tokens":38,"total_tokens":59}}

data: [DONE]

Send reasoning_effort: "low" | "medium" | "high" | "max". The gateway forwards it unchanged; max asks for the deepest budget the model offers, and the model decides how much to think. Reasoning text comes back as message.reasoning_content — some models use reasoning or thinking, and those fields pass through untouched.

curl https://kitsune.cv/v1/chat/completions \
  -H "Authorization: Bearer $KITSUNE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "minimax-m3.1-flash",
    "messages": [
      {"role": "user", "content": "Design a retry strategy for a payment API."}
    ],
    "reasoning_effort": "high"
  }'

Whether a model actually reasons is shown by the thinking badge in the model table above and on Live models.

Kitsune forwards tools, tool_choice and parallel_tool_calls, then returns the model's tool_calls. Your code executes the function and sends the result back as a role:"tool" message with the same tool_call_id before calling again.

curl https://kitsune.cv/v1/chat/completions \
  -H "Authorization: Bearer $KITSUNE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "minimax-m3.1-flash",
    "messages": [{"role": "user", "content": "What is the time in Tashkent?"}],
    "tools": [{
      "type": "function",
      "function": {
        "name": "get_time",
        "description": "Return the current time for a city.",
        "parameters": {
          "type": "object",
          "properties": {"city": {"type": "string"}},
          "required": ["city"],
          "additionalProperties": false
        }
      }
    }],
    "tool_choice": "auto",
    "parallel_tool_calls": true
  }'

// 1. assistant returns a call
{ "role": "assistant", "content": null, "tool_calls": [{
    "id": "call_abc123",
    "type": "function",
    "function": { "name": "get_time", "arguments": "{\"city\":\"Tashkent\"}" }
}] }

// 2. you run it, then append the result
{ "role": "tool", "tool_call_id": "call_abc123",
  "content": "{\"time\":\"2026-11-03T20:30:00Z\"}" }

// 3. call again with the same tools -> final assistant content

Use a model with the vision badge. Pass content as an array of text and image_url parts — HTTPS URLs and base64 data URLs are both accepted, model permitting.

curl https://kitsune.cv/v1/chat/completions \
  -H "Authorization: Bearer $KITSUNE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "minimax-m3.1-flash",
    "messages": [{
      "role": "user",
      "content": [
        {"type": "text", "text": "What is in this image?"},
        {"type": "image_url", "image_url": {"url": "https://example.com/chart.png"}}
      ]
    }]
  }'

response_format also accepts json_object for loose JSON. For strict schemas, use json_schema with strict: true where the model supports it.

Kitsune prepends the admin main system prompt and the model's own prompt, keeps your role:"system" message, then appends the current UTC time when the model has time context enabled. The time goes at the end so the stable prefix stays cacheable.

system: <main prompt>

        <model prompt>

        <your system message>

        Current UTC time: 2026-11-03 20:30:00 UTC
user:   Explain HTTP caching...

Each successful request is priced from the model row at the time of the call:

cost = uncached_input × input_price
     + cached_input   × cache_price
     + output_tokens  × output_price

• When a model has no cache price, cached prompt tokens bill at the input price.
• Cache hits are reported as prompt_tokens_details.cached_tokens or cache_read_input_tokens; both are counted and never exceed the prompt.
• Sub-cent amounts accrue on the account and are charged in whole cents as they cross the threshold.
• Failed calls are not billed. Aborted streams are billed for the usage reported for the turn.
• An empty balance returns 402 insufficient_balance before the request is sent.

Response headers

x-kitsune-billing: payg
content-type: application/json

A model can carry more than one route. Where a second route is wired, the first healthy one takes the request and a retryable failure moves to the next — transport errors, 401/402/403/408/409/425/429 and 5xx. A failing route is rested with an exponential cooldown.

Errors use a single envelope. Branch on error.code, not the message.

{
  "error": {
    "message": "balance is empty — top up to keep using the API",
    "type": "gateway_error",
    "code": "insufficient_balance"
  }
}

Account, usage & keys

The same key manages the account it belongs to. Key creation returns the secret once — store it before leaving the response.

curl https://kitsune.cv/v1/account \
  -H "Authorization: Bearer $KITSUNE_KEY"

curl "https://kitsune.cv/v1/usage?days=30" \
  -H "Authorization: Bearer $KITSUNE_KEY"

curl https://kitsune.cv/v1/keys \
  -H "Authorization: Bearer $KITSUNE_KEY"

# create a key (secret is returned once)
curl https://kitsune.cv/v1/keys \
  -H "Authorization: Bearer $KITSUNE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"label":"ci","spend_cap_cents":500,"expires_days":90}'

Any other JSON field is forwarded unchanged. Kitsune does not execute tools, browse, or store prompts. The complete parameter table and every request example live in the cookbook.