API nền tảng

Đây là mọi thứ ngoại trừ việc gửi một prompt: có những mô hình nào, mỗi nhà cung cấp tính giá bao nhiêu, bạn đã chi bao nhiêu và bạn đang giữ những khóa nào. Tất cả đều trả về JSON trên cùng máy chủ api mà bạn gửi yêu cầu hoàn thành văn bản.

Các điểm cuối danh mục và giá là công khai, hoàn toàn không cần thông tin xác thực. Mọi thứ liên quan đến tài khoản của bạn đều cần, và có hai loại.

Chúng không thay thế cho nhau được. Khóa API không đọc được số dư của bạn, còn token truy cập không gửi được yêu cầu hoàn thành văn bản.

Cả hai đều đi trong cùng một header, Authorization: Bearer rồi đến giá trị. Không có gì khác được đọc. Các ví dụ cũ có thêm header New-Api-User, header đó bị bỏ qua, và không có phương án dự phòng bằng cookie.

Hãy gửi header đó ngay cả ở nơi điểm cuối vẫn trả lời khi thiếu nó. Một yêu cầu tới tuyến tài khoản mà không mang thông tin xác thực có thể bị chặn lại để kiểm tra trước khi đến chỗ chúng tôi, và bước kiểm tra đó trả về HTML thay vì JSON.

Mở Cài đặt, tìm mục Truy cập API trong phần Bảo mật và tạo một token. Token chỉ hiện ra một lần. Nó chỉ có thể được tạo khi bạn đang đăng nhập, nên một script không thể tự cấp token cho chính nó.

Hãy coi nó như một mật khẩu. Nó có thể tiêu tiền, tạo khóa và đọc lịch sử của bạn. Hãy thu hồi nó ngay trên màn hình đó khi script không còn cần đến nữa.

Một yêu cầu công khai duy nhất trả về mọi mô hình, với giá đã quy đổi sẵn sang đô la cho mỗi triệu token. Không cần khóa, không cần đăng ký.

curl https://api.unorouter.com/api/pricing/catalog

{
  "counts": { "models": 239, "free": 134, "paid": 105, "vendors": 50 },
  "first_free_model": "glm-5.3:free",
  "vendors": [{ "vendor_id": 4, "vendor_name": "Zhipu", "icon": "Zhipu.Color" }],
  "models": [
    {
      "model_name": "glm-5.3",
      "vendor": "Zhipu",
      "type": "text",
      "is_free": false,
      "online": true,
      "input_price": 0.05103,
      "output_price": 0.160382187,
      "original_input_price": 1.26,
      "original_output_price": 3.960054,
      "tags": "Text,Reasoning,Tools,Cache",
      "supported_endpoint_types": ["openai", "anthropic"],
      "uptime_24h": 99.965,
      "success_rate": 95,
      "avg_latency_ms": 11062
    }
  ]
}

input_price và output_price là số tiền bạn thực sự phải trả hôm nay, tại nhà cung cấp rẻ nhất đang phục vụ mô hình đó. original_input_price và original_output_price là giá niêm yết của chính hãng, nên khoảng cách giữa hai bên chính là mức giảm giá. Trường is_free đánh dấu những mô hình không bao giờ tính phí, còn online đánh dấu những mô hình đang có nhà cung cấp hoạt động ngay lúc này.

Hai điểm cuối nhỏ hơn cùng họ: /api/pricing/counts chỉ trả về các con số tổng và đủ nhẹ để hỏi liên tục, còn /api/pricing/vendors trả về danh sách hãng. Điểm cuối cũ hơn /api/pricing trả về hệ số thô thay vì đô la và lớn hơn nhiều lần.

Phần lớn mô hình được nhiều nhà cung cấp phục vụ với mức giá khác nhau. Hãy hỏi về một mô hình duy nhất để thấy tất cả.

curl "https://api.unorouter.com/api/pricing/catalog/model?model=glm-5.3"

{
  "model_name": "glm-5.3",
  "model_ratio": 0.63,
  "completion_ratio": 3.1429,
  "cache_ratio": 0.1857,
  "input_price": 0.05103,
  "output_price": 0.160382187,
  "grid_min_ratio": 0.0405,
  "auto_chain": ["a7-bbgt-2846-glm-5.3", "a7-kkl-3731-glm-5.3", "a7-4069-glm-5.3"],
  "group_ratio": {
    "a7-bbgt-2846-glm-5.3": 0.0405,
    "a7-kkl-3731-glm-5.3": 0.0911,
    "a7-4069-glm-5.3": 0.1214
  },
  "enable_groups": ["a7-bbgt-2846-glm-5.3", "a7-kkl-3731-glm-5.3"]
}

Trường auto_chain là thứ tự mà bộ định tuyến thử lần lượt, rẻ nhất trước. Trường group_ratio cho biết hệ số nhân của từng nhà cung cấp, và giá được suy ra từ đó:

input  $/1M = model_ratio * 2 * group_ratio
output $/1M = input * completion_ratio
cached $/1M = input * cache_ratio

glm-5.3 on a7-bbgt-2846: 0.63 * 2 * 0.0405 = $0.05103 / 1M in
                          0.05103 * 3.1429  = $0.16038 / 1M out

Các tên nhóm này chính là những tên bạn gán cố định cho một khóa, xem Ghim nhóm

Danh sách tương thích OpenAI là thứ mà hầu hết client gọi khi bạn bấm kết nối. Nó cần một khóa API.

curl https://api.unorouter.com/v1/models \
  -H "Authorization: Bearer $UNOROUTER_API_KEY"

Nó chỉ trả về những gì khóa đó thực sự được dùng, nên khóa ở bậc miễn phí thấy ít mô hình hơn khóa đã nạp tiền. Mỗi mục còn kèm context_length và max_output_tokens, những trường mà OpenAI thuần không cung cấp.

Đường dẫn là /v1/models. Bỏ /v1 đi thì bạn tới một trang web chứ không phải API, và client báo lỗi này thành lỗi phân tích JSON về một doctype không mong đợi.

Một lệnh gọi trả về tài khoản của bạn, gồm cả số tiền còn lại để chi tiêu.

curl https://api.unorouter.com/api/user/self \
  -H "Authorization: Bearer $UNOROUTER_ACCESS_TOKEN"

{
  "success": true,
  "message": "",
  "data": {
    "id": 12345,
    "username": "you",
    "group": "default",
    "quota": 265000,
    "used_quota": 4231900,
    "request_count": 1884,
    "aff_code": "ABC123"
  }
}

Số tiền tính bằng đơn vị hạn mức, không phải đô la. 500.000 đơn vị bằng một đô la Mỹ, nên số dư ở trên là 0,53 USD. Chia cho 500.000 để hiển thị thành tiền.

Trường quota là số bạn còn có thể chi. Trường used_quota và request_count là tổng tích lũy trọn đời và chỉ tăng lên, nên used_quota không phải là hiệu giữa bất cứ thứ gì với số dư của bạn.

Liệt kê các khóa của bạn, rồi hiện một khóa theo id.

curl "https://api.unorouter.com/api/token/?p=1&page_size=20" \
  -H "Authorization: Bearer $UNOROUTER_ACCESS_TOKEN"

curl -X POST https://api.unorouter.com/api/token/42/key \
  -H "Authorization: Bearer $UNOROUTER_ACCESS_TOKEN"

Khi liệt kê, mọi giá trị khóa đều bị che, vì vậy việc hiện khóa là một lệnh gọi riêng. Lệnh gọi đó bị giới hạn tần suất và được ghi vào nhật ký kiểm toán của bạn.

Tạo khóa trả về success nhưng không trả về chính khóa đó. Hãy tạo, liệt kê để tìm id của nó, rồi hiển thị khóa. Cập nhật khóa trả về đối tượng đã cập nhật, nhưng hãy gửi toàn bộ đối tượng: chỉ cross_group_retry, group_mapping và auto_groups là giữ nguyên khi bị bỏ qua, mọi trường khác bạn bỏ qua sẽ bị ghi lại thành rỗng.

Lịch sử yêu cầu của chính bạn được phân trang và có thể lọc.

curl -G https://api.unorouter.com/api/log/self \
  -H "Authorization: Bearer $UNOROUTER_ACCESS_TOKEN" \
  -d p=1 \
  -d page_size=100 \
  -d type=2 \
  -d start_timestamp=1789344000 \
  -d model_name=glm-5.3

Thêm p và page_size để phân trang, kích thước trang tối đa là 100. Điểm cuối anh em /api/log/self/stat chỉ trả về các con số tổng cho cùng bộ lọc: chi tiêu, số yêu cầu mỗi phút và số token mỗi phút.

Để đọc số dư còn lại của một khóa mà không cần token truy cập, hãy xác thực bằng chính khóa đó:

curl https://api.unorouter.com/api/usage/token/ \
  -H "Authorization: Bearer $UNOROUTER_API_KEY"

{
  "object": "token_usage",
  "name": "SillyTavern",
  "total_granted": 500000,
  "total_used": 231900,
  "total_available": 268100,
  "unlimited_quota": false,
  "model_limits_enabled": false,
  "expires_at": 0
}

Các điểm cuối tài khoản bọc phần dữ liệu của chúng. Các điểm cuối phân trang bọc hai lần.

{ "success": true, "message": "", "data": { ... } }

{ "success": true, "message": "", "data": {
    "page": 1, "page_size": 20, "total": 137, "items": [ ... ]
} }

Các điểm cuối danh mục công khai là ngoại lệ, chúng trả về đối tượng trực tiếp, không có lớp bọc.

Phần lớn lỗi vẫn trả về HTTP 200 với success đặt thành false kèm một thông báo giải thích lý do. Hãy kiểm tra trường đó thay vì mã trạng thái.

Xác thực là ngoại lệ và trả về mã trạng thái thật: 401 kèm AUTH_UNAUTHORIZED khi thông tin xác thực sai, AUTH_TOKEN_EXPIRED khi nó đã hết hạn, AUTH_SESSION_REVOKED sau khi đăng xuất, và 403 AUTH_INSUFFICIENT_PRIVILEGE khi tài khoản không được phép gọi tuyến đó.