Tính năng

• 🤖 Chat đa API: hỗ trợ các endpoint tương thích OpenAI Chat Completions, Anthropic Messages và OpenAI Responses
• 🖼️ Tạo nội dung đa phương thức: ngoài chat văn bản, còn hỗ trợ các tác vụ bất đồng bộ tạo hình ảnh và video (text-to-, image-to-, khung đầu/cuối, tài nguyên tham chiếu)
• 🔍 Tra cứu mô hình & tài khoản: liệt kê các mô hình khả dụng, chi tiết mô hình, số dư tài khoản, chi tiết sử dụng/thanh toán và các giao dịch nạp tiền
• 🔑 Khóa được truyền qua header: mỗi lệnh gọi đọc khóa API từ header của yêu cầu, nhờ đó một lần triển khai có thể được nhiều tài khoản dùng chung — máy chủ không bao giờ lưu trữ hay lưu cache bất kỳ khóa nào

Bắt đầu nhanh

Sử dụng trong Claude Code (khuyến nghị). Thêm -s user để đăng ký ở phạm vi người dùng (khả dụng trong tất cả các dự án của bạn).

Bước 1: Thêm kết nối

Sao chépclaude mcp add --transport http basicrouter https://api.basicrouter.ai/mcp \
  --header "X-Basicrouter-Api-Key: <khóa API BasicRouter của bạn>" \
  -s user

Bước 2: Xác minh kết nối

Sao chépclaude mcp list          # sẽ hiển thị ✓ Connected
claude mcp get basicrouter  # sẽ hiển thị Scope: User config (available in all your projects)

Bước 3: Bắt đầu sử dụng

Bạn có thể hỏi Claude những điều như:

• "Dùng BasicRouter để gọi claude-sonnet-5 và viết một bài thơ về mùa thu"
• "Liệt kê các mô hình khả dụng trên tài khoản BasicRouter của tôi"
• "Kiểm tra số dư và mức sử dụng gần đây của tôi trên BasicRouter"
• "Dùng BasicRouter để tạo một hình ảnh thành phố cyberpunk về đêm"

Claude sẽ tự động gọi công cụ MCP phù hợp và trả về kết quả.

Sử dụng với Claude Desktop

Thêm nội dung này vào phần mcpServers:

Sao chép{
  "mcpServers": {
    "basicrouter": {
      "type": "http",
      "url": "https://api.basicrouter.ai/mcp",
      "headers": {
        "X-Basicrouter-Api-Key": "<khóa API BasicRouter của bạn>"
      }
    }
  }
}

Sử dụng với Codex CLI

Khuyến nghị: dùng env_http_headers để đọc khóa từ một biến môi trường

Đầu tiên, khai báo biến môi trường trong shell của bạn:

Sao chépexport BASICROUTER_API_KEY=<khóa API BasicRouter của bạn>

Sau đó trong ~/.codex/config.toml:

Sao chép[mcp_servers.basicrouter]
url = "https://api.basicrouter.ai/mcp"
env_http_headers = { "X-Basicrouter-Api-Key" = "BASICROUTER_API_KEY" }

Cách khác: dùng http_headers để ghi khóa trực tiếp vào cấu hình (tiện lợi nếu bạn không muốn quản lý một biến môi trường riêng, nhưng lưu ý khóa sẽ được lưu ở dạng văn bản thuần trong tệp cấu hình):

Sao chép[mcp_servers.basicrouter]
url = "https://api.basicrouter.ai/mcp"
http_headers = { "X-Basicrouter-Api-Key" = "<khóa API BasicRouter của bạn>" }

Nếu thêm thông qua giao diện cài đặt của Codex:

• Loại: HTTP / Streamable HTTP
• Tên: basicrouter
• URL: https://api.basicrouter.ai/mcp
• Tên header: X-Basicrouter-Api-Key
• Giá trị header: khóa API BasicRouter của bạn

Xác minh kết nối

Sau khi khởi động Codex CLI, lệnh /mcp sẽ liệt kê các máy chủ MCP đã cấu hình cùng trạng thái kết nối của chúng — chỉ cần xác nhận nó đã được tải đúng cách. Cách sử dụng giống với Claude: Codex sẽ tự động chọn công cụ phù hợp.

Nếu tệp cấu hình của bạn đã có các máy chủ MCP khác, hãy thêm máy chủ này vào cùng cấp. Đóng hoàn toàn và mở lại Claude Desktop sau khi chỉnh sửa.

Công cụ

Máy chủ MCP này cung cấp 14 công cụ, được chia thành năm nhóm:

1. Hội thoại

1. chat_completion — Chat Completions

Gửi một yêu cầu hội thoại và trả về phản hồi đầy đủ của mô hình (không stream). Ngoài văn bản, còn nhận ảnh để hiểu thị giác (mô hình phải hỗ trợ vision) — đổi content của tin nhắn từ chuỗi sang mảng khối nội dung trộn text và image_url.

Đầu vào đa phương thức (text / image / video)

Nhập ảnh (URL):

Sao chép{"role": "user", "content": [
  {"type": "text", "text": "Trong ảnh này có gì?"},
  {"type": "image_url", "image_url": {"url": "https://example.com/image.jpg"}}
]}

Nhập ảnh (Base64):

Sao chép{"type": "image_url", "image_url": {"url": "data:image/jpeg;base64,<BASE64_STRING>"}}

Định dạng hỗ trợ: PNG, JPEG, GIF (chỉ khung đầu), WebP. Giới hạn kích thước ảnh đơn 20MB.

Lưu ý: ảnh lớn mã hóa Base64 tạo ra chuỗi rất dài, có thể thất bại do phần thân yêu cầu quá lớn; ưu tiên truyền ảnh bằng URL.

Tham số detail (tùy chọn, đặt trên object image_url) điều khiển độ chính xác xử lý ảnh: "auto" (mặc định — mô hình tự quyết theo kích thước) / "low" (thumbnail 512x512, nhanh và rẻ, tốt cho phân loại đơn giản) / "high" (độ phân giải đầy đủ, tốt cho chữ nhỏ / chi tiết). Mảng content của một tin nhắn có thể chứa nhiều khối image_url để truyền nhiều ảnh.

Nhập video (URL):

Sao chép{"role": "user", "content": [
  {"type": "text", "text": "Mô tả những gì xảy ra trong video này."},
  {"type": "video_url", "video_url": {"url": "https://example.com/video.mp4"}}
]}

Nhập video (Base64):

Sao chép{"type": "video_url", "video_url": {"url": "data:video/mp4;base64,<BASE64_STRING>"}}

Các mô hình hỗ trợ đầu vào video trên BasicRouter bao gồm một số mô hình thuộc dòng Qwen, Doubao (dola-seed), Kimi, MiniMax — kiểm tra input_modalities trả về bởi list_models. Tiêu chuẩn Chat Completions chính thức của OpenAI không hỗ trợ video native, nhưng gateway BasicRouter hỗ trợ qua định dạng mở rộng:

Sao chép{"type": "video_url", "video_url": {"url": "..."}}

Định dạng này nhất quán với định dạng video_url được sử dụng bởi OpenRouter, NVIDIA NIM, vLLM và các nền tảng khác.

2. create_message — Tương thích Anthropic Messages

Gọi endpoint tương thích Anthropic Messages (không stream). Khối nội dung hỗ trợ text, image, tool_use, tool_result, thinking, redacted_thinking. Ảnh được truyền qua khối nội dung:

Sao chép{"type": "image", "source": {...}}

Đầu vào đa phương thức (text / image / video)

Nhập ảnh hỗ trợ ba kiểu source:

1. Mã hóa Base64 (lưu ý: trường data là chuỗi Base64 thuần, không có tiền tố data:); media_type hỗ trợ image/jpeg, image/png, image/gif, image/webp:

Sao chép{"type": "image", "source": {
  "type": "base64",
  "media_type": "image/jpeg",
  "data": "<BASE64_STRING>"
}}

2. Tham chiếu URL:

Sao chép{"type": "image", "source": {
  "type": "url",
  "url": "https://example.com/image.jpg"
}}

3. File ID (trước tiên tải ảnh lên qua Files API với purpose="vision" để lấy file_id):

Sao chép{"type": "image", "source": {
  "type": "file",
  "file_id": "<file_id>"
}}

Mảng content của một tin nhắn có thể chứa nhiều khối image để truyền nhiều ảnh.

Lưu ý: ảnh lớn mã hóa Base64 tạo ra chuỗi rất dài, có thể thất bại do phần thân yêu cầu quá lớn; ưu tiên truyền ảnh bằng URL.

Nhập video: API Anthropic Messages không hỗ trợ tệp video gốc. Để hiểu video, trước tiên trích khung chính bằng ffmpeg hoặc tương tự, rồi truyền mỗi khung làm khối nội dung image. Đối với các mô hình hỗ trợ đầu vào video trên BasicRouter (kiểm tra input_modalities trả về bởi list_models), hãy dùng giao diện chat_completion hoặc create_response để hỗ trợ video gốc.

3. create_response — Tương thích OpenAI Responses

Dùng input thay cho messages, instructions thay cho tin nhắn hệ thống, và text.format thay cho response_format. Ngoài văn bản, còn nhận ảnh để hiểu thị giác (mô hình phải hỗ trợ vision) — đặt input thành mảng object tin nhắn mà content là mảng khối nội dung trộn văn bản và ảnh.

Đầu vào đa phương thức (text / image / video)

Lưu ý: Responses API dùng kiểu khối nội dung input_text / input_image / input_video (không phải text / image_url / video_url của Chat Completions), và image_url / video_url là chuỗi trực tiếp, không phải object lồng nhau.

Nhập ảnh (URL):

Sao chép[{"role": "user", "content": [
  {"type": "input_text", "text": "Trong ảnh này có gì?"},
  {"type": "input_image", "image_url": "https://example.com/image.jpg"}
]}]

Nhập ảnh (Base64):

Sao chép{"type": "input_image", "image_url": "data:image/jpeg;base64,<BASE64_STRING>"}

Định dạng hỗ trợ: PNG, JPEG, GIF (chỉ khung đầu), WebP. Giới hạn kích thước ảnh đơn 20MB.

Lưu ý: ảnh lớn mã hóa Base64 tạo ra chuỗi rất dài, có thể thất bại do phần thân yêu cầu quá lớn; ưu tiên truyền ảnh bằng URL.

Nhập ảnh (File ID):

Sao chép{"type": "input_image", "file_id": "<file_id>"}

file_id lấy được bằng cách tải ảnh lên qua Files API với purpose="vision".

Tham số detail (tùy chọn, trên object input_image) điều khiển độ chính xác xử lý: "auto" (mặc định) / "low" (thumbnail 512x512, nhanh và rẻ) / "high" (độ phân giải đầy đủ, cho chữ nhỏ / chi tiết) / "original" (độ phân giải gốc). Mảng content của một tin nhắn có thể chứa nhiều khối input_image cho nhiều ảnh.

Nhập video (URL):

Sao chép[{"role": "user", "content": [
  {"type": "input_text", "text": "Mô tả những gì xảy ra trong video này."},
  {"type": "input_video", "video_url": "https://example.com/video.mp4"}
]}]

Nhập video (Base64):

Sao chép{"type": "input_video", "video_url": "data:video/mp4;base64,<BASE64_STRING>"}

Nhập video (File ID):

Sao chép{"type": "input_video", "file_id": "<file_id>"}

Các mô hình hỗ trợ đầu vào video trên BasicRouter bao gồm một số mô hình thuộc dòng Qwen, Doubao (dola-seed), Kimi, MiniMax — kiểm tra input_modalities trả về bởi list_models. Tiêu chuẩn Responses API chính thức của OpenAI không hỗ trợ video native, nhưng gateway BasicRouter hỗ trợ qua định dạng mở rộng:

Sao chép{"type": "input_video", "video_url": "..."}

Định dạng này nhất quán với định dạng input_video được sử dụng bởi BytePlus/Volcengine và các nền tảng khác.

2. Mô hình & tài khoản

4. list_models — Liệt kê các mô hình khả dụng

Trả về các mô hình khả dụng cho tài khoản hiện tại, cùng metadata về nhà cung cấp, phương thức, năng lực và giá. Không có tham số. Mỗi mục trong danh sách gồm bậc giá price_tiers — giá thanh toán hiệu lực của bên gọi, khớp với khoản trừ thực tế (xem Tham chiếu trường bậc giá) (only some newer models).

5. get_model — Lấy chi tiết một mô hình

Đầu ra gồm bậc giá price_tiers (xem Tham chiếu trường bậc giá); trả về 404 (không có trường giá) khi mô hình không tồn tại.

6. get_balance — Kiểm tra số dư tài khoản

Trả về mức sử dụng và số dư của tài khoản hiện tại. Không có tham số.

3. Thanh toán

7. list_usage — Chi tiết sử dụng/thanh toán mô hình

Chi tiết thanh toán sử dụng mô hình theo trang, sắp xếp theo thời gian tạo đơn giảm dần. Chỉ gồm các khoản phí sử dụng thông thường — không bao gồm nạp tiền hoặc điều chỉnh.

8. list_transactions — Giao dịch nạp tiền/gói

Giao dịch nạp tiền / mua gói đã thanh toán theo trang, sắp xếp theo thời gian tạo giảm dần.

4. Tạo hình ảnh

9. list_image_models — Liệt kê các mô hình hình ảnh

Trả về các mô hình tạo hình ảnh được hỗ trợ, cùng độ phân giải, tỷ lệ khung hình, số lượng hình ảnh tối đa (maxCount) và số lượng hình ảnh tham chiếu tối đa (fileMax). Không có tham số. Hãy kiểm tra trước khi tạo hình ảnh — bạn chỉ có thể truyền các giá trị mà nó công bố. Mỗi mục trong danh sách gồm bậc giá priceTiers (xem Tham chiếu trường bậc giá).

10. create_image_generation — Gửi một tác vụ tạo hình ảnh

Gửi bất đồng bộ và trả về ngay một taskId; tiêu tốn tín dụng tài khoản.

11. get_image_generation — Thăm dò một tác vụ hình ảnh

Trả về: status là pending / success / failed; images là một mảng chuỗi JSON các URL hình ảnh; text mang theo bất kỳ đầu ra bổ sung của mô hình (ví dụ đầu ra đa phương thức của Gemini).

5. Tạo video

12. list_video_models — Liệt kê các mô hình video

Trả về các mô hình tạo video được hỗ trợ, cùng allowedVideoTypes, khoảng thời lượng (videoDurationMin/Max), độ phân giải, tỷ lệ khung hình và giới hạn tài nguyên tham chiếu (fileMax). Không có tham số. Hãy kiểm tra trước khi tạo video. Mỗi mục trong danh sách gồm bậc giá priceTiers (xem Tham chiếu trường bậc giá).

13. create_video_generation — Gửi một tác vụ tạo video

Gửi bất đồng bộ và trả về ngay một taskId; tiêu tốn tín dụng tài khoản.

Ý nghĩa của video_type:

14. get_video_generation — Thăm dò một tác vụ video

Tham chiếu trường bậc giá

Đầu ra của 4 công cụ truy vấn mô hình này — list_models, get_model, list_image_models, list_video_models — trả về giá thanh toán hiệu lực của bên gọi (người dùng API Key), khớp chính xác với khoản trừ thực tế, và bao gồm tất cả bậc giá của mô hình.

Khác biệt đặt tên: list_models / get_model dùng snake_case của OpenAI (price_tiers); list_image_models / list_video_models dùng camelCase (priceTiers). Cấu trúc giống nhau.

price_tiers / priceTiers là mảng; mỗi phần tử là một bậc giá:

Ba loại mô hình dùng chung một cấu trúc; chỉ khác trường mô tả, và trường không áp dụng là null:

Ý nghĩa giá: các inputPrice / outputPrice / cacheReadPrice / cacheWritePrice trả về, v.v. là giá đơn vị thanh toán cuối cùng dành cho người dùng API Key hiện tại, được tính qua chuỗi giá (chain) → guidance → giá cơ sở, và khớp với khoản trừ thực tế. Giá đơn vị mà bên gọi thấy khác nhau tùy chuỗi giá của họ (reseller / distributor / doanh nghiệp / cấu hình cấp người dùng).

Khoản trừ thực tế = lượng dùng ÷ quantity × giá đơn vị × ratio. Khi thanh toán video theo giây: khoản trừ thực tế = duration × outputPrice × ratio.

Trường hợp biên và xử lý lỗi (endpoint chỉ đọc không bao giờ trả 500 do cấu hình giá):

Ví dụ phản hồi (list_models, mô hình văn bản):

Sao chép{
  "object": "list",
  "data": [
    {
      "id": "gpt-4o",
      "object": "model",
      "display_name": "gpt-4o",
      "context_length": 128000,
      "description": "...",
      "price_tiers": [
        {
          "region": "GLOBAL",
          "bandMin": null,
          "bandMax": null,
          "resolution": null,
          "clarity": null,
          "unit": "token",
          "quantity": 1000,
          "description": "mỗi 1K token",
          "inputPrice": 0.0025,
          "outputPrice": 0.01,
          "cachePrice": 0.00125,
          "cacheReadPrice": 0,
          "cacheWritePrice": 0,
          "ratio": 1,
          "mode": "RATIO",
          "planId": null
        }
      ]
    }
  ]
}

Ví dụ phản hồi (list_image_models, mô hình ảnh; priceTiers cùng cấu trúc, unit là image):

Sao chép{
  "object": "list",
  "data": [
    {
      "id": "dall-e-3",
      "object": "image_model",
      "displayName": "dall-e-3",
      "resolutions": ["1024x1024", "1792x1024", "1024x1792"],
      "priceTiers": [
        {
          "region": null,
          "bandMin": null,
          "bandMax": null,
          "resolution": "1024x1024",
          "clarity": "standard",
          "unit": "image",
          "quantity": 1,
          "description": "mỗi ảnh",
          "inputPrice": 0,
          "outputPrice": 0.04,
          "cachePrice": 0,
          "cacheReadPrice": 0,
          "cacheWritePrice": 0,
          "ratio": 1,
          "mode": "RATIO",
          "planId": null
        }
      ]
    }
  ]
}

Ví dụ

Ví dụ 1: một yêu cầu chat đơn giản

Hỏi: "Dùng BasicRouter để gọi claude-sonnet-5 và hỏi GIL của Python là gì"

AI sẽ gọi chat_completion với:

Sao chép{
  "model": "claude-sonnet-5",
  "messages": [{"role": "user", "content": "What is Python's GIL?"}]
}

Ví dụ 2: dùng công cụ qua endpoint Anthropic Messages

Hỏi: "Dùng endpoint Messages của BasicRouter và để mô hình tự quyết định có cần kiểm tra thời tiết không"

AI sẽ gọi create_message, truyền một định nghĩa tools và tool_choice; phản hồi sẽ bao gồm một khối nội dung tool_use.

Ví dụ 3: liệt kê các mô hình khả dụng

Hỏi: "Liệt kê các mô hình trên tài khoản BasicRouter của tôi"

AI sẽ gọi list_models, trả về ID, nhà cung cấp, phương thức, giá và nhiều thông tin khác cho mọi mô hình khả dụng.

Ví dụ 4: kiểm tra số dư và mức sử dụng

Hỏi: "Kiểm tra mức sử dụng BasicRouter của tôi trong tháng này"

AI sẽ gọi get_balance để lấy số dư, sau đó list_usage (với start_time giới hạn trong tháng này) để lấy chi tiết sử dụng.

Ví dụ 5: tạo một hình ảnh

Hỏi: "Dùng BasicRouter để tạo một hình ảnh thành phố cyberpunk về đêm"

AI sẽ gọi list_image_models trước để kiểm tra thông số, sau đó create_image_generation để lấy taskId, rồi thăm dò get_image_generation để lấy URL hình ảnh.

Ví dụ 6: text-to-video

Hỏi: "Dùng BasicRouter để tạo một video 5 giây về một tinh vân trong không gian"

AI sẽ gọi list_video_models trước để kiểm tra thông số, sau đó create_video_generation (video_type=1, duration=5), và sau khi nhận được taskId, thăm dò get_video_generation.

FAQ

Lệnh gọi công cụ thất bại với "missing BasicRouter API Key"

• Bạn đã chạy claude mcp add mà không có --header, hoặc khóa sai
• Nếu chỉnh sửa trực tiếp cấu hình JSON, tên trường headers bị sai (phải là X-Basicrouter-Api-Key)
• Chạy cục bộ mà chưa đặt biến môi trường BASICROUTER_API_KEY

Lệnh gọi công cụ thất bại với "BasicRouter returned 401 unauthorized"

Khóa API bản thân nó sai hoặc đã hết hạn — hãy tạo lại trong bảng điều khiển BasicRouter.

Claude không gọi các công cụ BasicRouter — làm sao đây?

• Xác nhận kết nối hiển thị ✓ Connected qua claude mcp list
• Kiểm tra trạng thái kết nối: claude mcp get basicrouter
• Hãy thử nói rõ hơn: "Dùng công cụ chat_completion của BasicRouter để gọi claude-sonnet-5 …"

Tạo hình ảnh/video mãi ở trạng thái pending

• Thăm dò các tác vụ hình ảnh bằng get_image_generation và các tác vụ video bằng get_video_generation — lưu ý trạng thái của một tác vụ video đang chạy là "running", không phải "pending"
• Việc tạo cần thời gian, thường từ vài đến vài chục giây, lâu hơn với video
• Nếu bạn đã truyền callback_url, tác vụ sẽ gọi lại khi hoàn tất — không cần thăm dò

Lỗi list_image_models / list_video_models

Cả hai công cụ này đều không tự tiêu tốn tín dụng — lỗi thường chỉ ra vấn đề về khóa hoặc mạng. Trước tiên hãy xác nhận list_models hoạt động bình thường.

Ghi chú

• Tên header:MCP truyền khóa qua X-Basicrouter-Api-Key.
• Tiêu tốn tín dụng:chat_completion / create_message / create_response / create_image_generation / create_video_generation đều tiêu tốn tín dụng tài khoản — hãy kiểm tra get_balance trước nếu bạn muốn biết số dư trước khi thực hiện.
• Kiểm tra thông số trước khi tạo:Các tham số tạo hình ảnh/video như model, resolution, ratio, count, duration và video_type chỉ được dùng các giá trị do list_image_models / list_video_models công bố, nếu không lệnh gọi sẽ báo lỗi.
• Không streaming:Không có endpoint chat nào trong ba endpoint hỗ trợ streaming — mỗi endpoint trả về toàn bộ kết quả một lần.
• Thiết kế không trạng thái:Mỗi yêu cầu độc lập và không có session nào được lưu trữ; đối với hội thoại nhiều lượt, hãy dùng previous_response_id của create_response hoặc tự duy trì lịch sử trong messages.