API Reference

Quick Start

OpenAI compatible. Drop in with 3 lines of code.

1. Get API Key

Log in to AICraft Console, go to API Keys, create a key. Format: sk- + 40 hex.

2. Base URL

3. First Call

Copycurl https://aicraftapi.net/v1/chat/completions   -H "Content-Type: application/json"   -H "Authorization: Bearer YOUR_API_KEY"   -d '{"model":"auto","messages":[{"role":"user","content":"Hello!"}]}'

Copy# pip install openai
from openai import OpenAI
client = OpenAI(api_key="YOUR_API_KEY", base_url="https://aicraftapi.net/v1")
response = client.chat.completions.create(model="auto", messages=[{"role":"user","content":"Hello!"}])
print(response.choices[0].message.content)

Copy// npm install openai
import OpenAI from "openai";
const client = new OpenAI({ apiKey: "YOUR_API_KEY", baseURL: "https://aicraftapi.net/v1" });
const r = await client.chat.completions.create({ model: "auto", messages: [{ role: "user", content: "Hello!" }] });
console.log(r.choices[0].message.content);

Copy// go get github.com/openai/openai-go
package main
import ("context"; "fmt"; openai "github.com/openai/openai-go"; "github.com/openai/openai-go/option")
func main() {
    c := openai.NewClient(option.WithAPIKey("YOUR_API_KEY"), option.WithBaseURL("https://aicraftapi.net/v1"))
    r, _ := c.Chat.Completions.New(context.Background(), openai.ChatCompletionNewParams{
        Model: openai.String("auto"),
        Messages: openai.F([]openai.ChatCompletionMessageParamUnion{openai.UserMessage("Hello!")}),
    })
    fmt.Println(r.Choices[0].Message.Content)
}

Download Tools (Step-by-Step)

Tools to get the most out of AICraft. Install in order: ① Node.js → ② VS Code → ③ Claude Code. Every step includes a verification check. If you get stuck, see the troubleshooting table in Step ③.

① Node.js (Prerequisite)

Installation Steps

1. Download: Click "Download Node.js 22 LTS" above to open the official page.
2. Version: Click the big green Download Node.js 22 LTS button (auto-detects your OS).
3. Install: Double-click the installer → Next → Finish. Windows users: make sure "Add to PATH" is checked (it is by default).
4. Verify: Open a terminal (Windows: Win+R → type cmd → Enter; Mac: "Terminal" app), run:

   node -v

   You should see v22.x.x ✅. Then run npm -v — if it prints a version too, everything is ready.

② VS Code

Installation Steps

1. Download: Click "Download VS Code" above and pick your OS (Windows / Mac).
2. Install: Double-click → Next. On Windows, tick "Add to PATH" and the "Open with Code" context-menu option.
3. Verify: Open VS Code — if the welcome page appears, you're done ✅.

Play B: Cline Extension (In-Editor AI Chat)

1. In VS Code, click the Extensions icon (4 squares) on the left, search Cline, click Install.
2. Click the Cline icon on the right sidebar to open its panel.
3. Set API Provider to OpenAI Compatible.
4. Fill in the fields below (use the API Key you create in ③ Step 2):

③ Claude Code Setup (Step-by-Step)

Claude Code is Anthropic's terminal AI coding agent — the core of this guide. Follow these 6 steps.

Step 1: Install Claude Code

Prerequisite: Node.js 18+ (go back to ① Node.js if you haven't installed it).

Option A (recommended) — official one-click script:

1. Download: Download Install Script
2. Open a terminal in the script's folder (Mac / Linux) and run bash install-claude-code.sh
3. When prompted > , paste the API Key you created, press Enter
4. The script installs Claude Code AND writes the config for you. When you see Done!, you're all set ✅

Option B — manual install: pick your OS:

Copy# Option 1: Official native installer (recommended, auto-updates)
curl -fsSL https://claude.ai/install.sh | bash

# Option 2: npm install (fallback, requires Node.js)
npm install -g @anthropic-ai/claude-code

# Verify
claude --version

Copy:: Windows — pick one:

:: Option A (recommended): install WSL first (Microsoft Store, search "WSL"),
:: then run this in the Ubuntu terminal:
curl -fsSL https://claude.ai/install.sh | bash

:: Option B (quick): use npm with Node.js
npm install -g @anthropic-ai/claude-code

Verify: run claude --version — a version number means success ✅

Step 2: Get Your API Key

1. Log in to the AICraft Console
2. Find the "API Key" card → click "Create"
3. Copy the generated key — it starts with sk- followed by 40 hex characters

Step 3: Configure settings.json

Used the one-click script? It wrote the config for you — skip this step, go to Step 4.
Manual install? Find (or create) the config file:

If the .claude folder doesn't exist, create it first:

Copymkdir -p ~/.claude && touch ~/.claude/settings.json

CopyNew-Item -ItemType Directory -Force -Path "$HOME\.claude" | Out-Null
New-Item -ItemType File -Force -Path "$HOME\.claude\settings.json" | Out-Null

Paste this, replacing YOUR_API_KEY with your real key:

Copy{
  "env": {
    "ANTHROPIC_BASE_URL": "https://aicraftapi.net",
    "ANTHROPIC_AUTH_TOKEN": "YOUR_API_KEY",
    "ANTHROPIC_MODEL": "auto",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "auto",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "auto",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "auto",
    "CLAUDE_CODE_SUBAGENT_MODEL": "auto"
  }
}

Step 4: Verify the Connection

1. Open a new terminal and cd to your project:

   cd your-project
   claude

2. After startup, type /status and check:

3. Ask: "Hi, introduce yourself." → a reply means everything works ✅

Step 5: Use It With VS Code (Vibe Coding)

1. In VS Code: File → Open Folder → select your project
2. Press Ctrl+` to open the built-in terminal
3. Type claude and press Enter
4. Let Claude edit code — changes appear live in the editor

Step 6: Enable Deep Reasoning (Optional)

Type /config in Claude Code → set Thinking mode to true → quit and re-enter.

Troubleshooting

Does Web Search work?

Yes. AICraft doesn't block native search. For MCP search: Tencent Cloud MCP Marketplace.

Which model does "auto" pick?

Router picks per task: DeepSeek for coding, Qwen for Chinese, MiniMax for creative. Check the X-AICraft-Routed-To header. See Auto Router.

④ Codewhale (Terminal AI Coding Assistant)

Codewhale is an open-source terminal coding assistant that works with any OpenAI-compatible API. If you already use AICraft, add the config below and it will call our models.

Step 1: Install Codewhale

macOS / Linux:

Copycurl -fsSL https://codewhale.net/install.sh | sh

Windows: download the installer from GitHub Releases. Already installed? Upgrade with codewhale update.

Step 2: Write the Config

Edit ~/.codewhale/config.toml (on Windows, %USERPROFILE%\.codewhale\config.toml) and add:

Copyprovider = "aicraft"

[providers.aicraft]
kind = "openai-compatible"
base_url = "https://aicraftapi.net/v1"
api_key = "sk-YOUR_KEY"
model = "claude-4.5-sonnet"

Step 3: Start Using It

From your project directory run codewhale, choose aicraft under /provider and a model under /model, then describe the task.

Model IDs come from the Model Catalog and can be pasted into the config as-is.

⑤ Switch Providers With CC Switch (Windows / Mac GUI)

CC Switch is a free, open-source provider switcher for Claude Code. It writes ~/.claude/settings.json for you through a GUI, so you can flip between providers with one click instead of editing config by hand. Use it or the manual settings.json route above — not both.

1. Install: search GitHub for farion1231/claude-code-switch, or grab the Windows / Mac installer from its website (a CC Switch icon appears on your desktop).
2. Open CC Switch → "Add Provider" and fill in:

⑥ Skills Pack (Optional)

140 AI development skills covering coding, testing, deployment, security, and docs. Import into Claude Code for direct use.

Install

Extract to Claude Code's skills directory:

Copy# 1. Download and extract
unzip aicraft-skills.zip -d ~/.claude/skills/

# 2. Verify
ls ~/.claude/skills/
# You should see 140 skill directories (python / fastapi / code-review ...)

Copy:: 1. Download aicraft-skills.zip
:: 2. Extract to %USERPROFILE%\.claude\skills (right-click zip → Extract to .claude\skills)

:: 3. Verify with PowerShell
dir $env:USERPROFILE\.claude\skills\

Usage

Type /skill-name in Claude Code to invoke a skill. Examples:

Copy/python-patterns         # Python design pattern guidance
/code-review             # Review current code
/test-driven-development # TDD workflow
/deployment-strategies   # Deployment advice
/security                # Security review
/api-design              # API design best practices

API Reference

Chat Completions

OpenAI-compatible chat completions endpoint.

Parameters

Response

Copy{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1720000000,
  "model": "deepseek/deepseek-v4-pro",
  "choices": [{
    "message": { "role": "assistant", "content": "Hello! How can I help?" },
    "finish_reason": "stop"
  }],
  "usage": { "prompt_tokens": 10, "completion_tokens": 8, "total_tokens": 18 }
}

Streaming (SSE)

Set "stream": true:

Copydata: {"choices":[{"delta":{"content":"Hello"}}]}

data: {"choices":[{"delta":{"content":" world"}}]}

data: {"choices":[{"finish_reason":"stop"}]}

data: [DONE]

Each chunk is data: {json}. Ends with data: [DONE]. OpenAI SDK handles this.

Jev Native Endpoints

Three models are served over their native protocol instead of chat messages: typesafe/jev-1.13, typesafe/jev-1.14 and microsoft/microsoft-decision-1. Send one POST to one of the two endpoints below and you get structured answers back. "model": "jev-latest" resolves to the newest version currently on sale.

Question types

SystemOne

Score or classify a single state against one or more named questions.

Parameters

Example

Copycurl https://aicraftapi.net/v1/systemone \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "typesafe/jev-1.14",
    "state": "今天天气不错",
    "questions": {
      "is_zh": { "type": "noul", "instructions": "这段是中文吗？" }
    }
  }'

Copy{
  "model": "typesafe/jev-1.14",
  "answers": {
    "is_zh": { "type": "noul", "noul": 0.99 }
  },
  "usage": { "input_tokens": 280, "output_tokens": 22, "total_tokens": 302 },
  "id": "jev-9f1c2b7e4a6d8c0e"
}

Decisions

Run one or more decisions over a single input and get an ordered array of answers.

Parameters

Example

Copycurl https://aicraftapi.net/v1/decisions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "microsoft/microsoft-decision-1",
    "input": "今天天气不错",
    "questions": [
      { "type": "predicate", "name": "is_zh", "instructions": "中文吗？" }
    ]
  }'

Copy{
  "model": "microsoft/microsoft-decision-1",
  "answers": [
    { "type": "predicate", "name": "is_zh", "probability": 0.99 }
  ],
  "usage": { "input_tokens": 280, "output_tokens": 21, "total_tokens": 301 },
  "id": "jev-4c8d1e6f9b2a7350"
}

Model List

List available models. Full catalog: Model Catalog.

Copycurl https://aicraftapi.net/v1/models -H "Authorization: Bearer YOUR_API_KEY"

Auto Router v6

model: "auto" activates the core routing engine.

12 Routing Categories

Response Headers

v6 Smart Features

• Lock Decay — 7 days idle → auto-unlock model preference
• Drift Detection — Task type shift > 40% → auto-unlock
• Fault Self-Healing — failed models bypassed within 1h
• Community Cold Start — new users learn from community
• Feedback API — POST /v1/feedback teaches Router preferences

Model Usage & Fallback

Always Use Real Model IDs

Handling Errors

Guides

Response Cache beta

Two-layer caching saves money automatically. Rolling out gradually.

• Hit rate: 35-55% · Capacity: 50k · TTL: 1h · user_id isolated
• Auto-enabled. Skip: X-AICraft-No-Cache: true
• Stats: GET /cache-stats

Rate Limits

Returns 429 when exceeded. See Pricing.

Error Codes

OnlineDebug