Amanai

Amanai Docs

Quickstart

Get your first request running in under a minute.

The Amanai gateway speaks both the OpenAI Chat Completions API and the Anthropic Messages API. Point your client at the base URL and pass your sk-amanai-… key.

Base URL

Point your client at the gateway. The same endpoint serves both SDK and CLI traffic, fronted by Cloudflare for rate limiting and DDoS protection:

bash 
https://api.amanai.dev/v1

New here? You need an API key first. Get one with your credit pack, then paste it into the dashboard at ai.amanai.dev.

OpenAI SDK (Python)

Drop-in replacement — change only base_url and api_key.

bash 
from openai import OpenAI

client = OpenAI(
    base_url="https://api.amanai.dev/v1",
    api_key="sk-amanai-...",
)

response = client.chat.completions.create(
    model="amanai/glm-5.2",
    messages=[{"role": "user", "content": "Hello!"}],
    max_tokens=100,
)

print(response.choices[0].message.content)

Streaming

bash 
stream = client.chat.completions.create(
    model="amanai/glm-5.2",
    messages=[{"role": "user", "content": "Write a haiku."}],
    max_tokens=100,
    stream=True,
)
for chunk in stream:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="")

Claude Code (Anthropic Messages API)

Set environment variables, then run claude as usual. The gateway translates the Messages API transparently.

bash 
export ANTHROPIC_BASE_URL="https://api.amanai.dev"
export ANTHROPIC_AUTH_TOKEN="sk-amanai-..."
claude

CLI tools

Choose the one-command setup for the fastest install, or configure each CLI manually.

One-command setup (recommended)

Safe to re-run. Every installer creates a timestamped backup of the CLI's existing configuration before making changes, so your previous setup can be restored if needed.

Claude Code — backs up your settings, then lets you map live Amanai models to the Fable, Opus, Sonnet, and Haiku slots.

bash 
curl -fsSL https://ai.amanai.dev/setup/claude-code.sh | sh

After setup, quit open sessions, run claude daemon stop --any, then launch claude again so warm workers load the new configuration.

Claude Desktop Bridge — installs the signed local bridge and opens an interactive setup wizard for Claude Desktop. macOS tested only.

bash 
curl -fsSL https://ai.amanai.dev/setup/claude-desktop.sh | sh

Codex CLI — backs up your config, sets up the Responses API, and loads the live Amanai model catalog.

bash 
curl -fsSL https://ai.amanai.dev/setup/codex.sh | sh

OpenCode — backs up and safely merges your config, loads every live Amanai model, and lets you choose the default.

bash 
curl -fsSL https://ai.amanai.dev/setup/opencode.sh | sh

Grok Build — backs up your Grok config, loads every live Amanai model, and lets you choose the default. Install Grok Build first.

bash 
curl -fsSL https://ai.amanai.dev/setup/grok.sh | sh

OpenClaw — backs up your config, adds Amanai as an OpenAI-compatible provider, and verifies the selected model. Install OpenClaw first.

bash 
curl -fsSL https://ai.amanai.dev/setup/openclaw.sh | sh

Pi — backs up ~/.pi/agent/models.json, fetches the live Amanai catalog, maps each model's API adapter and thinking levels, and smoke-tests the gateway. Install Pi first (npm install -g --ignore-scripts @earendil-works/pi-coding-agent).

bash 
curl -fsSL https://ai.amanai.dev/setup/pi.sh | sh

Hermes — backs up ~/.hermes/config.yaml and .env, fetches the live model catalog, and writes the provider config via hermes config set. Install Hermes first.

bash 
curl -fsSL https://ai.amanai.dev/setup/hermes.sh | sh

Manual setup

Claude Code — set the gateway, token, and four model slots in ~/.claude/settings.json:

bash 
{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.amanai.dev",
    "ANTHROPIC_AUTH_TOKEN": "sk-amanai-...",
    "ANTHROPIC_DEFAULT_FABLE_MODEL": "amanai/glm-5.2",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "amanai/claude-opus-4.8",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "amanai/claude-sonnet-4.6",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "amanai/gpt-5.6-sol"
  },
  "model": "opus"
}

Codex CLI — create ~/.codex/config.toml with a Responses API provider and command-backed authentication. Replace /home/you with your actual home directory:

bash 
model = "amanai/gpt-5.6-sol"
model_provider = "amanai"
model_reasoning_effort = "medium"

[model_providers.amanai]
name = "Amanai"
base_url = "https://api.amanai.dev/v1"
wire_api = "responses"

[model_providers.amanai.auth]
command = "/home/you/.codex/amanai-token.sh"
timeout_ms = 5000
refresh_interval_ms = 0

Store your key in ~/.codex/auth.json:

bash 
{
  "auth_mode": "apikey",
  "OPENAI_API_KEY": "sk-amanai-..."
}

Create ~/.codex/amanai-token.sh, then run chmod 700 ~/.codex/amanai-token.sh:

bash 
#!/bin/sh
exec python3 -c 'import json,os; print(json.load(open(os.path.join(os.environ["HOME"], ".codex", "auth.json")))["OPENAI_API_KEY"])'

Also protect the key files with chmod 600 ~/.codex/auth.json ~/.codex/config.toml. Command-backed authentication lets Codex refresh the live Amanai model catalog.

Other OpenAI-compatible tools

Amanai also works with tools that support a custom OpenAI-compatible endpoint:

OpenCode

The bootstrap writes ~/.config/opencode/opencode.jsonc (or your XDG/OpenCode config directory), preserves unrelated settings and providers, and creates a timestamped backup before changing an existing file. OpenCode selects custom models as provider/model; because Amanai catalog IDs already begin with amanai/, the full selector is amanai/amanai/glm-5.2.

For unattended setup, provide the key and a model from the live catalog through environment variables:

bash 
curl -fsSL https://ai.amanai.dev/setup/opencode.sh | KEY=sk-amanai-... MODEL=amanai/glm-5.2 sh

Manual configuration uses a custom OpenAI-compatible provider in opencode.jsonc:

bash 
{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "amanai": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Amanai",
      "options": {
        "baseURL": "https://api.amanai.dev/v1",
        "apiKey": "sk-amanai-..."
      },
      "models": {
        "amanai/glm-5.2": { "name": "GLM 5.2" }
      }
    }
  },
  "model": "amanai/amanai/glm-5.2"
}

Aider

bash 
export OPENAI_API_BASE="https://api.amanai.dev/v1"
export OPENAI_API_KEY="sk-amanai-..."
aider --model amanai/glm-5.2

Continue (VS Code)

bash 
# ~/.continue/config.json
{
  "models": [{
    "title": "Amanai",
    "provider": "openai",
    "model": "amanai/glm-5.2",
    "apiBase": "https://api.amanai.dev/v1",
    "apiKey": "sk-amanai-..."
  }]
}

Cursor

Settings → Models → OpenAI API Base: $https://api.amanai.dev/v1, API Key: sk-amanai-...

curl

Send your key as a Bearer token or x-api-key header — both work.

bash 
curl https://api.amanai.dev/v1/chat/completions -H "Authorization: Bearer sk-amanai-..." -H "Content-Type: application/json" -d '{"model": "amanai/glm-5.2","messages":[{"role": "user","content": "Hello!"}],"max_tokens":100}'

Response:

bash 
{
  "object": "chat.completion",
  "model": "amanai/glm-5.2",
  "choices": [{
    "index": 0,
    "message": {"role": "assistant", "content": "Hello! How can I help you today?"},
    "finish_reason": "stop"
  }],
  "usage": {"prompt_tokens": 8, "completion_tokens": 9, "total_tokens": 17}
}

List available models

bash 
curl https://api.amanai.dev/v1/models
bash 
{"object": "list","data":[
  {"id": "amanai/glm-5.2","object": "model","owned_by": "amanai"},
  {"id": "amanai/kimi-k3","object": "model","owned_by": "amanai"},
  {"id": "amanai/jev-1.13","object": "model","modality": "structured_evaluation"},
  ...
]}

See Chat for the complete capability table. Context and output limits are model-specific and must be read from the catalog.

For typed decisions, use System One with amanai/jev-1.13 instead of a chat endpoint.

Reasoning effort

Most models support selectable reasoning depth. The gateway accepts reasoning.effort (OpenAI Responses API) or a thinking string ( Messages API), and forwards it to the upstream provider in whichever field that provider reads.

Llow — fast responses, lighter reasoning. Good for simple code edits and lookups.
Mmedium — balances speed and depth. The default for Codex CLI. Good for debugging and everyday work.
Hhigh — deeper reasoning for complex problems, refactors, and architecture decisions.
Xxhigh — maximum reasoning depth for the hardest problems. Slower and more expensive.

Not every model supports all levels. The catalog's thinking array on GET /v1/models shows which levels are available per model. Models with only ["auto"] have no runtime selector — the provider decides. Some fixed-variant models encode their level directly in the model ID.

Per-CLI usage: Codex — codex --reasoning-effort high or set model_reasoning_effort in config.toml. OpenCode — press Ctrl+T in the TUI to cycle variants. Pi — select from the thinking level picker in the model menu.

Next steps

  • API reference — shared authentication, headers, lifecycle, and error conventions
  • Chat — model catalog, capabilities, reasoning, and chat formats
  • Media — images, video, speech, files, and artifacts
  • Realtime — multi-turn WebRTC voice sessions
  • Embeddings — text vectors and batching
  • Rerank — query-document relevance ranking
  • System One — typed decisions from state and questions
  • Billing & pricing — general billing behavior and every model rate
  • Dashboard Playground — explore chat and non-chat APIs in one workspace