Khám phá mô hình

Sử dụng trang Mô hình hoặc API Mô hình để kiểm tra các mô hình văn bản có sẵn. Siêu dữ liệu mô hình bao gồm nhà cung cấp, nhà cung cấp dịch vụ, phương thức, độ dài ngữ cảnh, họ API được hỗ trợ, khả năng được hỗ trợ, tình trạng sẵn có, giới hạn cấp tài khoản và giá tín dụng.

Điểm cuối: GET /v1/models Mục đích: Liệt kê các mô hình sẵn có cho tài khoản hiện tại.

curl --request GET \
  --url https://api.basicrouter.ai/api/v1/models \
  --header "Authorization: Bearer $BASICROUTER_API_KEY"

Ma trận khả năng

Ma trận tương thích họ API

Xác thực

Mọi yêu cầu API đều sử dụng bearer token. Lưu khóa trong biến môi trường phía máy chủ, xoay vòng khi quyền truy cập nhóm thay đổi và ghi lại ID yêu cầu để gỡ lỗi.

Khuyến nghị bảo mật khóa

1. Giữ khóa API trên máy chủ. Không tiết lộ khóa trong mã trình duyệt hoặc ứng dụng khách di động.
2. Sử dụng các khóa riêng biệt cho phát triển, staging, sản xuất và tích hợp bên thứ ba.
3. Phạm vi hóa khóa theo môi trường, dịch vụ, khách hàng hoặc đối tượng thuê khi có sẵn.
4. Xoay vòng khóa sau khi nhân viên nghỉ việc, quyền truy cập nhà cung cấp thay đổi hoặc nghi ngờ rò rỉ.
5. Lưu khóa trong trình quản lý bí mật hoặc biến môi trường, không phải mã nguồn.

Tác nhân lập trình

BasicRouter hoạt động với các tác nhân lập trình và công cụ phát triển AI hỗ trợ các điểm cuối API tương thích OpenAI hoặc tương thích Anthropic. Sử dụng các bí danh định tuyến như mwf/coding-auto để BasicRouter có thể định tuyến đến mô hình lập trình tốt nhất sẵn có mà không yêu cầu nhà phát triển thay đổi cấu hình công cụ.

Thiết lập tương thích OpenAI chung

Sử dụng thiết lập này cho Cursor, Codex, Hermes, OpenClaw, Continue, Aider, Cline, các tác nhân dựa trên LangChain, các tác nhân dựa trên LlamaIndex và các runtime tác nhân tương thích OpenAI tùy chỉnh.

export OPENAI_BASE_URL="https://api.basicrouter.ai/api/v1"
export OPENAI_API_KEY="$BASICROUTER_API_KEY"
export OPENAI_MODEL="mwf/coding-auto"

Thiết lập tương thích Anthropic chung

Sử dụng thiết lập này cho các máy khách tương thích Claude và các công cụ mong đợi định dạng Anthropic Messages.

export ANTHROPIC_BASE_URL="https://api.basicrouter.ai/api/anthropic"
export ANTHROPIC_API_KEY="$BASICROUTER_API_KEY"
export ANTHROPIC_MODEL="mwf/coding-auto"

Mô hình tác nhân được khuyến nghị

Hướng dẫn nhanh Cursor

Sử dụng điểm cuối tương thích OpenAI.

Base URL: https://api.basicrouter.ai/api/v1
API Key:  BASICROUTER_API_KEY
Model:    mwf/coding-auto

Các bước khuyến nghị:

1. Mở cài đặt Cursor.
2. Thêm hoặc bật cấu hình khóa API tương thích OpenAI.
3. Đặt ghi đè OpenAI base URL thành https://api.basicrouter.ai/api/v1.
4. Thêm một mô hình tùy chỉnh như mwf/coding-auto, mwf/coding-fast, hoặc mwf/coding-long.
5. Sử dụng mô hình hỗ trợ phát trực tuyến và gọi công cụ để có hành vi tác nhân tốt nhất.

Khắc phục sự cố:

Hướng dẫn nhanh Claude Code

Sử dụng điểm cuối cổng tương thích Anthropic.

export ANTHROPIC_BASE_URL="https://api.basicrouter.ai/api/anthropic"
export ANTHROPIC_API_KEY="$BASICROUTER_API_KEY"
export ANTHROPIC_MODEL="mwf/coding-auto"

BasicRouter hỗ trợ đường dẫn tương thích Anthropic này cho Claude Code và khả năng tương thích SDK Anthropic:

POST /api/v1/messages

Các yêu cầu khuyến nghị:

Hướng dẫn nhanh Codex

Sử dụng BasicRouter như một nhà cung cấp mô hình tương thích OpenAI tùy chỉnh.

Cấu hình nhà cung cấp ví dụ:

[model_providers.basicrouter]
name = "BasicRouter"
base_url = "https://api.basicrouter.ai/api/v1"
env_key = "BASICROUTER_API_KEY"
wire_api = "responses"

model_provider = "basicrouter"
model = "mwf/coding-auto"

Biến môi trường:

export BASICROUTER_API_KEY="br_xxx"

Các mô hình khuyến nghị:

Khắc phục sự cố:

Hướng dẫn nhanh Hermes

Sử dụng điểm cuối tương thích OpenAI trừ khi triển khai Hermes của bạn được cấu hình cho giao thức khác.

export OPENAI_BASE_URL="https://api.basicrouter.ai/api/v1"
export OPENAI_API_KEY="$BASICROUTER_API_KEY"
export OPENAI_MODEL="mwf/coding-auto"

Chính sách mô hình khuyến nghị:

Hướng dẫn nhanh OpenClaw

Sử dụng điểm cuối tương thích OpenAI cho cấu hình runtime tác nhân kiểu OpenAI.

export OPENAI_BASE_URL="https://api.basicrouter.ai/api/v1"
export OPENAI_API_KEY="$BASICROUTER_API_KEY"
export OPENAI_MODEL="mwf/coding-auto"

Nếu OpenClaw hỗ trợ nhiều nhà cung cấp, cấu hình BasicRouter như một nhà cung cấp tương thích OpenAI và sử dụng bí danh định tuyến BasicRouter để chọn mô hình.

{
  "provider": "openai-compatible",
  "base_url": "https://api.basicrouter.ai/api/v1",
  "api_key_env": "BASICROUTER_API_KEY",
  "model": "mwf/coding-auto"
}

Danh sách kiểm tra khả năng tương thích tác nhân

Sử dụng bảng điều khiển

Bảng điều khiển BasicRouter là mặt phẳng điều khiển vận hành cho truy cập API, tính khả dụng của mô hình, chính sách định tuyến, hiển thị mức sử dụng và quản lý thanh toán. Nó cung cấp cho quản trị viên tài khoản một chế độ xem tập trung về các khóa, mô hình, yêu cầu, tín dụng và điều khiển cấp tài khoản cho lưu lượng mô hình sản xuất.

Quản lý khóa API

Tạo, xoay vòng, thu hồi và gắn nhãn khóa API từ bảng điều khiển. Sử dụng các khóa riêng biệt cho phát triển, dàn dựng, sản xuất và các dịch vụ riêng lẻ để mức sử dụng có thể được kiểm toán và cô lập theo môi trường hoặc ứng dụng.

Danh sách mô hình

Sử dụng trang Mô hình để xem xét các mô hình sẵn có cho tài khoản. Mỗi mục mô hình có thể bao gồm nhà cung cấp, nhà cung cấp dịch vụ, phương thức, họ API được hỗ trợ, độ dài ngữ cảnh, cờ khả năng, tình trạng sẵn có và thông tin giá.

Cho các ứng dụng sản xuất, xác minh khả năng mô hình trước khi bật lưu lượng. Một số tham số và tính năng phụ thuộc vào mô hình và có thể không được hỗ trợ trên tất cả các họ API.

Sử dụng & nhật ký

Chế độ xem Sử dụng & Nhật ký cung cấp hiển thị vận hành cho lưu lượng API. Các nhóm có thể kiểm tra khối lượng yêu cầu, mô hình đã chọn, mục tiêu định tuyến đã giải quyết, mức tiêu thụ tín dụng, độ trễ, mã lỗi và ID yêu cầu.

• Khắc phục sự cố yêu cầu thất bại.
• Nhận diện các tải công việc chi phí cao.
• So sánh mức sử dụng mô hình giữa các ứng dụng và môi trường.
• Xác thực hành vi định tuyến và dự phòng.
• Điều tra vấn đề độ trễ hoặc tính khả dụng của nhà cung cấp.
• Cung cấp ID yêu cầu khi liên hệ hỗ trợ.

Mỗi phản hồi API bao gồm hoặc tiết lộ một ID yêu cầu BasicRouter. Lưu ID này trong nhật ký ứng dụng của bạn để làm cho việc gỡ lỗi sản xuất và leo thang hỗ trợ hiệu quả hơn.

Dự phòng

Dự phòng là cơ chế khả năng phục hồi của BasicRouter. Khi mô hình chính hoặc chính sách định tuyến thất bại, hệ thống tự động chuyển sang mô hình dự phòng để tiếp tục xử lý yêu cầu. Điều này giữ cho ứng dụng của bạn phản hồi tốt và giảm thiểu rủi ro gián đoạn dịch vụ.

Tại sao dự phòng quan trọng

Trong sản xuất, các dịch vụ mô hình có thể gặp một số vấn đề không thể đoán trước:

• Lỗi dịch vụ mô hình: API thượng nguồn tạm thời không khả dụng hoặc hết thời gian chờ.
• Biến động hiệu suất: tải mô hình cao dẫn đến phản hồi chậm hoặc thất bại.
• Lỗi định tuyến: tất cả các mô hình ứng viên được chọn bằng định tuyến thông minh đều không khả dụng.

Dự phòng giữ cho ứng dụng của bạn sẵn có bằng cách cung cấp một đường dẫn dự phòng đáng tin cậy.

Ưu điểm cốt lõi

Cấu hình mô hình dự phòng toàn cục

BasicRouter hỗ trợ thiết lập mô hình dự phòng toàn cục từ backend bảng điều khiển. Tất cả các yêu cầu tự động sử dụng mô hình này làm dự phòng khi thất bại.

Cách cấu hình:

1. Đi đến trang cài đặt chiến lược BasicRouter.
2. Tìm cài đặt Mô hình dự phòng mặc định.
3. Chọn mô hình dự phòng toàn cục của bạn từ danh sách thả xuống.
4. Lưu cài đặt để áp dụng ngay lập tức.

Ưu điểm của cấu hình toàn cục:

• Không cần thay đổi mã: cấu hình một lần và áp dụng toàn cục, không cần lặp lại cài đặt trên mỗi yêu cầu.
• Quản lý tập trung: quản lý chính sách dự phòng tại một nơi để dễ điều chỉnh và theo dõi hơn.
• Bảo trì đơn giản: giảm độ phức tạp của mã và khả năng xảy ra lỗi cấu hình.
• Ghi đè linh hoạt: cấu hình dự phòng cấp yêu cầu có ưu tiên và có thể ghi đè cài đặt toàn cục cho các kịch bản cụ thể.

Cấu hình dự phòng cấp yêu cầu

Cho các kịch bản kinh doanh cụ thể, bạn có thể chỉ định một mô hình dự phòng trên từng yêu cầu để ghi đè cấu hình toàn cục.

Chỉ định mô hình dự phòng với tham số router.fallBackModels:

{
  "model": "claude-sonnet-4",
  "messages": [
    {
      "role": "user",
      "content": "Explain what quantum computing is"
    }
  ],
  "router": {
    "fallBackModels": ["glm-5.2"]
  }
}

Quy tắc ưu tiên

Khi có nhiều cấu hình dự phòng, ưu tiên chạy từ cao nhất đến thấp nhất:

1. router.fallBackModels cấp yêu cầu: mô hình dự phòng được chỉ định trên một yêu cầu riêng lẻ.
2. Mô hình dự phòng mặc định toàn cục: mô hình dự phòng toàn cục được cấu hình trong bảng điều khiển.
3. Không có dự phòng: nếu không cấu hình cái nào, yêu cầu trả về lỗi khi thất bại.

Quản trị tài khoản

Tùy thuộc vào loại tài khoản, bảng điều khiển có thể bao gồm kích hoạt mô hình cấp tài khoản, điều khiển đại lý phân phối hoặc nhà phân phối, cấu hình thanh toán và cài đặt truy cập. Quản trị viên có thể sử dụng các điều khiển này để căn chỉnh quyền truy cập mô hình, hiển thị mức sử dụng và trách nhiệm thanh toán với các ứng dụng, tài khoản khách hàng hoặc đơn vị kinh doanh.

Danh sách kiểm tra vận hành sản xuất

Thanh toán & tín dụng

BasicRouter sử dụng mô hình thanh toán dựa trên tín dụng cho các tải công việc mô hình văn bản, hình ảnh, video và các loại khác được hỗ trợ. Tín dụng cung cấp một đơn vị thống nhất cho việc sử dụng đa mô hình và đa nhà cung cấp để các nhóm có thể quản lý mức tiêu thụ một cách nhất quán trên các phương thức và họ API.

Giá mô hình chi tiết có sẵn trên trang Mô hình hoặc qua các API siêu dữ liệu mô hình. Giá có thể thay đổi theo mô hình, nhà cung cấp, phương thức, độ phân giải, loại token, độ dài đầu ra, thời gian tác vụ, loại tài khoản và thỏa thuận thương mại.

Nạp tiền & ví

Tài khoản có thể thêm tín dụng ví trả theo mức dùng cho sử dụng linh hoạt. Tín dụng ví được sử dụng sau khi tín dụng gói hàng tháng và gói tài nguyên đã được tiêu thụ, trừ khi một quy tắc thanh toán tùy chỉnh áp dụng cho tài khoản.

Tín dụng ví không hết hạn trừ khi được chỉ định khác trong điều khoản thương mại áp dụng. Phí dịch vụ được tính khi nạp lại ví trả theo mức dùng.

Gói hàng tháng và gói tài nguyên

Mỗi người dùng hoặc tài khoản có thể chọn một gói hàng tháng đang hoạt động. Gói hàng tháng cung cấp một lượng năng lực sử dụng xác định, điều khoản thương mại và cấu hình truy cập cấp tài khoản cho kỳ thanh toán.

Người dùng cũng có thể mua nhiều gói tài nguyên để có thêm năng lực sử dụng. Gói tài nguyên có thể tách biệt mức sử dụng cam kết khỏi số dư ví trả theo mức dùng và hữu ích cho sử dụng khối lượng lớn văn bản, hình ảnh, video hoặc tải công việc chuyên biệt.

Thứ tự khấu trừ

Trừ khi cấu hình quy tắc thanh toán tùy chỉnh, tín dụng được khấu trừ theo thứ tự sau:

Cho các tài khoản có điều khoản thương mại tùy chỉnh, thứ tự khấu trừ, quy tắc hết hạn, mức sử dụng đi kèm và giá có thể khác. Quy tắc cụ thể theo tài khoản được hiển thị trong bảng điều khiển hoặc cung cấp qua thỏa thuận thương mại.

Định giá tùy chỉnh

Giá có thể được tùy chỉnh cho mỗi người dùng hoặc tài khoản. Khách hàng doanh nghiệp, tài khoản đại lý phân phối, tài khoản nhà phân phối và khách hàng khối lượng lớn có thể đủ điều kiện cho giá tùy chỉnh. Liên hệ bộ phận bán hàng để nhận báo giá.

Giá tùy chỉnh có thể được cấu hình theo tài khoản, mô hình, nhà cung cấp, phương thức, khu vực, khối lượng sử dụng hoặc thỏa thuận thương mại. Khi giá tùy chỉnh được bật, bảng điều khiển và API thanh toán phản ánh giá và quy tắc khấu trừ cụ thể theo tài khoản khi có sẵn.

Đơn vị giá

Các phương thức mô hình khác nhau sử dụng các đơn vị đo lường khác nhau. BasicRouter quy đổi các đơn vị này thành tín dụng theo quy tắc giá của mô hình.

Đơn vị giá có thể thay đổi theo mô hình. Luôn tham khảo trang chi tiết mô hình hoặc siêu dữ liệu giá trước khi bật một mô hình trong sản xuất.

Gán mức sử dụng

Mức sử dụng BasicRouter có thể được xem xét theo tài khoản, khóa API, mô hình, phương thức hoặc phạm vi thời gian. Điều này cho phép các nhóm gán chi phí cho ứng dụng, môi trường, khách hàng hoặc đơn vị kinh doanh nội bộ.

Số dư tín dụng

Kiểm tra xem có bao nhiêu tín dụng sẵn có trên tài khoản của bạn. Số dư được chia thành ba ví được khấu trừ theo thứ tự: hạn mức gói hàng tháng, gói tài nguyên đã mua và ví trả theo mức dùng. Tổng tài nguyên kết hợp (gói hàng tháng + gói tài nguyên, không bao gồm trả theo mức dùng) cũng có sẵn để theo dõi mức sử dụng đi kèm tách biệt khỏi chi tiêu nạp tiền.

Để truy xuất theo chương trình, xem GET /v1/billing/balance trong Tài liệu API.

Chi tiết sử dụng

Xem xét danh sách theo trang, theo thời gian của các bản ghi sử dụng riêng lẻ để báo cáo, theo dõi và phân bổ chi phí nội bộ. Mỗi bản ghi hiển thị mô hình, loại mô hình (văn bản, hình ảnh hoặc video), tín dụng đã khấu trừ và phân tích từng ví mà mỗi khoản khấu trừ được rút từ. Kết quả có thể được lọc theo một phạm vi thời gian cụ thể.

Để truy xuất theo chương trình, xem GET /v1/usage trong Tài liệu API.

Lịch sử giao dịch

Sử dụng lịch sử giao dịch để xem xét các biến động tín dụng, bao gồm nạp tiền, phân bổ gói, cấp gói tài nguyên, khấu trừ mức sử dụng, điều chỉnh và hiệu chỉnh hành chính.

Để truy xuất theo chương trình, xem GET /v1/billing/transactions trong Tài liệu API.

Yêu cầu thất bại và hoàn tiền

Lỗi xác thực, lỗi xác thực danh tính và lỗi quyền thường không được tính phí vì không có thực thi mô hình nào xảy ra. Các yêu cầu đến một mô hình thượng nguồn hoặc tạo đầu ra một phần có thể tiêu thụ tín dụng tùy thuộc vào mô hình, nhà cung cấp và trạng thái phản hồi.

Cho các tác vụ hình ảnh và video không đồng bộ, hành vi thanh toán phụ thuộc vào việc tác vụ đã được chấp nhận, bắt đầu, hoàn thành, thất bại hay hủy. Phản hồi chi tiết tác vụ bao gồm thông tin sử dụng khi tín dụng đã được tiêu thụ.

Nạp tiền, gói hàng tháng, gói tài nguyên và tín dụng đã tiêu thụ không thể hoàn lại trừ khi được chỉ định khác trong thỏa thuận thương mại áp dụng hoặc yêu cầu bởi pháp luật.

Tài liệu API

Quy ước chung

URL cơ sở

Tất cả các điểm cuối được phục vụ dưới tiền tố /v1.

Xác thực

Các lệnh gọi đến điểm cuối /v1/* sử dụng xác thực Khóa API (không phải JWT). Khóa API được truyền qua header sau:

Các khóa bị thiếu hoặc không hợp lệ trả về 401.

Kiểm tra trước số dư

Tất cả các điểm cuối gọi mô hình chạy kiểm tra trước số dư trước khi thực thi:

• Số dư không đủ trả về Insufficient credit, được ánh xạ tới:
  • Giao thức OpenAI: HTTP 400, code = insufficient_quota
  • Giao thức Anthropic: HTTP 402, type = billing_error
• Một số điểm cuối cũng ước tính chi phí tối thiểu theo mô hình cho lần kiểm tra thứ hai.

POST https://api.basicrouter.ai/api/v1/chat/completions

Điểm cuối tương thích OpenAI Chat Completions. Hỗ trợ phát trực tuyến và không phát trực tuyến, gọi công cụ, chế độ JSON và đầu vào đa phương thức.

Các trường Message:

curl --request POST \
  --url https://api.basicrouter.ai/api/v1/chat/completions \
  --header "Authorization: Bearer $BASICROUTER_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "glm-5.2",
    "messages": [{"role": "user", "content": "Describe Hangzhou in one sentence."}],
    "stream": false,
    "temperature": 0.7
  }'

{
  "id": "chatcmpl-xxx",
  "object": "chat.completion",
  "created": 1721380000,
  "model": "glm-5.2",
  "choices": [
    {
      "index": 0,
      "message": {"role": "assistant", "content": "Hangzhou is ..."},
      "finish_reason": "stop"
    }
  ],
  "usage": {"prompt_tokens": 12, "completion_tokens": 18, "total_tokens": 30}
}

Các trường phản hồi (không phát trực tuyến):

Ví dụ phản hồi phát trực tuyến:

data: {"object":"chat.completion.chunk","choices":[{"delta":{"role":"assistant","content":"..."}}]}

data: {"object":"chat.completion.chunk","choices":[{"delta":{"content":"..."}}]}

data: [DONE]

POST https://api.basicrouter.ai/api/v1/responses

Điểm cuối tương thích OpenAI Responses. Sử dụng input thay vì messages, instructions thay vì tin nhắn hệ thống và khối text thay vì response_format.

curl --request POST \
  --url https://api.basicrouter.ai/api/v1/responses \
  --header "Authorization: Bearer $BASICROUTER_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "glm-5.2",
    "input": "Describe Hangzhou in one sentence.",
    "instructions": "Be concise.",
    "stream": false
  }'

{
  "id": "resp_xxx",
  "object": "response",
  "model": "glm-5.2",
  "status": "completed",
  "created_at": 1721380000,
  "output": [
    {
      "id": "msg_xxx",
      "type": "message",
      "role": "assistant",
      "content": [{"type": "output_text", "text": "Hangzhou is ..."}],
      "status": "completed"
    }
  ],
  "usage": {"input_tokens": 12, "output_tokens": 18, "total_tokens": 30}
}

Các trường phản hồi (không streaming):

Streaming tuân theo các sự kiện của API Responses:

POST https://api.basicrouter.ai/api/v1/messages

Điểm cuối tương thích Anthropic Messages. Chấp nhận header x-api-key và anthropic-version: 2023-06-01. Các khối nội dung hỗ trợ text, image, tool_use, tool_result, thinking và redacted_thinking.

Ví dụ khối hình ảnh:

{ "type": "image", "source": { "type": "base64", "media_type": "...", "data": "..." } }
{ "type": "image", "source": { "type": "url", "url": "..." } }

curl --request POST \
  --url https://api.basicrouter.ai/api/v1/messages \
  --header "Authorization: Bearer $BASICROUTER_API_KEY" \
  --header "anthropic-version: 2023-06-01" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "claude-sonnet-4.6",
    "max_tokens": 1024,
    "messages": [{"role": "user", "content": "Describe Hangzhou in one sentence."}]
  }'

{
  "id": "msg_xxx",
  "type": "message",
  "role": "assistant",
  "model": "claude-sonnet-4.6",
  "content": [{"type": "text", "text": "Hangzhou is ..."}],
  "stop_reason": "end_turn",
  "usage": {"input_tokens": 12, "output_tokens": 18}
}

Các trường phản hồi (không phát trực tuyến):

GET https://api.basicrouter.ai/api/v1/models

Trả về tất cả các mô hình API trực tuyến, đã được kích hoạt.

curl --request GET \
  --url https://api.basicrouter.ai/api/v1/models \
  --header "Authorization: Bearer $BASICROUTER_API_KEY"

{
  "object": "list",
  "data": [
    {
      "id": "glm-5.2",
      "object": "model",
      "display_name": "glm-5.2",
      "created": 1721380000,
      "owned_by": "Zai",
      "input_modalities": ["text", "image"],
      "output_modalities": ["text"],
      "context_length": 128000
    }
  ]
}

Các trường của mỗi mục mô hình (data[]):

GET https://api.basicrouter.ai/api/v1/models/{model}

Trả về một mô hình đơn với cùng cấu trúc như một mục danh sách. Trả về HTTP 404 khi mô hình không tồn tại.

curl --request GET \
  --url https://api.basicrouter.ai/api/v1/models/gpt-5.5 \
  --header "Authorization: Bearer $BASICROUTER_API_KEY"

Phản hồi thành công: một đối tượng mô hình đơn với cùng các trường như một mục danh sách /v1/models.

Khi mô hình không tồn tại, trả về HTTP 404:

{"error": {"message": "The model 'xxx' does not exist", "type": "invalid_request_error", "code": "invalid_model_error"}}

GET https://api.basicrouter.ai/api/v1/image-models

Truy vấn các độ phân giải, tỷ lệ và số lượng tối đa được hỗ trợ bởi một mô hình hình ảnh trước khi gọi /v1/image-generations. Không cần xác thực.

curl --request GET \
  --url https://api.basicrouter.ai/api/v1/image-models \
  --header "Authorization: Bearer $BASICROUTER_API_KEY"

{
  "object": "list",
  "data": [
    {
      "id": "gpt-image-2",
      "object": "image_model",
      "displayName": "GPT Image 1",
      "description": "...",
      "icon": "...",
      "created": 1721380000,
      "maxCount": 4,
      "fileMax": 10,
      "resolutions": ["720p", "1080p"],
      "ratios": ["1:1", "3:2"]
    }
  ]
}

GET https://api.basicrouter.ai/api/v1/video-models

Truy vấn các giá trị videoType được hỗ trợ, phạm vi thời lượng, độ phân giải và tỷ lệ cho một mô hình video trước khi gọi /v1/video-generations. Không cần xác thực.

Các trường VideoTypeOption:

curl --request GET \
  --url https://api.basicrouter.ai/api/v1/video-models \
  --header "Authorization: Bearer $BASICROUTER_API_KEY"

{
  "object": "list",
  "data": [
    {
      "id": "sora-2",
      "object": "video_model",
      "displayName": "Sora 2",
      "description": "...",
      "icon": "...",
      "created": 1721380000,
      "allowedVideoTypes": [
        {"code": 1, "name": "text-to-video"},
        {"code": 2, "name": "image-to-video"},
        {"code": 3, "name": "image-to-video (first/last frame)"}
      ],
      "videoDurationMin": 5,
      "videoDurationMax": 10,
      "videoDurationSuggest": [5, 8, 10],
      "resolutions": ["1080p", "720p"],
      "ratios": ["16:9", "9:16"],
      "fileMax": 5
    }
  ]
}

POST https://api.basicrouter.ai/api/v1/image-generations

Gửi không đồng bộ một tác vụ tạo hình ảnh. Trả về taskId ngay lập tức; truy xuất kết quả bằng cách polling GET /v1/image-generations/{taskId} hoặc qua webhook callbackUrl.

Các giá trị model, resolution / ratio được hỗ trợ, giới hạn trên count, và giới hạn tải lên hình ảnh tham chiếu (fileMax) phải được lấy từ GET /v1/image-models trước. Chỉ các giá trị được quảng cáo bởi spec của mô hình đó mới được chấp nhận.

curl --request POST \
  --url https://api.basicrouter.ai/api/v1/image-generations \
  --header "Authorization: Bearer $BASICROUTER_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "seedream-4.5",
    "text": "A cat drinking water by the river",
    "count": 1,
    "resolution": "2k",
    "ratio": "1:1",
    "imageUrls": []
  }'

{
  "code": 200,
  "message": "image task is commit",
  "data": {"taskId": "img_xxx"}
}

Phản hồi lỗi:

// Insufficient credit
{ "code": 500, "message": "Insufficient credit" }

// Model not found
{ "code": 404, "message": "Model not found: xxx" }

GET https://api.basicrouter.ai/api/v1/image-generations/{taskId}

Poll một tác vụ tạo hình ảnh. status là pending / success / failed. images là một mảng URL hình ảnh được chuỗi hóa JSON; text mang theo bất kỳ mô tả văn bản nào được mô hình đính kèm (vd. đầu ra đa phương thức Gemini), null nếu không có.

curl --request GET \
  --url https://api.basicrouter.ai/api/v1/image-generations/img_xxx \
  --header "Authorization: Bearer $BASICROUTER_API_KEY"

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "img_xxx",
    "status": "success",
    "errorMessage": null,
    "images": "[\"https://.../1.png\"]",
    "text": null
  }
}

Các trường phản hồi data:

Không tìm thấy tác vụ:

{ "code": 500, "message": "task not found" }

Nếu callbackUrl được cung cấp khi gửi, máy chủ sẽ đẩy kết quả cuối cùng success / failed qua webhook với cùng cấu trúc data.

Ví dụ hoàn chỉnh (gửi + poll)

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.time.Duration;

public class ImageGenerationExample {
  private static final String BASE = "https://api.basicrouter.ai/api/v1";
  private static final String API_KEY = System.getenv("BASICROUTER_API_KEY");

  public static void main(String[] args) throws Exception {
    HttpClient http = HttpClient.newBuilder()
        .connectTimeout(Duration.ofSeconds(10)).build();

    // 1. Submit the task.
    String body = "{"
        + "\"model\":\"seedream-4.5\","
        + "\"text\":\"A cat drinking water by the river\","
        + "\"count\":1,"
        + "\"resolution\":\"2k\","
        + "\"ratio\":\"1:1\","
        + "\"imageUrls\":[]"
        + "}";
    HttpResponse<String> submit = http.send(
        HttpRequest.newBuilder(URI.create(BASE + "/image-generations"))
            .header("Authorization", "Bearer " + API_KEY)
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(body)).build(),
        HttpResponse.BodyHandlers.ofString());

    String taskId = extract(submit.body(), "taskId");
    System.out.println("taskId = " + taskId);

    // 2. Poll until terminal status.
    String status = "pending";
    while ("pending".equals(status)) {
      Thread.sleep(15_000L);
      HttpResponse<String> poll = http.send(
          HttpRequest.newBuilder(URI.create(BASE + "/image-generations/" + taskId))
              .header("Authorization", "Bearer " + API_KEY).GET().build(),
          HttpResponse.BodyHandlers.ofString());
      status = extract(poll.body(), "status");
      System.out.println("status = " + status);
    }

    if (!"success".equals(status)) {
      throw new RuntimeException("image generation failed: " + status);
    }
    // images is a JSON-stringified array of URLs.
    String images = extract(pollResult(http, taskId), "images");
    System.out.println("images = " + images);
  }

  // Minimal JSON field extractor — use Jackson/Gson in production.
  private static String extract(String json, String field) {
    int i = json.indexOf("\"" + field + "\":");
    if (i < 0) return null;
    i += field.length() + 3;
    if (json.charAt(i) == '\"') {
      int end = json.indexOf('\"', i + 1);
      return json.substring(i + 1, end);
    }
    int end = i;
    while (end < json.length() && "0123456789.".indexOf(json.charAt(end)) >= 0) end++;
    return json.substring(i, end);
  }

  private static String pollResult(HttpClient http, String taskId) throws Exception {
    return http.send(HttpRequest.newBuilder(URI.create(BASE + "/image-generations/" + taskId))
        .header("Authorization", "Bearer " + API_KEY).GET().build(),
        HttpResponse.BodyHandlers.ofString()).body();
  }
}

import os
import time
import requests

BASE = "https://api.basicrouter.ai/api/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['BASICROUTER_API_KEY']}"}

# 1. Submit the task.
resp = requests.post(
    f"{BASE}/image-generations",
    headers={**HEADERS, "Content-Type": "application/json"},
    json={
        "model": "seedream-4.5",
        "text": "A cat drinking water by the river",
        "count": 1,
        "resolution": "2k",
        "ratio": "1:1",
        "imageUrls": [],
    },
)
resp.raise_for_status()
task_id = resp.json()["data"]["taskId"]
print(f"taskId = {task_id}")

# 2. Poll until terminal status.
while True:
    time.sleep(15)
    poll = requests.get(f"{BASE}/image-generations/{task_id}", headers=HEADERS)
    poll.raise_for_status()
    data = poll.json()["data"]
    status = data["status"]
    print(f"status = {status}")
    if status != "pending":
        break

if status != "success":
    raise RuntimeError(f"image generation failed: {data.get('errorMessage')}")

# images is a JSON-stringified array of URLs.
import json
images = json.loads(data["images"])
print(f"images = {images}")

POST https://api.basicrouter.ai/api/v1/video-generations

Gửi không đồng bộ một tác vụ tạo video. Trả về taskId ngay lập tức; truy xuất kết quả bằng cách polling GET /v1/video-generations/{taskId} hoặc qua webhook callbackUrl.

Các giá trị model, videoType được phép, phạm vi thời lượng (videoDurationMin/Max), resolution / ratio được hỗ trợ, và giới hạn tải lên tài sản tham chiếu (fileMax) phải được lấy từ GET /v1/video-models trước. Chỉ các mã videoType được liệt kê trong allowedVideoTypes của mô hình đó mới được chấp nhận.

Ví dụ cho từng videoType:

1. Văn bản thành video (videoType=1)

Tạo video chỉ từ prompt văn bản; không cần tài sản tham chiếu.

curl --request POST \
  --url https://api.basicrouter.ai/api/v1/video-generations \
  --header "Authorization: Bearer $BASICROUTER_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "videoType": 1,
    "text": "A cat jumping on a bed",
    "resolution": "480p",
    "ratio": "16:9",
    "duration": 4,
    "model": "seedance-2.0"
  }'

2. Hình ảnh thành video - khung đầu (videoType=2)

Cung cấp một khung hình bắt đầu đơn trong imageUrls; mô hình tạo video bắt đầu từ khung hình đó.

curl --request POST \
  --url https://api.basicrouter.ai/api/v1/video-generations \
  --header "Authorization: Bearer $BASICROUTER_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "videoType": 2,
    "text": "Happily shaking head",
    "resolution": "480p",
    "ratio": "16:9",
    "duration": 4,
    "model": "seedance-2.0",
    "imageUrls": ["https://basicrouter-flie.oss-accelerate.aliyuncs.com/test/first-frame.png"]
  }'

3. Hình ảnh thành video - khung đầu và khung cuối (videoType=3)

Cung cấp cả khung đầu và khung cuối trong imageUrls (thứ tự: [đầu, cuối]); mô hình tạo video chuyển tiếp giữa hai khung hình.

curl --request POST \
  --url https://api.basicrouter.ai/api/v1/video-generations \
  --header "Authorization: Bearer $BASICROUTER_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "videoType": 3,
    "text": "Put on the hat",
    "resolution": "480p",
    "ratio": "16:9",
    "duration": 4,
    "model": "seedance-2.0",
    "imageUrls": [
      "https://basicrouter-flie.oss-accelerate.aliyuncs.com/test/first-frame.png",
      "https://basicrouter-flie.oss-accelerate.aliyuncs.com/test/last-frame.png"
    ]
  }'

4. Hình ảnh thành video - tham chiếu (videoType=4)

Cung cấp một hoặc nhiều hình ảnh tham chiếu trong imageUrls; mô hình sử dụng phong cách/nội dung của chúng làm tham chiếu (không phải là khung đầu/cuối bắt buộc) để tạo video.

curl --request POST \
  --url https://api.basicrouter.ai/api/v1/video-generations \
  --header "Authorization: Bearer $BASICROUTER_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "videoType": 4,
    "text": "Two cats playing together",
    "resolution": "480p",
    "ratio": "16:9",
    "duration": 4,
    "model": "kling-v3-omni-video",
    "imageUrls": [
      "https://basicrouter-flie.oss-accelerate.aliyuncs.com/test/ref-1.png",
      "https://basicrouter-flie.oss-accelerate.aliyuncs.com/test/ref-2.png"
    ]
  }'

5. Tất cả tham chiếu (videoType=5)

Tham chiếu hình ảnh / video / âm thanh hỗn hợp. Tham chiếu tài sản theo vị trí trong prompt: mục thứ 1 trong imageUrls là @图片 1, mục thứ 1 trong videoUrls là @视频 1, mục thứ 1 trong audioUrls là @音频 1. videoUrls cũng chấp nhận chuỗi URL đơn giản.

curl --request POST \
  --url https://api.basicrouter.ai/api/v1/video-generations \
  --header "Authorization: Bearer $BASICROUTER_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "videoType": 5,
    "text": "Use the first-person framing of @视频 1 and @音频 1 as background music. First-person tea ad; start frame is @图片 1 ... end frame is @图片 2.",
    "model": "seedance-2.0",
    "imageUrls": [
      "https://ark-project.tos-cn-beijing.volces.com/doc_image/r2v_tea_pic1.jpg",
      "https://ark-project.tos-cn-beijing.volces.com/doc_image/r2v_tea_pic2.jpg"
    ],
    "videoUrls": ["https://ark-project.tos-cn-beijing.volces.com/doc_video/r2v_tea_video1.mp4"],
    "audioUrls": ["https://ark-project.tos-cn-beijing.volces.com/doc_audio/r2v_tea_audio1.mp3"],
    "resolution": "1080p",
    "ratio": "16:9",
    "duration": 11
  }'

Phản hồi gửi (tất cả năm loại):

{
  "code": 200,
  "message": "success",
  "data": {"taskId": "vid_xxx"}
}

GET https://api.basicrouter.ai/api/v1/video-generations/{taskId}

Poll một tác vụ tạo video. status là pending / success / failed; videoUrl là URL video đã tạo và lastFrameUrl là URL khung cuối (trong trường hợp hình ảnh thành video).

curl --request GET \
  --url https://api.basicrouter.ai/api/v1/video-generations/vid_xxx \
  --header "Authorization: Bearer $BASICROUTER_API_KEY"

{
  "code": 200,
  "message": "success",
  "data": {
    "status": "success",
    "videoUrl": "https://.../out.mp4",
    "lastFrameUrl": null,
    "message": null
  }
}

Các trường phản hồi data:

Nếu callbackUrl được cung cấp khi gửi, máy chủ sẽ đẩy kết quả cuối cùng qua webhook với cùng cấu trúc data.

Ví dụ hoàn chỉnh (gửi + poll)

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.time.Duration;

public class VideoGenerationExample {
  private static final String BASE = "https://api.basicrouter.ai/api/v1";
  private static final String API_KEY = System.getenv("BASICROUTER_API_KEY");

  public static void main(String[] args) throws Exception {
    HttpClient http = HttpClient.newBuilder()
        .connectTimeout(Duration.ofSeconds(10)).build();

    // 1. Submit the task (videoType=1: text-to-video).
    String body = "{"
        + "\"videoType\":1,"
        + "\"text\":\"A cat jumping on a bed\","
        + "\"resolution\":\"480p\","
        + "\"ratio\":\"16:9\","
        + "\"duration\":4,"
        + "\"model\":\"seedance-2.0\""
        + "}";
    HttpResponse<String> submit = http.send(
        HttpRequest.newBuilder(URI.create(BASE + "/video-generations"))
            .header("Authorization", "Bearer " + API_KEY)
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(body)).build(),
        HttpResponse.BodyHandlers.ofString());

    String taskId = extract(submit.body(), "taskId");
    System.out.println("taskId = " + taskId);

    // 2. Poll until terminal status. Video tasks take longer — poll every 20s.
    String status = "pending";
    String lastBody = null;
    while ("pending".equals(status)) {
      Thread.sleep(20_000L);
      HttpResponse<String> poll = http.send(
          HttpRequest.newBuilder(URI.create(BASE + "/video-generations/" + taskId))
              .header("Authorization", "Bearer " + API_KEY).GET().build(),
          HttpResponse.BodyHandlers.ofString());
      lastBody = poll.body();
      status = extract(lastBody, "status");
      System.out.println("status = " + status);
    }

    if (!"success".equals(status)) {
      throw new RuntimeException("video generation failed: " + status);
    }
    String videoUrl = extract(lastBody, "videoUrl");
    System.out.println("videoUrl = " + videoUrl);
  }

  // Minimal JSON field extractor — use Jackson/Gson in production.
  private static String extract(String json, String field) {
    int i = json.indexOf("\"" + field + "\":");
    if (i < 0) return null;
    i += field.length() + 3;
    if (json.charAt(i) == '\"') {
      int end = json.indexOf('\"', i + 1);
      return json.substring(i + 1, end);
    }
    int end = i;
    while (end < json.length() && "0123456789.".indexOf(json.charAt(end)) >= 0) end++;
    return json.substring(i, end);
  }
}

import os
import time
import requests

BASE = "https://api.basicrouter.ai/api/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['BASICROUTER_API_KEY']}"}

# 1. Submit the task (videoType=1: text-to-video).
resp = requests.post(
    f"{BASE}/video-generations",
    headers={**HEADERS, "Content-Type": "application/json"},
    json={
        "videoType": 1,
        "text": "A cat jumping on a bed",
        "resolution": "480p",
        "ratio": "16:9",
        "duration": 4,
        "model": "seedance-2.0",
    },
)
resp.raise_for_status()
task_id = resp.json()["data"]["taskId"]
print(f"taskId = {task_id}")

# 2. Poll until terminal status. Video tasks take longer — poll every 20s.
while True:
    time.sleep(20)
    poll = requests.get(f"{BASE}/video-generations/{task_id}", headers=HEADERS)
    poll.raise_for_status()
    data = poll.json()["data"]
    status = data["status"]
    print(f"status = {status}")
    if status != "pending":
        break

if status != "success":
    raise RuntimeError(f"video generation failed: {data.get('message')}")

print(f"videoUrl = {data['videoUrl']}")
if data.get("lastFrameUrl"):
    print(f"lastFrameUrl = {data['lastFrameUrl']}")

GET https://api.basicrouter.ai/api/v1/billing/balance

Trả về số dư tài khoản chia thành ba ví: gói tháng, gói tài nguyên và tín dụng trả theo mức dùng.

curl --request GET \
  --url https://api.basicrouter.ai/api/v1/billing/balance \
  --header "Authorization: Bearer $BASICROUTER_API_KEY"

{
  "totalCredit": 128.50,
  "totalResourceCredit": 30.00,
  "wallets": {
    "monthlyPlan": {"id": "pkg_xxx", "credit": 50.00, "name": "Monthly plan"},
    "resourcePacks": [
      {"id": "rp_xxx", "credit": 30.00, "name": "Video resource pack"}
    ],
    "payAsYouGo": 48.50
  }
}

Các trường phản hồi:

Các trường WalletDetailVO:

GET https://api.basicrouter.ai/api/v1/usage

Chi tiết thanh toán cuộc gọi mô hình phân trang, được chụp nhanh theo giá (priceSnapshotId), sắp xếp theo thời gian tạo đơn hàng giảm dần. Chỉ các bản ghi tính phí bình thường (reason = model usage) được trả về.

Tham số truy vấn:

curl --request GET \
  --url "https://api.basicrouter.ai/api/v1/usage?page=1&size=20&startTime=2026-07-01T00:00:00&endTime=2026-07-31T23:59:59" \
  --header "Authorization: Bearer $BASICROUTER_API_KEY"

Bọc phản hồi:

{
  "code": 0,
  "message": "success",
  "data": { ... }
}

Các trường UsageDetailVO:

Các trường CreditDetailItem:

Quy ước giá trị null: chỉ các trường liên quan đến từng modelType mới được điền; các trường còn lại là null. text điền các trường token; image điền imageCount/imageResolution/imageRatio; video điền videoResolution/videoRatio/videoDurationSec.

Ví dụ phản hồi:

{
  "code": 200,
  "message": "success",
  "data": {
    "records": [
      {
        "priceSnapshotId": "snap_9f3c1a2b",
        "taskId": "task_5e8a1c33",
        "credit": 0.0342,
        "model": "glm-5.2",
        "modelType": "text",
        "inputTokens": 1280,
        "outputTokens": 642,
        "totalTokens": 1922,
        "cacheReadTokens": 0,
        "cacheWriteTokens": 0,
        "imageCount": null,
        "imageResolution": null,
        "imageRatio": null,
        "videoResolution": null,
        "videoRatio": null,
        "videoDurationSec": null,
        "orderCreatedAt": "2026-07-18T14:23:11",
        "creditDetails": [
          {
            "credit": 0.0342,
            "deductionSource": "balance",
            "packageName": ""
          }
        ]
      },
      {
        "priceSnapshotId": "snap_a12f77c0",
        "taskId": "task_c71e44a2",
        "credit": 1.8000,
        "model": "seedance-2.0",
        "modelType": "video",
        "inputTokens": null,
        "outputTokens": null,
        "totalTokens": null,
        "cacheReadTokens": null,
        "cacheWriteTokens": null,
        "imageCount": null,
        "imageResolution": null,
        "imageRatio": null,
        "videoResolution": "1080p",
        "videoRatio": "16:9",
        "videoDurationSec": 8,
        "orderCreatedAt": "2026-07-17T22:41:09",
        "creditDetails": [
          {
            "credit": 1.5000,
            "deductionSource": "Monthly Package",
            "packageName": "基础月度套餐"
          },
          {
            "credit": 0.3000,
            "deductionSource": "Resource Package",
            "packageName": "byteplus视频资源包"
          }
        ]
      }
    ],
    "total": 128,
    "current": 1,
    "size": 20,
    "pages": 7
  }
}

GET https://api.basicrouter.ai/api/v1/billing/transactions

Danh sách phân trang các giao dịch nạp tiền đã thanh toán (status=2) của người dùng hiện tại, sắp xếp theo created_at giảm dần.

curl --request GET \
  --url "https://api.basicrouter.ai/api/v1/billing/transactions?page=1&size=20&startTime=2026-07-01%2000:00:00&endTime=2026-07-31%2023:59:59" \
  --header "Authorization: Bearer $BASICROUTER_API_KEY"

Bọc phản hồi:

{
  "code": 0,
  "message": "success",
  "data": { ... }
}

Các trường TransactionVO:

Các trường TransactionVO (tiếp theo):

{
  "code": 200,
  "message": "success",
  "data": {
    "records": [
      {
        "orderNo": "R20260718abc123",
        "thirdPartyOrderNo": "wx_pay_xxx",
        "amount": 50.00,
        "actualAmount": 48.50,
        "discount": 1.50,
        "paymentMethod": "wechat",
        "serviceFeeAmount": 0.00,
        "paymentChannel": "wechat",
        "source": "recharge",
        "packageName": null,
        "createdAt": "2026-07-18T14:23:11"
      }
    ],
    "total": 28,
    "current": 1,
    "size": 20,
    "pages": 2
  }
}

Vận hành

Lỗi

BasicRouter trả về mã lỗi ổn định để ứng dụng có thể xử lý thử lại, dự phòng, vấn đề thanh toán và gỡ lỗi một cách nhất quán.

Các điểm cuối tương thích nhà cung cấp cố gắng giữ nguyên hình dạng lỗi của họ API gốc khi có thể. Các điểm cuối native BasicRouter sử dụng đối tượng lỗi BasicRouter.

Ánh xạ trạng thái HTTP và mã lỗi

Mã lỗi phổ biến