Quickstart

Sign in, get a connection token, make the first call. Five minutes. Red-team models need card-based identity verification (the free 1,000/day allowance stays).

1. Sign in and issue a token

Sign in at kotoba.cloud/account with a passkey or a wallet, then “Use from a CLI / IDE” → “Issue a connection token”. It is shown once.

Shell

export KOTOBA_API_TOKEN="kc_pat_<your-token>"
curl -s https://api.kotoba.cloud/v1/models -H "Authorization: Bearer $KOTOBA_API_TOKEN"

2. Verify (needed for red-team models)

In the account console's “Identity verification” register a credit or debit card; the code-review scope is approved within seconds. Blue-team models skip this step.

Shell

curl -s https://api.kotoba.cloud/v1/research/status -H "Authorization: Bearer $KOTOBA_API_TOKEN"
# → {"status": "eligible", "freeTier": {...}, "scopes": [{"id": "owned", "status": "approved", "tasks": ["code-review"]}]}

3. The first call

curl

curl -s -X POST https://api.kotoba.cloud/v1/chat/completions \
  -H "Authorization: Bearer $KOTOBA_API_TOKEN" -H "content-type: application/json" \
  -d '{"model":"qwen3.8-flash-next-whitehacker","max_tokens":2048,
       "messages":[{"role":"user","content":"Review this login handler for auth bypasses: ..."}]}'

Python

from openai import OpenAI
client = OpenAI(base_url="https://api.kotoba.cloud/v1", api_key=os.environ["KOTOBA_API_TOKEN"])
r = client.chat.completions.create(model="qwen3.8-flash-next-whitehacker", max_tokens=2048,
    messages=[{"role": "user", "content": "Review this login handler for auth bypasses: ..."}])
print(r.choices[0].message.content)

The answer is an OpenAI chat.completion plus billing ("free" / "paid") and receiptId. The first call can take tens of seconds to minutes while the origin starts.

4. Next

Connect an agent or IDE (Claude Code, Codex CLI, Cursor, hermes…)
Tool calling · Streaming · Reasoning
Endpoint reference · CLI cheat sheet
Add credits (when you need more than the free allowance)

An unverified principal calling a red-team model gets 403 verification-required (before verification) or research-scope-required (no approved scope). The job API (submit, poll) is on the Streaming page.