Tài liệu API

Tương thích OpenAI SDK & Anthropic Messages API. Hoạt động với Claude Code, Cursor, Cline, Continue, Aider...

> 3 bước để chạy lần đầu

1. Tạo API key tại /dashboard/keys — key bắt đầu bằng vai-. Copy & lưu ngay (coi như mật khẩu).

2. Nếu số dư = 0, nạp tại /dashboard/topup (tài khoản mới được tặng credit dùng thử).

3. Verify key bằng 2 lệnh dưới đây — cả hai trả về JSON là chạy ngon, rồi sang tab tool của bạn.

bash — verify key + base URL

# 1) Liệt kê model — phải trả HTTP 200 + danh sách JSON
curl https://shibiai.dev/api/v1/models \
  -H "Authorization: Bearer vai-your-api-key"

# 2) Smoke test chat — phải trả về 1 câu trả lời
curl https://shibiai.dev/api/v1/chat/completions \
  -H "Authorization: Bearer vai-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"model":"aws/claude-haiku-4-5","messages":[{"role":"user","content":"ping"}]}'

Không có terminal? Dùng /dashboard/playground để chat thử ngay trên web.

> Kết nối

OpenAI Format

(curl, OpenAI SDK, Cursor, Cline OpenAI mode)

https://shibiai.dev/api/v1

Endpoint: /chat/completions

Anthropic Format

(Claude Code, Anthropic SDK, Cline Anthropic mode)

https://shibiai.dev

SDK tự append /v1/messages

API Key: vai-xxxxxxxxxx (tạo ở /dashboard/keys)

Auth header: Authorization: Bearer vai-... hoặc x-api-key: vai-...

> Cài đặt cho IDE / CLI

Chọn công cụ bạn đang dùng để xem cấu hình copy-paste.

Từ số 0 trên Windows — cài & cấu hình A-Z

Hướng dẫn từ số 0 trên Windows: cài công cụ → cài Claude Code → trỏ về gateway ShibiAI. Làm tuần tự từng bước, ~10 phút.

Cài 3 phần mềm nền (bắt buộc)

Tải và cài (next → next → finish), toàn bộ là trang chính thức:

VS Code — code.visualstudio.com/download
Node.js (kèm npm) — nodejs.org → chọn bản LTS
Git for Windows — git-scm.com/downloads/win

⚠️ Phải cài Node.js, không bỏ qua — lệnh ở bước 2 cần npm (đi kèm Node). Cài xong khởi động lại máy (hoặc ít nhất mở lại CMD) để PATH cập nhật.

Cài Claude Code CLI

Mở CMD (gõ cmd ở Start menu) rồi dán lệnh:

cmd

npm install -g @anthropic-ai/claude-code

Kiểm tra cài xong:

cmd

claude --version

Hiện ra số version là OK. Báo 'npm' is not recognized nghĩa là chưa cài Node.js hoặc chưa mở lại CMD — quay lại bước 1.

Cài extension trong VS Code

Mở VS Code → bấm icon Extensions (hoặc Ctrl+Shift+X) → tìm Claude Code for VS Code (publisher Anthropic, có tích xanh) → Install.

Cẩn thận: chọn đúng extension chính chủ Anthropic, đừng cài bản nhái trùng tên.

Cấu hình trỏ về gateway (settings.json)

Mở thư mục cấu hình Claude: vào C:\Users\<tên-user>\.claude\ rồi mở file settings.json bằng Notepad. Chưa có thì tạo mới file tên settings.json (chạy claude một lần để nó tự tạo thư mục .claude).

Dán nội dung sau, thay vai-your-api-key bằng key của bạn (lấy ở /dashboard/keys):

~/.claude/settings.json

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://shibiai.dev",
    "ANTHROPIC_AUTH_TOKEN": "vai-your-api-key",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "aws/claude-opus-4-8-medium",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "aws/claude-sonnet-5-medium",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "aws/claude-haiku-4-5",
    "PYTHONIOENCODING": "utf-8",
    "PYTHONUTF8": "1",
    "LANG": "en_US.UTF-8",
    "LC_ALL": "en_US.UTF-8",
    "CHCP": "65001"
  },
  "permissions": {
    "allow": ["Bash(*)"]
  },
  "model": "aws/claude-opus-4-8-medium"
}

⚠️ ANTHROPIC_BASE_URL để trần https://shibiai.dev — KHÔNG thêm /v1 hay /api/v1. Anthropic SDK tự append /v1/messages.

⚠️ Model id nên có prefix aws/ kèm tier (vd aws/claude-opus-4-8-medium). Tên trần claude-sonnet-4-6 bị tắt → lỗi invalid_model. (Claude Code gửi tên trần vẫn được vì gateway tự map.)

⚠️ "permissions": { "allow": ["Bash(*)"] } cho Claude chạy mọi lệnh terminal không hỏi lại — tiện khi vọc, bỏ đi nếu muốn xác nhận từng lệnh.

Chạy thử

Trong VS Code, mở terminal (Ctrl + `) hoặc panel Claude Code, gõ claude để bắt đầu. Hỏi thử một câu để xác nhận model trả lời.

Lỗi 401 → sai key; invalid_model → còn sót model thiếu aws/; không gọi được → kiểm tra base URL đúng https://shibiai.dev.

> Quick Start (raw)

Nếu bạn tự code thay vì dùng IDE, đây là 3 cách phổ biến nhất.

curl

curl https://shibiai.dev/api/v1/chat/completions \
  -H "Authorization: Bearer vai-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"model":"aws/claude-sonnet-5-medium","messages":[{"role":"user","content":"Hello!"}],"stream":true}'

python (openai sdk)

from openai import OpenAI

client = OpenAI(
    api_key="vai-your-api-key",
    base_url="https://shibiai.dev/api/v1"
)

response = client.chat.completions.create(
    model="aws/claude-sonnet-5-medium",
    messages=[{"role": "user", "content": "Hello!"}],
    stream=True
)
for chunk in response:
    print(chunk.choices[0].delta.content or "", end="")

typescript (anthropic sdk)

import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic({
  apiKey: "vai-your-api-key",
  baseURL: "https://shibiai.dev",   // ← Anthropic SDK auto-appends /v1/messages
});

const msg = await client.messages.create({
  model: "aws/claude-sonnet-5-medium",
  max_tokens: 1024,
  messages: [{ role: "user", content: "Hello!" }],
});
console.log(msg.content);

> Models

⚠️ Model Claude (Opus / Sonnet) phải kèm effort tier: -low / -medium / -high / -xhigh / -max (vd aws/claude-opus-4-8-high). Thêm hậu tố -thinking để bật extended thinking. Gửi id trần không tier (vd aws/claude-opus-4-8) sẽ lỗi invalid_model. Haiku / MiniMax / GLM / Qwen không có tier — dùng thẳng.

ID	CTX	IN $/M	OUT $/M	Ghi chú
aws/claude-opus-4-8-medium	1M	$6.00	$30.00	Mạnh nhất — agent, reasoning sâu
aws/claude-opus-4-7-medium	1M	$6.00	$30.00	Opus 4.7
aws/claude-opus-4-6-medium	1M	$5.00	$25.00	Opus 4.6
aws/claude-sonnet-5-medium	1M	$2.00	$10.00	Tốt nhất cho code (giá tốt)
aws/claude-sonnet-4-6-medium	1M	$3.00	$15.00	Sonnet 4.6
aws/claude-haiku-4-5	200K	$1.00	$5.00	Nhanh & rẻ (không cần tier)
aws/glm-5	200K	$1.00	$5.00	Reasoning + agentic
aws/minimax-m2.5	200K	$0.50	$2.00	Agentic coding
aws/qwen3-codex	256K	$0.10	$0.50	Budget code

Đây là các model tiêu biểu. Danh sách + giá đầy đủ realtime tại /dashboard/models hoặc gọi GET /api/v1/models.

> Endpoints

POST/api/v1/chat/completions— OpenAI format (stream + non-stream, tools, vision)

POST/api/v1/messages— Anthropic Messages API (Claude Code dùng cái này)

GET/api/v1/models— Liệt kê model + giá

> Prompt Caching

Tất cả model Claude hỗ trợ cache_control: { type: "ephemeral" } theo chuẩn Anthropic.

Khi cache hit, gateway giảm ~47% giá input cho phần cache_read (multiplier 0.53). Cache_write tính theo giá gốc +25% (multiplier 1.25).

Claude Code & Cline tự động dùng caching cho system prompt + tools — không cần config thêm.

> Xử lý lỗi thường gặp

401 Unauthorized — sai key, thiếu chữ Bearer trước key, hoặc key đã bị xoá/đổi. Tạo lại tại /dashboard/keys.

invalid_model / 404 — sai tên model. Với Opus/Sonnet nhớ kèm tier (-medium…). Copy đúng id từ bảng Models hoặc GET /api/v1/models.

402 / hết số dư — nạp thêm tại /dashboard/topup.

Connection refused / timeout — base URL sai. OpenAI format phải có /api/v1; Anthropic format để trần https://shibiai.dev (SDK tự thêm /v1/messages).

> Thanh toán

• Pay-as-you-go: trừ theo token thực tế từ usage upstream

• Tài khoản mới được tặng credit dùng thử

• Nạp tối thiểu 100.000đ · thanh toán qua VietQR

• Cộng credit tự động qua webhook SePay sau khi chuyển khoản

• Tỷ giá & bảng giá chi tiết xem tại /pricing và /dashboard/topup