// 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ụ.

Cách nhanh nhất: dán một prompt

Bạn đã có sẵn một AI agent — đó là lý do bạn mua khoá. Hãy để nó tự cấu hình: chọn công cụ bên dưới, bấm copy, thay khoá của bạn vào, rồi dán vào agent nào sửa được file và chạy được lệnh (Claude Code, Codex, Cline…). Agent sẽ tự sửa file cấu hình và tự chạy lệnh kiểm chứng.

Claude Code (CLI)
You are configuring Claude Code to use MotAPI (motapis.com) as its API endpoint.

Use these EXACT values. Do not invent alternatives and do not use any other host:
  ANTHROPIC_BASE_URL   = https://motapis.com          (no /v1 -- the SDK appends it)
  ANTHROPIC_AUTH_TOKEN = sk-mot-THAY_BANG_KHOA_CUA_BAN
  ANTHROPIC_API_KEY    = ""                            (empty string, see step 3)
  model                = claude-opus-4-8

Steps:
1. If ~/.claude/settings.json exists, copy it to ~/.claude/settings.json.bak first.
   Show me the diff before you write anything.
2. Create or merge ~/.claude/settings.json so it has an "env" object containing the three
   values above. Keep every other key already in that file exactly as it is.
3. ANTHROPIC_API_KEY must be PRESENT and set to the empty string "" -- not omitted. If it
   is merely absent, Claude Code falls back to authenticating against real Anthropic
   whenever this machine has a real Anthropic key in its environment, and the requests go
   to the wrong provider without any error.
4. Verify: run  claude --print "reply with exactly: pong"  and show me the output.

IMPORTANT
- Never print, echo, or commit the API key, and never write it into a file inside a git
  repository.
- Do not modify any other provider, profile, or key in that file.
- If a step fails, stop and tell me. Do not try a different host or a different auth method.
Codex CLI
You are configuring OpenAI Codex CLI to use MotAPI (motapis.com).

Use these EXACT values:
  provider id = motapis                      (no hyphen -- Codex fails to resolve provider
                                              ids that contain "-")
  base_url    = https://motapis.com/v1
  env var     = MOTAPIS_API_KEY
  model       = gpt-5.6-terra                (Claude works too, e.g. claude-sonnet-5)

Steps:
1. Back up ~/.codex/config.toml if it exists. Show me the diff before you write.
2. If that file contains a block marked "BEGIN codex-router-provider-managed", STOP and
   tell me. codex-router rewrites that block and sets requires_openai_auth = true, which
   makes Codex send OpenAI credentials instead of the MotAPI key -- the request then never
   reaches MotAPI and fails with 401 api_key_not_supported. Either disable codex-router
   first, or keep using it and pick a custom/motapis-* model inside it instead.
3. Add or update this block, keeping every other setting in the file unchanged:

model_provider = "motapis"
model = "gpt-5.6-terra"

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

4. Do NOT add a wire_api line. Current Codex removed wire_api = "chat" entirely and
   defaults to the Responses API, which is what MotAPI serves.
5. Ask me which shell profile to use, then export MOTAPIS_API_KEY=sk-mot-THAY_BANG_KHOA_CUA_BAN there.
6. Verify: run  codex doctor  and show me the output. It should say "config loaded" and
   print the model line; if the key is missing it states that explicitly.

CLAUDE MODELS WORK HERE TOO (since 26/09/2026): claude-sonnet-5, claude-opus-4-8,
claude-opus-5-5 and the other claude-* models run in Codex over the Responses API.
Other working models on this path include gpt-5.6-terra, gpt-6-astra, gpt-5.3-codex,
grok-4.6, glm-5.3, gemini-3.1-pro-preview, deepseek-v4-pro and qwen3.8-max.

Expected, not an error: Codex prints "Model metadata for ... not found" every session,
because it only knows OpenAI's own model catalogue. It still works.

IMPORTANT
- Never print, echo, or commit the API key.
- Do not change any other model provider already in config.toml.
OpenCode CLI
You are configuring OpenCode CLI to use MotAPI (motapis.com).

Use these EXACT values:
  provider id = motapis
  baseURL     = https://motapis.com/v1
  model       = claude-opus-4-8

Steps:
1. Back up opencode.json if it already exists. Show me the diff before you write.
2. Create or merge opencode.json (project folder, or the global config) so it contains:

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

   Keep every other provider already in the file unchanged.
3. Do NOT put the raw key in this file. Tell me to run /connect inside OpenCode and pick
   the "motapis" provider -- that is where the key is stored.
4. Verify: start opencode and check that motapis/claude-opus-4-8 appears in the model list.

IMPORTANT
- Never print, echo, or commit the API key.
- The provider id in opencode.json must match the one you select in /connect exactly.
Continue.dev
You are configuring the Continue extension to use MotAPI (motapis.com).

Use these EXACT values:
  provider = openai            (OpenAI-compatible, not "anthropic")
  apiBase  = https://motapis.com/v1
  apiKey   = sk-mot-THAY_BANG_KHOA_CUA_BAN
  model    = claude-opus-4-8

Steps:
1. Find Continue's config file. It is usually ~/.continue/config.yaml -- if it is not
   there, check the path shown in Continue's own settings before creating a new one.
2. Back it up, then show me the diff before you write.
3. Append this model, keeping every model already listed:

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

4. Verify: open the model picker in Continue -- the new model must appear in the list.

IMPORTANT
- Never print, echo, or commit the API key, and keep this file out of any git repository.
- Do not remove or edit any model or provider that is already configured.
Lưu ý: Prompt sẽ yêu cầu agent cho bạn xem diff TRƯỚC khi ghi, và sao lưu file cũ. Hãy đọc diff rồi mới duyệt — thói quen tốt với mọi thứ tải từ Internet.

Cursor và Cline không có prompt, cố ý: Cursor chỉ cấu hình được qua Settings, còn Cline lưu trong state nội bộ của VS Code — để agent sửa mấy chỗ đó dễ hỏng hơn là được việc. Hai công cụ này dùng hướng dẫn thủ công bên dưới.

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

Trong VS Code, chọn API provider OpenAI Compatible. Không cần cài thêm gì — cài extension Cline 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 — 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 = "gpt-5.6-terra"

[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.
  • Codex in cảnh báo Model metadata … not found ở mỗi phiên — bình thường: Codex chỉ biết danh mục model của OpenAI nên không nhận ra model của MộtAPI, và nó vẫn chạy đúng. Nếu thấy hội thoại bị nén sớm, thêm model_context_window = TOKENS (điền đúng giới hạn của model bạn dùng) vào đầu ~/.codex/config.toml.

Kiểm tra: chạy codex doctor — mất khoảng 1 giây và chỉ thẳng chỗ sai (thiếu biến môi trường, sai tên model, hay config không nạp được).

→ 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 gpt-5.6-terra
# 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, 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.