// TÀI LIỆU API · v1

AI API, một endpoint
cho mọi model.

MộtAPI là gateway tương thích OpenAI và Anthropic. Dùng một API key, truy cập 57 model và chỉ trả tiền cho số token thực tế.

// 01 · QUICKSTART

Bắt đầu nhanh

Gửi request đầu tiên tới endpoint tương thích OpenAI bằng API key được tạo trong dashboard.

curl https://motapis.com/v1/chat/completions \
  -H "Authorization: Bearer sk-mot-..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-opus-4-8",
    "messages": [
      {"role": "user", "content": "Xin chào, MộtAPI!"}
    ]
  }'

Response trả về theo format Chat Completions: nội dung nằm trong choices[0].message.content, cùng thông tin model và usage.

{
  "id": "chatcmpl-mot-...",
  "object": "chat.completion",
  "model": "claude-opus-4-8",
  "choices": [{
    "index": 0,
    "message": {"role": "assistant", "content": "Xin chào!"},
    "finish_reason": "stop"
  }],
  "usage": {"prompt_tokens": 12, "completion_tokens": 8, "total_tokens": 20}
}

// 02 · AUTHENTICATION

Xác thực

Mọi request cần header Bearer với khoá có định dạng sk-mot-.... Khoá được tạo trong dashboard tại /dashboard.html, mục Khoá API.

Authorization: Bearer sk-mot-...

Bảo mật: Không chia sẻ API key, không commit key vào Git và không đưa key vào mã frontend chạy trên trình duyệt. Dùng biến môi trường ở phía server.

// 03 · ENDPOINTS

Endpoints

POST/v1/chat/completions

API kiểu OpenAI cho hội thoại. Hỗ trợ response thường và streaming SSE với "stream": true.

POST https://motapis.com/v1/chat/completions
Content-Type: application/json
Authorization: Bearer sk-mot-...

{
  "model": "claude-opus-4-8",
  "messages": [
    {"role": "system", "content": "Bạn là trợ lý hữu ích."},
    {"role": "user", "content": "Tóm tắt nội dung này."}
  ],
  "temperature": 0.7,
  "stream": false
}

{
  "id": "chatcmpl-mot-...",
  "object": "chat.completion",
  "choices": [{
    "message": {"role": "assistant", "content": "Nội dung tóm tắt..."},
    "finish_reason": "stop"
  }],
  "usage": {"prompt_tokens": 42, "completion_tokens": 18, "total_tokens": 60}
}

POST/v1/messages

API kiểu Anthropic Messages, phù hợp với Anthropic SDK và các công cụ dùng giao thức Anthropic.

POST https://motapis.com/v1/messages
Content-Type: application/json
x-api-key: sk-mot-...
anthropic-version: 2023-06-01

{
  "model": "claude-opus-4-8",
  "max_tokens": 1024,
  "messages": [
    {"role": "user", "content": "Viết một câu chào bằng tiếng Việt."}
  ]
}

GET/v1/models

Liệt kê các model khả dụng cùng thông tin định danh.

curl https://motapis.com/v1/models \
  -H "Authorization: Bearer sk-mot-..."

// 04 · SDK

SDK & thư viện

Python · OpenAI SDK

from openai import OpenAI

client = OpenAI(
    base_url="https://motapis.com/v1",
    api_key="sk-mot-..."
)

response = client.chat.completions.create(
    model="claude-opus-4-8",
    messages=[
        {"role": "user", "content": "Xin chào, MộtAPI!"}
    ]
)

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

Node.js · OpenAI SDK

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://motapis.com/v1",
  apiKey: "sk-mot-..."
});

const response = await client.chat.completions.create({
  model: "claude-opus-4-8",
  messages: [{ role: "user", content: "Xin chào, MộtAPI!" }]
});

console.log(response.choices[0].message.content);

Anthropic Python SDK

from anthropic import Anthropic

client = Anthropic(
    base_url="https://motapis.com",
    api_key="sk-mot-..."
)

message = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=1024,
    messages=[
        {"role": "user", "content": "Xin chào, MộtAPI!"}
    ]
)

print(message.content[0].text)

curl · streaming

curl https://motapis.com/v1/chat/completions \
  -H "Authorization: Bearer sk-mot-..." \
  -H "Content-Type: application/json" \
  -d '{"model":"claude-opus-4-8","messages":[{"role":"user","content":"Hello"}],"stream":true}'

// 05 · TOOL CONFIGURATION

Cài đặt cho công cụ

Claude Code, Codex CLI và OpenCode CLI có thể cấu hình tự động bằng script setup-cli bên dưới — hoặc làm thủ công theo hướng dẫn từng công cụ.

Cursor

Chọn provider OpenAI-compatible trong phần cài đặt model. Không cần cài thêm gì — Cursor đã có sẵn.

Override Base URL:
https://motapis.com/v1

API Key:
sk-mot-...

Model:
claude-opus-4-8
# hoặc gpt-5.6, glm-5.2…

Bật "Override OpenAI Base URL" — nếu không, Cursor bỏ qua Base URL đã nhập.
Model phải gõ đúng tên trong bảng model, không dùng tên rút gọn của Cursor.

Kiểm tra: mở chat, hỏi thử một câu — nếu ra lỗi 401 thì key sai, lỗi model-not-found thì tên model sai.

Claude Code (CLI)

Cài đặt: curl -fsSL https://claude.ai/install.sh | bash

Đặt biến môi trường trước khi chạy CLI, hoặc lưu vào file cấu hình dự án.

export ANTHROPIC_BASE_URL=https://motapis.com
export ANTHROPIC_AUTH_TOKEN=sk-mot-...
export ANTHROPIC_API_KEY=""

claude

Hoặc lưu vào ~/.claude/settings.json (áp dụng mọi project) hay .claude/settings.local.json (chỉ project hiện tại):

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://motapis.com",
    "ANTHROPIC_AUTH_TOKEN": "sk-mot-...",
    "ANTHROPIC_API_KEY": ""
  }
}

ANTHROPIC_API_KEY phải đặt thành chuỗi rỗng "" — để trống hẳn (không set) sẽ khiến Claude Code cố xác thực thẳng với Anthropic nếu máy từng có key Anthropic thật.
Nếu trước đó từng chạy claude login, gõ /logout trong Claude Code rồi khởi động lại — phiên đăng nhập Anthropic cũ được cache riêng, không tự mất khi đổi biến môi trường.
Khởi động lại terminal (hoặc mở terminal mới) sau khi đổi biến môi trường hoặc file cấu hình.

Kiểm tra: trong Claude Code, gõ /status — phải thấy Base URL là https://motapis.com.

→ Dùng script setup-cli để tự động hoá bước này

Cline / Roo Code

Trong VS Code, chọn API provider OpenAI Compatible. Không cần cài thêm gì — cài extension Cline/Roo Code như bình thường.

API Provider:
OpenAI Compatible

Base URL:
https://motapis.com/v1

API Key:
sk-mot-...

Model ID:
claude-opus-4-8

Sau khi đổi cấu hình, reload lại cửa sổ VS Code (Developer: Reload Window) nếu extension chưa nhận cấu hình mới.

Kiểm tra: gửi một task nhỏ trong Cline/Roo — usage hiển thị đúng model đã chọn.

Continue.dev

Thêm model vào file cấu hình Continue. Không cần cài thêm gì — cài extension Continue như bình thường.

models:
  - name: claude-opus-4-8
    provider: openai
    apiBase: https://motapis.com/v1
    apiKey: sk-mot-...
    model: claude-opus-4-8

File cấu hình thường ở ~/.continue/config.yaml — kiểm tra đường dẫn thật trong phần cài đặt Continue nếu không thấy model mới.

Kiểm tra: mở model picker trong Continue — model vừa thêm phải xuất hiện trong danh sách.

Codex CLI

Cài đặt: npm install -g @openai/codex

Sửa ~/.codex/config.toml, thêm provider MộtAPI:

model_provider = "motapis"
model = "claude-opus-4-8"

[model_providers.motapis]
name = "motapis"
base_url = "https://motapis.com/v1"
requires_openai_auth = false
env_key = "MOTAPIS_API_KEY"

export MOTAPIS_API_KEY=sk-mot-...

codex

Gói npm đúng tên là @openai/codex (có scope) — gói codex không scope là một project cũ không liên quan, cài nhầm sẽ không chạy được gì.
Model phải gõ đúng tên trong bảng model (vd claude-opus-4-8), không dùng cú pháp alias ~vendor/model của OpenRouter.
Nếu Codex báo lỗi liên quan wire_api: schema này đã đổi giữa các bản Codex CLI — thử thêm dòng wire_api = "responses" hoặc wire_api = "chat" vào khối provider, tuỳ bản đang cài.

Kiểm tra: chạy codex, gửi thử một câu hỏi — nếu báo "Unknown model" thì kiểm tra lại tên model.

→ Dùng script setup-cli để tự động hoá bước này

OpenCode CLI

Cài đặt: curl -fsSL https://opencode.ai/install | bash

Thêm provider vào opencode.json (thư mục project hoặc global):

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "motapis": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "MộtAPI",
      "options": {
        "baseURL": "https://motapis.com/v1",
        "apiKey": "{env:MOTAPIS_API_KEY}"
      },
      "models": {
        "claude-opus-4-8": { "name": "Claude Opus 4.8" }
      }
    }
  }
}

Sau đó lưu API key qua lệnh /connect ngay trong OpenCode (chọn provider motapis) — file cấu hình ở trên chỉ khai báo provider, chưa lưu key.

ID provider trong opencode.json (motapis) phải khớp chính xác với provider chọn ở bước /connect.
Đúng gói SDK là @ai-sdk/openai-compatible — sai tên gói khiến OpenCode không load được provider.

Kiểm tra: trong OpenCode, gõ /models — provider MộtAPI và model vừa thêm phải xuất hiện.

→ Dùng script setup-cli để tự động hoá bước này

Script setup-cli (Claude Code / Codex / OpenCode)

Script chỉ ghi file cấu hình cho công cụ đã cài sẵn — không tự cài Claude Code, Codex hay OpenCode, không sửa file khởi động shell, không cần quyền root. File cấu hình cũ được sao lưu trước khi ghi đè.

curl -fsSL https://motapis.com/motapis_cli_setup.py -o /tmp/motapis_cli_setup.py
python3 /tmp/motapis_cli_setup.py --tool claude-code
# hoặc --tool codex --model claude-opus-4-8
# hoặc --tool opencode --model claude-opus-4-8

Script hỏi API key khi chạy (không hiện lại trên màn hình) — hoặc đặt sẵn biến môi trường MOTAPIS_API_KEY trước khi chạy nếu dùng trong script tự động khác.

An toàn: nên tải script về rồi đọc qua trước khi chạy — đây là thói quen tốt cho mọi script tải từ Internet, kể cả script của chính MộtAPI.

// 06 · STREAMING

Streaming

Đặt "stream": true để nhận dữ liệu theo thời gian thực qua SSE. Mỗi phần nội dung nằm trong một dòng data:; kết thúc bằng data: [DONE].

curl https://motapis.com/v1/chat/completions \
  -H "Authorization: Bearer sk-mot-..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-opus-4-8",
    "messages": [{"role": "user", "content": "Kể một câu chuyện ngắn."}],
    "stream": true
  }'

from openai import OpenAI

client = OpenAI(
    base_url="https://motapis.com/v1",
    api_key="sk-mot-..."
)

stream = client.chat.completions.create(
    model="claude-opus-4-8",
    messages=[{"role": "user", "content": "Kể một câu chuyện ngắn."}],
    stream=True
)

for chunk in stream:
    text = chunk.choices[0].delta.content
    if text:
        print(text, end="", flush=True)

// 07 · MODEL CATALOG

Bảng model & giá

Giá tính trên 1 triệu token. Với model hình ảnh, giá hiển thị theo ảnh. Ví USD credit được trừ theo token thực tế của từng request.

Model	Nhà cung cấp	Hạng	Giá vào ($/1M token)	Giá ra ($/1M token)
Đang tải danh sách model...

// 08 · BILLING

Giá & thanh toán

Thanh toán theo token thực tế của mỗi request qua ví USD credit. Đây là mô hình trả theo mức sử dụng, không thuê bao và số dư không hết hạn.

Nạp tiền: VietQR, USDT-TRC20 hoặc PayPal trong dashboard tại /dashboard.html.

Số dư được trừ dần theo giá của model và số token input/output thực tế. Kiểm tra bảng model để xem đơn giá hiện tại trước khi triển khai.

// 09 · ERROR HANDLING

Xử lý lỗi

Mã / lỗi	Nguyên nhân	Cách xử lý
401	Sai hoặc thiếu API key	Kiểm tra header `Authorization: Bearer` và tạo key mới trong dashboard.
402	Hết số dư	Nạp thêm tiền vào ví USD credit bằng VietQR, USDT-TRC20 hoặc PayPal.
insufficient balance	Số dư không đủ cho request	Nạp thêm số dư rồi gửi lại request.
429	Quá nhiều request	Chờ một lúc, giảm tốc độ gửi và thêm retry với exponential backoff.
5xx	Lỗi tạm thời phía dịch vụ hoặc upstream	Thử lại request sau một khoảng thời gian; không lặp vô hạn.

// 10 · FAQ

Câu hỏi thường gặp

Base URL của MộtAPI là gì?

Kiểu OpenAI (/v1/chat/completions): https://motapis.com/v1. Kiểu Anthropic (/v1/messages): https://motapis.com — SDK/CLI tự thêm /v1/messages vào sau, không cần gõ /v1 ở cuối.

MộtAPI dùng được với công cụ nào?

Bất kỳ SDK/CLI nào hỗ trợ base_url tuỳ chỉnh kiểu OpenAI hoặc Anthropic — xem hướng dẫn chi tiết Cursor, Claude Code, Cline/Roo Code, Continue.dev, Codex CLI, OpenCode CLI ở mục Cài đặt cho công cụ phía trên.

Vì sao Claude Code vẫn báo lỗi liên quan Anthropic dù đã đổi key?

Thường do ANTHROPIC_API_KEY chưa được đặt thành chuỗi rỗng "" (chỉ để trống/không set là chưa đủ), hoặc Claude Code đang dùng phiên đăng nhập Anthropic cũ — gõ /logout trong Claude Code rồi thử lại. Chi tiết ở mục Claude Code (CLI).

Lỗi 401 hoặc "model not found" phải làm sao?

401 nghĩa là key sai hoặc thiếu header Authorization: Bearer/x-api-key. "Model not found" nghĩa là tên model gõ sai — đối chiếu đúng chính tả với bảng model, MộtAPI dùng tên model thật, không dùng alias kiểu vendor/model.

Streaming có hoạt động không?

Có, với mọi model — đặt "stream": true trong request. Xem ví dụ đầy đủ ở mục Streaming.

Nên chọn model nào?

Tuỳ nhu cầu và ngân sách — xem bảng model & giá để so sánh giá vào/ra của từng model trước khi chọn.

Billing hoạt động ra sao?

Trả theo mức dùng thực tế qua ví USD credit, không thuê bao, số dư không hết hạn. Xem mục Giá & thanh toán.

Codex CLI báo "Unknown model" hoặc cài xong không chạy được?

Kiểm tra đã cài đúng gói @openai/codex (có scope, không phải gói codex trần) và tên model trong config.toml khớp đúng chính tả với bảng model. Chi tiết ở mục Codex CLI.