SiCore TokenWorks

Tài liệu API

Hướng dẫn tích hợp chi tiết và tài liệu tham khảo API, giúp bạn nhanh chóng tích hợp dịch vụ API AI của SiCore TokenWorks

1Bắt đầu nhanh

Sử dụng API SiCore TokenWorks chỉ cần ba bước đơn giản:

  1. Đăng ký tài khoản SiCore TokenWorks và đăng nhập bảng điều khiển
  2. Tạo API Key trong bảng điều khiển
  3. Sử dụng API Key của bạn để gọi các giao diện của chúng tôi

Tip: Người dùng mới đăng ký sẽ nhận được hạn mức dùng thử miễn phí, không cần liên kết thẻ tín dụng để bắt đầu sử dụng.

2Địa chỉ giao diện

Địa chỉ cơ sở của API như sau, tất cả các yêu cầu đều sử dụng giao thức HTTPS:

text
https://www.token8341.com/v1

Giao diện hoàn thiện hội thoại:

text
POST https://www.token8341.com/v1/chat/completions

Note: Giao diện này hoàn toàn tương thích với định dạng giao diện Chat Completions của OpenAI, bạn có thể trực tiếp sử dụng SDK của OpenAI để gọi.

3Phương thức xác thực

SiCore TokenWorks sử dụng Bearer Token để xác thực API. Vui lòng mang theo API Key của bạn trong tiêu đề yêu cầu:

text
Authorization: Bearer sk-your-api-key-here

Bạn có thể tạo và quản lý khóa của mình tại trang "API Keys" trong bảng điều khiển. Vui lòng bảo quản API Key của bạn cẩn thận, không tiết lộ trong kho mã công khai hoặc mã phía máy khách.

4Danh sách mô hình hỗ trợ

ID mô hìnhTên mô hìnhNhà cung cấp
gpt-4oGPT-4oOpenAI
gpt-4o-miniGPT-4o MiniOpenAI
claude-3-5-sonnetClaude 3.5 SonnetAnthropic
claude-4-sonnetClaude 4 SonnetAnthropic
gemini-2-0-proGemini 2.0 ProGoogle
deepseek-v4-proDeepSeek-V4-ProDeepSeek
qwen-maxQwen-MaxAlibaba Cloud

Nhiều mô hình hơn đang được tích hợp liên tục, vui lòng theo dõi thông báo cập nhật của chúng tôi.

5Mã mẫu

curl

bash
curl https://www.token8341.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-your-api-key-here" \
  -d '{
    "model": "gpt-4o",
    "messages": [
      {"role": "user", "content": "Hello!"}
    ]
  }'

Python (openai SDK)

python
from openai import OpenAI

client = OpenAI(
    base_url="https://www.token8341.com/v1",
    api_key="sk-your-api-key-here"
)

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[
        {"role": "user", "content": "Hello!"}
    ]
)

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

Node.js (openai SDK)

javascript
import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://www.token8341.com/v1",
  apiKey: "sk-your-api-key-here",
});

const response = await client.chat.completions.create({
  model: "gpt-4o",
  messages: [
    { role: "user", content: "Hello!" },
  ],
});

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

6Giải thích mã lỗi

Khi yêu cầu API thất bại, sẽ trả về mã trạng thái HTTP và thông tin lỗi tương ứng, định dạng như sau:

json
{
  "error": {
    "message": "Insufficient balance",
    "type": "insufficient_balance",
    "code": 402
  }
}
Mã trạng tháiTênMô tả
400Bad Request请求参数错误，请检查请求体格式
401UnauthorizedAPI Key 无效或缺失，请检查 Authorization 请求头
402Insufficient Balance账户余额不足，请充值后重试
404Not Found请求的模型或接口不存在
429Rate Limit请求频率过高，请稍后重试
500Internal Server Error服务内部错误，请联系技术支持
503Service Unavailable模型服务暂时不可用，请稍后重试

Câu hỏi thường gặp khi tích hợp

Các câu hỏi thường gặp về API Key, chuyển đổi model và ngôn ngữ tích hợp

Một API Key có thể gọi tất cả các model không?

Có. Đây là đặc điểm cốt lõi của SiCore TokenWorks — nhà phát triển chỉ cần tích hợp một lần là có thể gọi tất cả các model trên nền tảng, không cần đăng ký tài khoản riêng và quản lý Key cho từng nhà cung cấp.

Chuyển đổi model có cần sửa code không?

Không cần sửa code logic, chỉ cần thay đổi một tham số model ID là có thể chuyển đổi giữa các model trong nước và quốc tế.

Hỗ trợ những ngôn ngữ lập trình nào?

Cung cấp các ví dụ tích hợp phổ biến như cURL, Python, Node.js, tương thích với mọi ngôn ngữ hỗ trợ HTTP request và OpenAI SDK chính thức.

API được xác thực như thế nào?

Phương thức xác thực là Bearer Token, chỉ cần mang API Key trong header của request; giao diện hoàn toàn tương thích với định dạng Chat Completions của OpenAI, có thể gọi trực tiếp bằng SDK chính thức của OpenAI mà không cần thích ứng thêm.

Có SDK hoặc ví dụ code sẵn có không?

Có. Nền tảng cung cấp các ví dụ tích hợp phổ biến như cURL, Python, Node.js, nhà phát triển chỉ cần chọn theo ngôn ngữ của mình để tích hợp nhanh chóng.

Các mô hình có được bổ sung liên tục không? Mô hình mới có cần sửa code không?

Có. Nền tảng liên tục tích hợp các mô hình nội địa và quốc tế chủ lưu mới, cách tích hợp và hệ thống tính phí được giữ nguyên, sau khi mô hình mới ra mắt có thể chọn dùng trực tiếp mà không cần sửa code.

Cơ chế cache của API mô hình lớn dùng thế nào? Trong tình huống nào có thể hit?

Nền tảng sử dụng cache chia sẻ giữa các người dùng với cùng prompt, sau khi hit giá giảm thêm hơn 90%, giá hit cache thấp nhất là ¥0.010 / triệu Token, phần hit được tính theo giá cache. Phù hợp với tình huống nhiều người dùng lặp lại cùng prefix prompt, ví dụ system prompt cố định, prefix kiến thức chung, v.v. — đặt phần không đổi lên trước sẽ có tỷ lệ hit cao hơn.

Khi gọi API thất bại hoặc timeout, làm sao để tự động retry và fallback?

Cách làm thông thường là: với timeout và các lỗi có thể retry thì dùng retry với exponential backoff, đồng thời đặt số lần retry tối đa; nếu vẫn thất bại thì fallback sang mô hình dự phòng. Nền tảng chuyển đổi mô hình chỉ cần sửa model ID, code không cần thay đổi, chỉ cần ghi mục tiêu fallback thành một model ID khác. Phía nền tảng còn có dự phòng đa node và định tuyến thông minh xuyên khu vực, khi một node gặp sự cố sẽ tự động chuyển đổi.

Làm sao so sánh hiệu quả và chi phí giữa các mô hình khác nhau?

Một API Key là có thể gọi toàn bộ mô hình, chuyển đổi mô hình chỉ cần sửa model ID, code không cần thay đổi, khi so sánh ngang không cần tích hợp riêng cho từng mô hình. Nên dùng cùng một loạt mẫu nghiệp vụ để gọi riêng từng mô hình, ghi lại chất lượng đầu ra và mức sử dụng, sau đó kết hợp với "bảng so sánh giá toàn bộ mô hình" trên website để đối chiếu từng mục giữa giá chính thức và giá của trang này.

API Key phía server nên lưu trữ an toàn như thế nào?

Nên chỉ lưu API Key ở phía server, mang theo qua request header dưới dạng Bearer Token, không viết vào frontend hoặc code phía client. Dữ liệu request và response của nền tảng được truyền mã hóa HTTPS toàn trình, đồng thời cung cấp quản lý quyền hạn cấp doanh nghiệp và audit log, lịch sử gọi có thể truy vết.

Trong tình huống độ đồng thời cao, làm sao đảm bảo gọi ổn định và độ trễ thấp?

Nền tảng dựa vào các trung tâm tính toán tại Hòa Lâm Cách Nhĩ thuộc Nội蒙古, Hami thuộc Tân Cương, Trung Vệ thuộc Ninh Hạ và các địa điểm khác, thông qua thuật toán điều phối tự phát triển để định tuyến thông minh xuyên khu vực và cân bằng tải động, khi một node gặp sự cố sẽ tự động chuyển đổi; người dùng tại các thành phố trọng điểm có thể đạt độ trễ mili giây, cam kết khả dụng dịch vụ 99.9%. Nên phía client kết hợp thêm retry với backoff và fallback đa mô hình.

Làm sao giám sát lượng gọi, chi phí và bất thường?

Nền tảng cung cấp tài khoản thống nhất và một hệ thống tính phí, mức sử dụng minh bạch, số dư vào tài khoản theo thời gian thực, có thể xem chi tiết tiêu thụ bất cứ lúc nào; đồng thời cung cấp chức năng audit log cho việc gọi API, lịch sử gọi có thể truy vết. Người dùng doanh nghiệp nếu cần yêu cầu tuân thủ nghiêm ngặt hơn (quản lý quyền hạn, audit log, v.v.) có thể liên hệ chăm sóc khách hàng để kết nối kinh doanh.