Tài liệu BazaarLink

Bảng giá

BazaarLink định giá mức sử dụng mô hình ở mức tăng bằng 0 (giống hệt với giá niêm yết chính thức của mỗi nhà cung cấp). Phí nền tảng được tính khi nạp tiền (tiền gửi): phí giao dịch 10%, cộng với 5% Đài Loan VAT trên các kênh TWD. Được lập hóa đơn bằng USD với báo giá TWD và hóa đơn thống nhất điện tử. Tự nạp tiền khi bạn sử dụng; doanh nghiệp có thể thu xếp thanh toán hàng tháng (Net-30, có thể thương lượng).

Cách hoạt động

• Consumption (ghi nợ): mỗi lệnh gọi API được tính phí theo mức sử dụng mã thông báo thực tế theo giá niêm yết USD chính thức của nhà cung cấp, được khấu trừ từ số dư của bạn — không cộng dồn, không tính thêm phí tiêu thụ.
• Nạp tiền (tiền gửi): TWD được chuyển đổi thành USD theo tỷ giá bán theo thời gian thực và được thêm vào số dư của bạn; phí giao dịch 10% được tính khi nạp tiền.
• → Thẻ tín dụng: áp dụng phí cố định US$0.60 bổ sung; một biên lai được phát hành. Các kênh
• → TWD: 5% Đài Loan VAT được thêm vào và phát hành hóa đơn thống nhất điện tử Đài Loan.
• → Chuyển khoản ngân hàng: đối với các khoản nạp tiền lớn hơn hoặc dành cho doanh nghiệp, hãy liên hệ với chúng tôi để sắp xếp chuyển khoản ngân hàng và lập hóa đơn tùy chỉnh.
• Invoicing: hóa đơn thống nhất điện tử được hỗ trợ cho quy trình chi phí ở Đài Loan; các công ty cần mua sắm hoặc thanh toán hàng tháng có thể sắp xếp các điều khoản doanh nghiệp (Net-30, có thể thương lượng).

Về tỷ giá hối đoái

Chuyển đổi ngoại hối sử dụng tỷ giá thời gian thực; thanh toán hàng tháng sử dụng tỷ giá tại thời điểm thanh toán (sao kê), trong khi các khoản nạp tiền trả trước chuyển đổi theo tỷ giá tại thời điểm nạp tiền. Tỷ lệ và dấu thời gian được giữ lại cùng với hồ sơ thanh toán.

Bảo vệ thanh toán cho yêu cầu thất bại

Nếu yêu cầu upstream thất bại mà không có dữ liệu sử dụng có thể quyết toán, BazaarLink tự động hoàn lại toàn bộ khoản đã giữ. Lần gọi đó bị tính 0 USD ngay cả khi stream đã bắt đầu trước khi lỗi.

0 token đầu ra không phải lúc nào cũng miễn phí

Nếu yêu cầu kết thúc bình thường và nhà cung cấp trả usage hợp lệ, BazaarLink sẽ quyết toán usage đó. Không nên chỉ dựa vào token đầu ra để xác định miễn phí: phản hồi có 0 token đầu ra vẫn có thể bị tính token đầu vào hoặc chi phí upstream hợp lệ đã báo cáo. Hãy kiểm tra usage.cost hoặc bản ghi Hoạt động để biết khoản phí cuối cùng.

Bắt đầu nhanh

Ba cách tích hợp

Bắt đầu trong vòng 5 phút. BazaarLink hoàn toàn tương thích với OpenAI SDK — chỉ cần thay đổi

Base URL

https://bazaarlink.ai/api/v1

Sử dụng OpenAI SDK

BazaarLink hoàn toàn tương thích với OpenAI SDK. Chỉ cần thay đổi base URL và khóa API — tất cả code khác giữ nguyên.

from openai import OpenAI

client = OpenAI(
    base_url="https://bazaarlink.ai/api/v1",
    api_key="sk-bl-YOUR_API_KEY",
)

completion = client.chat.completions.create(
    model="openai/gpt-4o",
    messages=[
        {"role": "user", "content": "What is the meaning of life?"}
    ],
)

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

Dùng khóa riêng của bạn (BYOK)

Gắn khóa API của nhà cung cấp upstream của riêng bạn (giao diện tương thích OpenAI hoặc Anthropic) vào tài khoản cá nhân hoặc tổ chức — các yêu cầu đủ điều kiện sẽ đi thẳng lên upstream qua khóa của bạn, với hai chế độ dự phòng seamless hoặc strict. Khóa cá nhân quản lý ở tab BYOK trên trang khóa; tổ chức quản lý trong cài đặt tổ chức. Đến cài đặt BYOK →

Lọc nội dung

Bảo vệ nội dung hai chiều cho lưu lượng API của bạn: yêu cầu chứa prompt injection bị chặn (400), dữ liệu nhạy cảm trong yêu cầu và phản hồi (khóa API, số thẻ, số định danh, v.v.) được tự động che. Quy tắc và danh sách miễn trừ có thể tùy chỉnh, kèm thống kê sử dụng. Đến cài đặt lọc nội dung →

Di chuyển từ OpenRouter

API của BazaarLink tương thích với OpenRouter — hầu hết các tích hợp chỉ cần đổi hai giá trị: base URL thành https://bazaarlink.ai/api/v1 và khóa API thành khóa BazaarLink bắt đầu bằng sk-bl-.

1. Cơ sở URL: https://openrouter.ai/api/v1 → https://bazaarlink.ai/api/v1
2. Khóa API: sk-or-... → sk-bl-... (tạo tại /keys)
3. ID mô hình: cùng định dạng provider/model (ví dụ anthropic/claude-sonnet-4.6); danh mục đầy đủ tại GET /api/v1/models
4. Dự phòng models[], tùy chọn định tuyến nhà cung cấp, streaming, gọi công cụ và đầu ra có cấu trúc dùng cùng cấu trúc request

  from openai import OpenAI

  client = OpenAI(
-     base_url="https://openrouter.ai/api/v1",
-     api_key="sk-or-...",
+     base_url="https://bazaarlink.ai/api/v1",
+     api_key="sk-bl-...",
  )

Xác thực

Tất cả yêu cầu API cần header Authorization với khóa API.

Authorization: Bearer sk-bl-YOUR_API_KEY

Lấy khóa API từ bảng điều khiển. Giữ khóa an toàn — không để lộ trong code phía client.

Header tùy chọn

Nguyên tắc

BazaarLink được thiết kế dựa trên ba nguyên tắc cốt lõi:

1. Giao diện thống nhất

Một API, một SDK, hàng trăm mô hình. Chuyển đổi giữa OpenAI, Anthropic, Google Gemini, Meta Llama và các nhà cung cấp khác mà không cần thay đổi code — chỉ thay đổi ID mô hình.

2. Tối ưu giá

BazaarLink tự động định tuyến đến nhà cung cấp hiệu quả chi phí nhất cho mô hình bạn chọn. Bạn chỉ trả cho những gì sử dụng, thanh toán USD với hỗ trợ hóa đơn đầy đủ.

3. Độ sẵn sàng cao

Chuyển đổi dự phòng tự động nghĩa là nếu một nhà cung cấp gặp sự cố, yêu cầu được chuyển hướng liền mạch. Không cần thay đổi code, không có thời gian chết.

Đa phương thức

BazaarLink hỗ trợ đầu vào đa phương thức — gửi hình ảnh, âm thanh và tệp cùng với văn bản đến các mô hình hỗ trợ. Nội dung được chuyển tiếp đến nhà cung cấp upstream.

Phương thức được hỗ trợ

Ví dụ:

# Image — URL or base64 data URI
curl https://bazaarlink.ai/api/v1/chat/completions \
  -H "Authorization: Bearer $BAZAARLINK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"google/gemini-2.5-flash","messages":[{"role":"user","content":[
        {"type":"text","text":"What is in this?"},
        {"type":"image_url","image_url":{"url":"https://example.com/photo.jpg"}}
      ]}]}'

# File / PDF — base64 data URI only, no URL
curl https://bazaarlink.ai/api/v1/chat/completions \
  -H "Authorization: Bearer $BAZAARLINK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"google/gemini-2.5-flash","messages":[{"role":"user","content":[
        {"type":"file","file":{"filename":"doc.pdf","file_data":"data:application/pdf;base64,JVBER..."}},
        {"type":"text","text":"Summarize this."}
      ]}]}'

# Audio — raw base64, no URL. "format" is required
curl https://bazaarlink.ai/api/v1/chat/completions \
  -H "Authorization: Bearer $BAZAARLINK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"google/gemini-2.5-flash","messages":[{"role":"user","content":[
        {"type":"text","text":"Transcribe this."},
        {"type":"input_audio","input_audio":{"data":"UklGRi...","format":"wav"}}
      ]}]}'

# Video — URL (CDN) or base64 data URI
curl https://bazaarlink.ai/api/v1/chat/completions \
  -H "Authorization: Bearer $BAZAARLINK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"google/gemini-2.5-flash","messages":[{"role":"user","content":[
        {"type":"text","text":"Describe this video."},
        {"type":"video_url","video_url":{"url":"https://example.com/clip.mp4"}}
      ]}]}'

Gửi hình ảnh

Sử dụng định dạng mảng content với các phần image_url. Định dạng hỗ trợ: PNG, JPEG, WebP và GIF (bao gồm GIF động). Bạn có thể bao gồm nhiều hình ảnh trong một tin nhắn — mỗi cái là một phần image_url riêng:

curl https://bazaarlink.ai/api/v1/chat/completions \
  -H "Authorization: Bearer sk-bl-YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-4o",
    "messages": [{"role":"user","content":[
      {"type":"text","text":"What is in this image?"},
      {"type":"image_url","image_url":{"url":"https://example.com/photo.jpg","detail":"auto"}}
    ]}]
  }'

Giới hạn

BazaarLink áp dụng hai giới hạn độc lập: giới hạn tốc độ cho số yêu cầu mỗi phút, và giới hạn tín dụng cho chi tiêu tài khoản. Vượt giới hạn tốc độ sẽ nhận HTTP 429; hết tín dụng sẽ nhận HTTP 402.

Giới hạn tốc độ

Giới hạn tốc độ theo người dùng (không theo khóa), đo bằng yêu cầu mỗi phút (RPM). Không có giới hạn hàng ngày. Tier được xác định tự động bởi số dư tín dụng tài khoản.

Khi vượt giới hạn tốc độ, bạn nhận phản hồi 429 với header Retry-After. Triển khai exponential backoff khi thử lại.

Response

Mỗi response thành công đều bao gồm các header rate limit để client có thể theo dõi:

X-RateLimit-Limit: 200        # Max requests per minute for your tier
X-RateLimit-Remaining: 198    # Remaining requests in current window
X-RateLimit-Reset: 1740000060 # Unix timestamp when the window resets
X-Request-Id: chatcmpl-abc123 # Unique request ID for debugging

Giới hạn tín dụng

Phản hồi 402 nghĩa là số dư tài khoản hoặc hạn mức chi tiêu của khóa đã về 0 — không phải do bạn gửi yêu cầu quá nhanh. Phản hồi này không có header rate limit, và nếu giới hạn bị chạm giữa lúc streaming, bạn sẽ nhận sự kiện lỗi SSE thay vì thay đổi mã trạng thái HTTP.

Phanh Khẩn Cấp Cá Nhân

Hạn mức chi tiêu USD cố định theo cửa sổ 1 phút và 1 giờ, áp dụng cho tất cả API key của bạn. Khi vượt ngưỡng, các yêu cầu mới nhận HTTP 429; cửa sổ tự động đặt lại theo ranh giới đồng hồ.

Tạo hình ảnh

Tạo hình ảnh qua /v1/chat/completions với modalities:["image"], hoặc /v1/images/generations tương thích OpenAI DALL·E.

curl -N https://bazaarlink.ai/api/v1/chat/completions \
  -H "Authorization: Bearer $BAZAARLINK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"openai/gpt-5.4-image-2","messages":[{"role":"user","content":"a red cat on a sofa"}],"modalities":["image","text"],"stream":true}'

Luồng đầy đủ (streaming, chỉnh sửa ảnh, giao thức SSE, danh sách mô hình) xem tại API Reference →

Tạo video

Luồng 3 bước không đồng bộ (submit → poll → content). Tạo video mất từ 30 giây đến 5 phút.

curl https://bazaarlink.ai/api/v1/videos \
  -H "Authorization: Bearer $BAZAARLINK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"alibaba/wan2.7-t2v","prompt":"a bird flying over mountains","duration":3}'
# → 202 { "id": "vjob_xxx", "status": "pending" }

Luồng đầy đủ (polling, tải xuống, loại tác vụ, lưu ý) xem tại API Reference →

Đầu vào PDF

Gửi tài liệu PDF trực tiếp trong tin nhắn đến các mô hình hỗ trợ đầu vào PDF gốc (ví dụ: Claude, Gemini). BazaarLink chuyển tệp thẳng đến mô hình — tính phí như input token thông thường, không phụ phí hay bước xử lý thêm.

Định dạng được hỗ trợ

• Tài liệu PDF (văn bản, hình ảnh, bảng, quét)
• URL dữ liệu base64
• Tài liệu nhiều trang
• Chỉ PDF không có mật khẩu

import base64

with open("document.pdf", "rb") as f:
    pdf_data = base64.b64encode(f.read()).decode()

response = client.chat.completions.create(
    model="anthropic/claude-sonnet-4.6",
    messages=[{
        "role": "user",
        "content": [
            {
                "type": "file",
                "file": {
                    "filename": "document.pdf",
                    "file_data": f"data:application/pdf;base64,{pdf_data}",
                },
            },
            {"type": "text", "text": "Summarize this document."},
        ],
    }],
)

Đầu vào video

Gửi tệp video đến các mô hình hỗ trợ đầu vào video để phân tích, tạo chú thích, hoặc trả lời câu hỏi về cảnh và sự kiện. Dùng được URL trực tiếp hoặc base64 data URI — URL hiệu quả hơn cho video công khai; base64 dành cho tệp cục bộ hoặc video riêng tư.

Định dạng được hỗ trợ

response = client.chat.completions.create(
    model="google/gemini-2.5-flash",
    messages=[{
        "role": "user",
        "content": [
            {
                "type": "video_url",
                "video_url": {"url": "https://example.com/video.mp4"},
            },
            {"type": "text", "text": "What is happening in this video?"},
        ],
    }],
)

Tài liệu tham khảo API đầy đủ →

Khóa API quản lý

Khóa quản lý được thiết kế để quản lý khóa theo chương trình. Không thể gọi mô hình AI.

Tạo khóa quản lý

Vào trang Management API Keys và nhấp "Create" — đây là trang riêng, không phải lựa chọn loại trên trang API Keys thông thường.

Liệt kê khóa

GET https://bazaarlink.ai/api/v1/keys
Authorization: Bearer sk-bl-YOUR_MGMT_KEY

# Response
{
  "keys": [
    {
      "id": "clxyz123...",
      "name": "Production Key",
      "keyType": "standard",
      "keyPrefix": "sk-bl-abc1",
      "keySuffix": "XyZ9",
      "enabled": true,
      "spendLimitUsd": 10.00,
      "spendLimitPeriod": "month",
      "expiresAt": null,
      "createdAt": "2026-01-01T00:00:00.000Z",
      "lastUsed": "2026-03-01T12:34:56.000Z",
      "requestCount": 1234,
      "totalTokens": 5678901
    }
  ]
}

Tạo khóa con

POST https://bazaarlink.ai/api/v1/keys
Authorization: Bearer sk-bl-YOUR_MGMT_KEY
Content-Type: application/json

{
  "name": "Agent Key",
  "limit": 10.00,
  "limit_reset": "monthly",
  "expires_at": "2026-12-31T23:59:59Z"
}

# limit_reset: daily | weekly | monthly
# expires_at:  ISO 8601 datetime (optional)

# Response — save the key value, it won't be shown again
{
  "id": "clxyz789...",
  "name": "Agent Key",
  "key": "sk-bl-xyz789abcdef...",
  "keyType": "standard",
  "spendLimitUsd": 10.00,
  "spendLimitPeriod": "month",
  "expiresAt": "2026-12-31T23:59:59.000Z",
  "enabled": true,
  "createdAt": "2026-03-01T00:00:00.000Z"
}

Cập nhật khóa

PATCH https://bazaarlink.ai/api/v1/keys/:id
Authorization: Bearer sk-bl-YOUR_MGMT_KEY
Content-Type: application/json

{"enabled": false}              # disable key
{"spendLimitUsd": 5, "spendLimitPeriod": "week"}  # set spend limit
{"spendLimitUsd": null}         # remove spend limit
# Response: {"updated": true}

Thu hồi khóa

DELETE https://bazaarlink.ai/api/v1/keys/:id
Authorization: Bearer sk-bl-YOUR_MGMT_KEY

# Returns 204 No Content on success

Truy vấn số dư

GET https://bazaarlink.ai/api/v1/credits
Authorization: Bearer sk-bl-YOUR_MGMT_KEY

# Response
{
  "data": {
    "total_credits": 12.345,
    "total_usage": 3.210
  }
}

Truy vấn sử dụng

GET https://bazaarlink.ai/api/v1/usage?period=month
Authorization: Bearer sk-bl-YOUR_MGMT_KEY

# period: day | week | month | year

Ghi nhận ứng dụng

Xác định ứng dụng trong header yêu cầu.

Header khả dụng

from openai import OpenAI

client = OpenAI(
    base_url="https://bazaarlink.ai/api/v1",
    api_key="sk-bl-YOUR_KEY",
    default_headers={
        "HTTP-Referer": "https://yourapp.com",  # Optional: your site URL
        "X-Title": "My Application",             # Optional: your app name
    },
)

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

Mã lỗi

Error Trạng thái

Các endpoint suy luận mô hình trả về một phong bì lỗi tương thích với OpenAI. Trường type có thể thay đổi hoặc bị lược bỏ; hãy dùng trạng thái HTTP và error.code cho logic chương trình thay vì phân tích thông báo.

{
  "error": {
    "message": "Insufficient credits. Please top up to continue.",
    "type": "invalid_request_error",
    "code": "insufficient_credits"
  }
}

HTTP và error.code

Before streaming, the HTTP status identifies the broad failure class. error.code is either that number or a stable string for a specific remedy. Prefer the string code when present, otherwise use the HTTP status.

Mã thanh toán có thể đọc được bằng máy

A 402 can represent different controls. Use these stable codes to choose the correct action.

Stable error.code catalog

These string codes are emitted by public inference and media paths. Branch on the string code when present; the HTTP status remains the broad failure class.

Giới hạn tỷ lệ, ngân sách và phanh khẩn cấp

These controls can reject an otherwise valid request and require different recovery actions.

Compatibility note: rate-limit and emergency-brake paths currently emit numeric error.code values. Use HTTP status, Retry-After, and the documented response message.

Trạng thái tài nguyên video và phương tiện

Video validation commonly returns numeric code 400. Missing jobs return 404, retired models 410, unfinished video content 409, and invalid video byte ranges 416.

Chính sách thử lại

Retry only failures that may recover without changing the request. Honor Retry-After or use exponential backoff with jitter. Do not stack SDK and manual retries.

Xử lý lỗi

import random
import time
from openai import OpenAI, APIStatusError

client = OpenAI(
    base_url="https://bazaarlink.ai/api/v1",
    api_key="sk-bl-YOUR_API_KEY",
    max_retries=0,  # Avoid double retries; this example handles them.
)

RETRYABLE = {429, 502, 503, 504}

for attempt in range(5):
    try:
        response = client.chat.completions.create(
            model="openai/gpt-4.1",
            messages=[{"role": "user", "content": "Hello!"}],
        )
        break
    except APIStatusError as error:
        if error.status_code not in RETRYABLE or attempt == 4:
            raise
        retry_after = error.response.headers.get("Retry-After")
        delay = (
            float(retry_after)
            if retry_after
            else min(8, 0.5 * (2 ** attempt)) + random.uniform(0, 0.25)
        )
        time.sleep(delay)

Định dạng lỗi Streaming

Lỗi xảy ra trước khi stream token trả về phản hồi HTTP lỗi tiêu chuẩn với body JSON.

After a stream starts, the HTTP response is already 200. Parse each SSE data frame and treat a top-level error or choices[0].finish_reason === "error" as a failed, incomplete response.

Nếu stream thất bại giữa chừng, BazaarLink sẽ phát một sự kiện SSE cuối cùng chứa đối tượng error ở cấp cao nhất, theo sau là data: [DONE]. Các chunk được chuyển tiếp nguyên văn từ một số upstream có thể đặt lỗi trên choice (choices[0].finish_reason === "error") — hãy xử lý cả hai trường hợp.

// If the stream fails mid-flight, BazaarLink emits a final SSE event
// with a top-level "error" object, followed by data: [DONE]
data: {"error":{"message":"Upstream stream interrupted. The response is incomplete.","type":"upstream_error","code":502}}

data: [DONE]

// Chunks relayed verbatim from some upstreams may instead carry the error
// inline on the choice: choices[0].finish_reason === "error" with an
// "error" object ({ code, message }) on the choice — handle both shapes.
// Branch on error.code; error.type can vary by failure path.

Gọi công cụ

Gọi công cụ (còn gọi là gọi hàm) cho phép mô hình gọi các hàm bên ngoài mà bạn định nghĩa. Mô hình quyết định khi nào gọi công cụ và tạo tham số có cấu trúc — code của bạn thực thi hàm và trả về kết quả để tiếp tục hội thoại.

Mô hình được hỗ trợ

Hầu hết mô hình tiên tiến hỗ trợ gọi công cụ. Dưới đây là một số lựa chọn phổ biến:

Định nghĩa công cụ

Mỗi công cụ là đối tượng JSON mô tả hàm mô hình có thể gọi. Trường parameters sử dụng JSON Schema.

Tùy chọn tool_choice

Luồng hoàn chỉnh

Gọi công cụ là quy trình đa lượt: (1) gửi yêu cầu với công cụ → (2) mô hình trả về tool_calls → (3) thực thi hàm → (4) gửi kết quả lại → (5) mô hình tạo phản hồi cuối cùng.

curl https://bazaarlink.ai/api/v1/chat/completions \
  -H "Authorization: Bearer $BAZAARLINK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-4.1",
    "messages": [{"role":"user","content":"What is the weather in Taipei?"}],
    "tools": [{
      "type": "function",
      "function": {
        "name": "get_weather",
        "description": "Get current weather for a city",
        "parameters": {
          "type": "object",
          "properties": {
            "city": {"type": "string", "description": "City name"},
            "unit": {"type": "string", "enum": ["celsius", "fahrenheit"]}
          },
          "required": ["city"]
        }
      }
    }],
    "tool_choice": "auto"
  }'
# Response carries tool_calls — run get_weather() yourself, then send the
# result back with role:"tool" (same shape as the Python/TS steps 3-5) to
# get the model's final answer.

Gọi công cụ song song

Một số mô hình có thể gọi nhiều công cụ trong một phản hồi. Xử lý từng lệnh gọi và trả về tất cả kết quả:

# Model may return multiple tool_calls
if message.tool_calls:
    messages = [
        {"role": "user", "content": "Weather and time in Tokyo?"},
        message,
    ]

    for tool_call in message.tool_calls:
        # Execute each function
        if tool_call.function.name == "get_weather":
            result = {"temperature": 22, "condition": "Clear"}
        elif tool_call.function.name == "get_time":
            result = {"time": "2026-02-23T15:30:00+09:00"}

        messages.append({
            "role": "tool",
            "tool_call_id": tool_call.id,
            "content": json.dumps(result),
        })

    # Send all results back at once
    final = client.chat.completions.create(
        model="openai/gpt-4.1",
        messages=messages,
        tools=tools,
    )
    print(final.choices[0].message.content)

Gọi công cụ khi streaming

Khi streaming, các lệnh gọi công cụ đến dưới dạng delta từng phần được đánh chỉ số theo vị trí — tích lũy chuỗi tham số của mỗi delta theo chỉ số cho đến khi finish_reason trở thành "tool_calls", báo hiệu lệnh gọi đã hoàn tất.

# Streaming: tool_calls arrive as partial deltas indexed by position —
# accumulate function.arguments per index until finish_reason == "tool_calls".
stream = client.chat.completions.create(
    model="openai/gpt-4.1",
    messages=[{"role": "user", "content": "What's the weather in Taipei?"}],
    tools=tools,
    tool_choice="auto",
    stream=True,
)

tool_calls = {}
for chunk in stream:
    delta = chunk.choices[0].delta
    if delta.tool_calls:
        for tc in delta.tool_calls:
            entry = tool_calls.setdefault(tc.index, {"id": "", "name": "", "arguments": ""})
            if tc.id:
                entry["id"] = tc.id
            if tc.function.name:
                entry["name"] = tc.function.name
            if tc.function.arguments:
                entry["arguments"] += tc.function.arguments
    if chunk.choices[0].finish_reason == "tool_calls":
        for call in tool_calls.values():
            print(call["name"], json.loads(call["arguments"]))

Vòng lặp Agent đơn giản

Một mẫu chung tiếp tục gọi mô hình khi mô hình còn yêu cầu công cụ, và dừng lại khi mô hình trả về câu trả lời cuối cùng — dùng max_iterations để tránh vòng lặp vô hạn.

# Generic loop: keep calling the model while it keeps requesting tools,
# stop once it returns a plain answer. max_iterations guards against loops.
messages = [{"role": "user", "content": "What's the weather in Taipei, and what time is it there?"}]
max_iterations = 10

for _ in range(max_iterations):
    response = client.chat.completions.create(
        model="openai/gpt-4.1",
        messages=messages,
        tools=tools,
    )
    message = response.choices[0].message
    messages.append(message)

    if not message.tool_calls:
        break  # model gave a final answer

    for tool_call in message.tool_calls:
        args = json.loads(tool_call.function.arguments)
        result = TOOL_MAPPING[tool_call.function.name](**args)
        messages.append({
            "role": "tool",
            "tool_call_id": tool_call.id,
            "content": json.dumps(result),
        })
else:
    print("Warning: max_iterations reached without a final answer")

print(messages[-1].content)

Thực hành tốt nhất khi định nghĩa hàm

• Dùng tên cụ thể, rõ nghĩa — get_weather_forecast thay vì chỉ weather.
• Viết mô tả rõ ràng về chức năng và thời điểm nên dùng — mô hình chỉ dựa vào đoạn văn bản này để quyết định có gọi hay không.
• Giới hạn giá trị bằng enum khi có thể và thêm ví dụ trong mô tả để giảm khả năng tham số bị sai định dạng.
• Chỉ đánh dấu required cho các trường thực sự bắt buộc — trường tùy chọn phải thực sự có thể bỏ qua.

Đầu ra có cấu trúc

Buộc mô hình trả về JSON hợp lệ khớp với schema. Điều này thiết yếu để xây dựng ứng dụng đáng tin cậy phân tích đầu ra mô hình theo chương trình.

Phương pháp 1: response_format (JSON Schema)

để bắt buộc tuân thủ JSON Schema nghiêm ngặt:

curl https://bazaarlink.ai/api/v1/chat/completions \
  -H "Authorization: Bearer $BAZAARLINK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-4.1",
    "messages": [{"role":"user","content":"Review the movie Inception"}],
    "response_format": {
      "type": "json_schema",
      "json_schema": {
        "name": "movie_review",
        "strict": true,
        "schema": {
          "type": "object",
          "properties": {
            "title": {"type": "string"},
            "rating": {"type": "integer", "description": "Rating 1-10"},
            "summary": {"type": "string"},
            "pros": {"type": "array", "items": {"type": "string"}},
            "cons": {"type": "array", "items": {"type": "string"}}
          },
          "required": ["title", "rating", "summary", "pros", "cons"],
          "additionalProperties": false
        }
      }
    }
  }'

Mẹo

• Sử dụng tên thuộc tính rõ ràng, mô tả — mô hình sử dụng chúng làm ngữ cảnh.
• Thêm mô tả vào thuộc tính schema để hướng dẫn mô hình.
• Đặt strict: true để đảm bảo tuân thủ schema (có thể tăng độ trễ nhẹ).
• Giữ schema đơn giản — schema lồng sâu có thể giảm chất lượng đầu ra.
• Thử nghiệm với các mô hình khác nhau — một số xử lý schema phức tạp tốt hơn.

AHỗ trợ điền trước

Thêm một tin nhắn assistant chưa hoàn chỉnh làm mục cuối để yêu cầu tiếp tục trên các tuyến mô hình tương thích.

curl https://bazaarlink.ai/api/v1/chat/completions \
  -H "Authorization: Bearer $BAZAARLINK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "anthropic/claude-sonnet-4.6",
    "messages": [
      {"role":"user","content":"What is the capital of France?"},
      {"role":"assistant","content":"The capital of France is"}
    ]
  }'
# Model continues: " Paris, known for the Eiffel Tower..."

Chuyển đổi tin nhắn

Tự động chuyển đổi tin nhắn để phù hợp với giới hạn ngữ cảnh mô hình. Khi tin nhắn vượt quá cửa sổ ngữ cảnh, chuyển đổi thông minh cô đọng hội thoại bằng cách xóa tin nhắn ở giữa.

Sử dụng

// Enable middle-out on any model
{
  "model": "openai/gpt-4.1",
  "transforms": ["middle-out"],
  "messages": [
    { "role": "system", "content": "You are a helpful assistant." },
    ... // long conversation — middle will be trimmed to fit context
  ]
}

// Disable auto-trimming for small-context models
{ "transforms": [] }

Loại chuyển đổi

Hành vi mặc định

Mô hình có ngữ cảnh ≤8k tự động bật middle-out. Đối với mô hình ngữ cảnh lớn hơn, chọn tham gia rõ ràng.

Không lưu trữ dữ liệu

BazaarLink không lưu trữ nội dung tin nhắn theo mặc định.

Xử lý dữ liệu hiện tại

• Nội dung tin nhắn: không lưu trữ, bị xóa sau xử lý
• Metadata thanh toán: số token, thời gian, ID mô hình
• Nhật ký sử dụng: chỉ thống kê yêu cầu
• Chuyển tiếp upstream: tuân theo chính sách quyền riêng tư của họ

Bộ nhớ đệm Prompt

Bộ nhớ đệm prompt tái sử dụng token prompt đã tính toán, giảm đáng kể chi phí và độ trễ.

Cách hoạt động

Việc có cần cấu hình hay không tùy thuộc vào nhà cung cấp. Các mô hình họ OpenAI tự động cache tiền tố prompt dài và lặp lại — không cần thay đổi request. Các mô hình Claude (Anthropic) chỉ cache khi request chứa điểm ngắt cache_control rõ ràng; BazaarLink không tự thêm điều này thay bạn, nên một request Claude không có marker sẽ không bao giờ được cache. BazaarLink chuyển tiếp nguyên vẹn các cache marker bạn gửi và báo cáo số token cache đọc/ghi thực tế trong phản hồi usage.

# OpenAI-family models: nothing to add, long repeated prefixes cache automatically.
response = client.chat.completions.create(
    model="openai/gpt-4.1",
    messages=[
        {"role": "system", "content": "You are an expert..."},  # cached automatically if long/repeated
        {"role": "user", "content": "Question here"},
    ],
)

# Check cache savings in the response usage
usage = response.usage
print(f"Prompt tokens: {usage.prompt_tokens}")
print(f"Cached tokens: {usage.prompt_tokens_details.cached_tokens}")
print(f"Cache savings: {usage.prompt_tokens_details.cached_tokens / usage.prompt_tokens * 100:.1f}%")

# Claude models: you must mark the block to cache yourself.
response = client.chat.completions.create(
    model="anthropic/claude-sonnet-4.6",
    messages=[
        {
            "role": "system",
            "content": [
                {"type": "text", "text": "You are an expert...", "cache_control": {"type": "ephemeral"}}
            ],
        },  # BazaarLink does not add cache_control on your behalf
        {"role": "user", "content": "Question here"},
    ],
)

usage = response.usage
print(f"Cache read tokens: {getattr(usage, 'cache_read_input_tokens', 0)}")
print(f"Cache write tokens: {getattr(usage, 'cache_creation_input_tokens', 0)}")

Token suy luận

Mô hình suy luận (ví dụ DeepSeek R1, o1 series) suy nghĩ nội bộ trước khi tạo câu trả lời cuối cùng. Các token nội bộ này được tính phí riêng.

Đọc token suy luận từ phản hồi

response = client.chat.completions.create(
    model="deepseek/deepseek-r1",
    messages=[{"role": "user", "content": "Solve: if f(x) = x^2 + 3x, what is f(5)?"}],
)

# Read reasoning tokens from usage
usage = response.usage
print(f"Completion tokens: {usage.completion_tokens}")
if hasattr(usage, "completion_tokens_details"):
    details = usage.completion_tokens_details
    print(f"Reasoning tokens: {details.reasoning_tokens}")
    print(f"Output tokens: {details.accepted_prediction_tokens}")

const response = await client.chat.completions.create({
  model: "openai/o3-mini",
  messages: [{ role: "user", content: "Prove that sqrt(2) is irrational." }],
  // @ts-ignore - BazaarLink extension
  reasoning_effort: "high",  // low | medium | high
});

const usage = response.usage;
console.log("Reasoning tokens:", usage?.completion_tokens_details?.reasoning_tokens);

Điều khiển chế độ suy nghĩ

Một số mô hình hỗ trợ bật/tắt chế độ "suy nghĩ".

# Qwen3: explicitly enable thinking mode
response = client.chat.completions.create(
    model="qwen/qwen3-32b",
    messages=[{"role": "user", "content": "Prove the Pythagorean theorem"}],
    extra_body={"enable_thinking": True},  # opt-in to thinking
)

# usage.completion_tokens_details.reasoning_tokens shows thinking token count

Đối tượng reasoning thống nhất (Formaat mới)

BazaarLink cũng hỗ trợ đối tượng reasoning thống nhất, hoạt động trên tất cả dòng mô hình:

// Claude extended thinking — specify thinking budget in tokens
const response = await client.chat.completions.create({
  model: "anthropic/claude-sonnet-4.5",
  messages: [{ role: "user", content: "Prove the Pythagorean theorem" }],
  // @ts-ignore - BazaarLink extension
  reasoning: { max_tokens: 5000 },
});

// OpenAI o3 — specify effort level
const response2 = await client.chat.completions.create({
  model: "openai/o3",
  messages: [{ role: "user", content: "Solve this math problem..." }],
  // @ts-ignore - BazaarLink extension
  reasoning: { effort: "high" },
});

// Hide thinking content from response (model still thinks)
const response3 = await client.chat.completions.create({
  model: "anthropic/claude-sonnet-4.5",
  messages: [{ role: "user", content: "What is 2+2?" }],
  // @ts-ignore - BazaarLink extension
  reasoning: { max_tokens: 2000, exclude: true },
});

Độ trễ & Hiệu suất

Tối ưu hóa độ trễ phản hồi API AI rất quan trọng cho trải nghiệm người dùng.

Yếu tố ảnh hưởng độ trễ

• Kích thước mô hình: mô hình lớn hơn (70B+) thường chậm hơn
• Tải nhà cung cấp: thay đổi theo nhà cung cấp và thời điểm
• Số lượng token: max_tokens cao hơn = thời gian hoàn thành lâu hơn
• Streaming vs. không streaming: stream: true cung cấp token đầu tiên nhanh hơn
• Độ dài ngữ cảnh: ngữ cảnh rất dài tăng thời gian xử lý

Mẹo tối ưu

• Ưu tiên streaming (stream: true) để cải thiện độ trễ cảm nhận
• Sử dụng biến thể :nitro để chọn nhà cung cấp thông lượng cao
• Chọn mô hình nhỏ hơn (flash/mini/haiku) cho tình huống nhạy cảm độ trễ
• Sử dụng provider.sort: "latency" để tự động chọn nhà cung cấp độ trễ thấp nhất
• Bật bộ nhớ đệm prompt để giảm độ trễ cho yêu cầu lặp lại

import time

# Measure time to first token with streaming
start = time.time()
first_token_time = None

stream = client.chat.completions.create(
    model="google/gemini-2.5-flash",  # Fast model
    messages=[{"role": "user", "content": "Hello!"}],
    stream=True,
)

for chunk in stream:
    if chunk.choices and chunk.choices[0].delta.content and not first_token_time:
        first_token_time = time.time() - start

print(f"Time to first token: {first_token_time:.3f}s")

# Look up per-request latency and throughput after the fact, using the
# generation ID from the response (or the final streamed chunk).
curl "https://bazaarlink.ai/api/v1/generation?id=chatcmpl-abc123" \
  -H "Authorization: Bearer $BAZAARLINK_API_KEY"

# Response
{
  "data": {
    "id": "chatcmpl-abc123",
    "model": "google/gemini-2.5-flash",
    "duration_ms": 842,
    "throughput": 61.2,
    "usage": { "prompt_tokens": 12, "completion_tokens": 48, "total_tokens": 60 }
  }
}

# Use provider.sort for automatic latency optimization
response = client.chat.completions.create(
    model="openai/gpt-4o",
    messages=[{"role": "user", "content": "Hello!"}],
    extra_body={
        "provider": {
            "sort": "latency",  # Always pick lowest-latency provider
        }
    },
)

Tối ưu hóa Uptime

BazaarLink tối đa hóa tính khả dụng API qua nhiều lớp: chuyển đổi dự phòng tự động, circuit breaker và giám sát sức khỏe nhà cung cấp.

Cơ chế khả dụng

• Circuit breaker: tự động phát hiện và cô lập nhà cung cấp thất bại
• Chuyển đổi dự phòng: chuyển liền mạch sang nhà cung cấp dự phòng
• Giám sát sức khỏe: theo dõi liên tục tỷ lệ lỗi và độ trễ
• Logic thử lại: lỗi tạm thời (5xx) được tự động thử lại

Z

# BazaarLink handles failover automatically — no code changes needed.
# Configure fallback models for maximum resilience:

response = client.chat.completions.create(
    model="openai/gpt-4o",       # Primary model
    messages=[{"role": "user", "content": "Hello!"}],
    extra_body={
        "models": [              # Fallback chain
            "openai/gpt-4o",
            "anthropic/claude-sonnet-4.6",
            "google/gemini-2.5-flash",
        ],
        "route": "fallback",     # Enable fallback routing
    },
)

# Check if failover was used (in usage logs)
# "is_failover": true indicates the primary provider was bypassed

Rào chắn

Thêm cơ chế an toàn nội dung vào yêu cầu API để lọc nội dung có hại và thực thi chính sách tuân thủ. BazaarLink hiện chỉ cung cấp rào chắn lọc nội dung có thể tùy chỉnh ở cấp tổ chức (Organization); khóa API cá nhân (không thuộc tổ chức) không có thiết lập tương đương — an toàn nội dung hoàn toàn phụ thuộc vào hệ thống an toàn tích hợp riêng của từng nhà cung cấp mô hình upstream.

Tính năng dự kiến (chưa có cho cả khóa cá nhân lẫn tổ chức)

Hành vi hiện tại

Khóa API cá nhân: tất cả nhà cung cấp upstream có hệ thống an toàn nội dung riêng — phản hồi mô hình kích hoạt bộ lọc nội dung sẽ trả về với finish_reason: "content_filter", và BazaarLink không áp dụng lọc bổ sung. Khóa API tổ chức: org_admin có thể cấu hình quy tắc tùy chỉnh (chặn/che giấu/ghi nhận) tại "Content Filter Guardrails," áp dụng trước khi văn bản đến mô hình.

Cursor IDE

Đặt BazaarLink làm Override URL của OpenAI trong Cursor. Cài đặt với chuyển đổi Responses API tự động, chuẩn hóa định dạng tool, và quy ước tiền tố bz- cho các mô hình Claude.

Thiết lập nhanh

Trong Cursor, mở Settings → Models, sau đó:

1. Đặt Override OpenAI Base URL thành https://bazaarlink.ai/v1
2. Đặt Override OpenAI API Key thành khóa BazaarLink sk-bl-... của bạn
3. Thêm tên mô hình mong muốn — xem bên dưới cho Claude (tiền tố bz-).

Tiền tố bz- (cho mô hình Claude)

Kiểm tra phía client của Cursor sẽ định tuyến mọi tên mô hình bắt đầu bằng claude- qua tích hợp Anthropic riêng của Cursor, bỏ qua Override URL của bạn. Để buộc Cursor gửi yêu cầu đến BazaarLink, thêm tiền tố bz- vào tên mô hình. Server gỡ tiền tố và phân giải phần còn lại qua alias map.

Các biến thể dấu chấm/gạch ngang được chuẩn hóa: bz-claude-sonnet-4.6 và bz-claude-sonnet-4-6 đều phân giải đến cùng mô hình.

Biến môi trường CURSOR_MODEL_MAP (override của vận hành)

Với BazaarLink tự host, đặt biến môi trường này để ánh xạ lại tên model phía Cursor sang canonical id của danh mục:

CURSOR_MODEL_MAP=gpt-claude-sonnet:anthropic/claude-sonnet-4.6,gpt-opus:anthropic/claude-opus-4.7

Bây giờ gpt-claude-sonnet được nhập trong Cursor sẽ ánh xạ thành anthropic/claude-sonnet-4.6 ở phía server. Hữu ích khi bạn muốn Cursor nghĩ một mô hình thuộc họ GPT (để định tuyến qua Override URL) trong khi thực tế bạn phục vụ Claude.

Điều gì xảy ra tự động

Khi một yêu cầu đến /api/v1/chat/completions, BazaarLink áp dụng các chuyển đổi tương thích này một cách trong suốt — bạn không cần làm gì phía client:

• Tự phát hiện thân Responses API — nếu thân có input thay vì messages, nó được chuyển sang dạng Chat Completions (Cursor gửi định dạng Responses API cho các mô hình họ GPT).
• Bọc các định nghĩa tool phẳng — Cursor Agent gửi { name, description, parameters } không có wrapper function. Chúng tôi bọc để Anthropic không từ chối với Tool '' not found in provided tools.
• Ép định dạng tool_choice không đúng — Cursor gửi { type: "auto" } (dạng object, không có function). Quy chuẩn OpenAI yêu cầu dạng chuỗi cho auto/none/required, nên chúng tôi ép kiểu.
• Loại bỏ các trường chỉ dành cho OpenAI khi định tuyến đến nhà cung cấp không phải OpenAI — parallel_tool_calls, logprobs, top_logprobs, logit_bias, service_tier, user được loại bỏ trước khi chuyển tiếp (nếu không Anthropic trả về 400).
• Ánh xạ max_output_tokens → max_tokens và loại bỏ các trường chỉ dành cho Responses-API (previous_response_id, truncation, background, store). Trường reasoning được giữ lại cho các thân Chat-Completions gốc.

Chế độ Cursor Agent

Gọi tool hoạt động qua luồng tool-call Chat Completions tiêu chuẩn. Cursor gửi tools (Shell, Read, Write, Grep, v.v.) với tool_choice: "auto"; BazaarLink chuyển tiếp đến nhà cung cấp bạn chọn, nơi quyết định có gọi tool hay không. Các lời gọi tool trả về dưới dạng các delta tool_calls tiêu chuẩn của OpenAI; Cursor thực thi cục bộ và tiếp tục cuộc hội thoại. Hoạt động giống nhau cho dù bạn chọn gpt-4o (OpenAI gốc) hay bz-claude-sonnet-4.6.

Định tuyến mô hình

BazaarLink sử dụng định dạng provider/model-name để định tuyến yêu cầu đến nhà cung cấp upstream chính xác. Điều này cho bạn truy cập các mô hình chính qua một endpoint API duy nhất.

Định dạng ID mô hình

{provider}/{model-name}

# Examples
openai/gpt-5.4-mini
anthropic/claude-sonnet-4.6
google/gemini-3-flash-preview
deepseek/deepseek-v3.2

Ưu tiên định tuyến

Khi bạn gửi yêu cầu, BazaarLink xác định nhà cung cấp upstream theo thứ tự sau:

1. Khớp chính xác — tìm route mô hình khớp với ID mô hình đầy đủ
2. Wildcard nhà cung cấp — fallback đến route provider/* (ví dụ openai/*)
3. Wildcard toàn cục — fallback đến route * wildcard
4. Khóa nhà cung cấp mặc định — chỉ với mô hình đã có trong danh mục, dùng khóa đang bật và được đánh dấu mặc định

Xem tất cả mô hình khả dụng trên trang Mô hình.

Bộ định tuyến tự động

Auto Router v3 chấm yêu cầu vào một trong 14 tier tác vụ rồi dùng primary và chuỗi fallback hiện được cấu hình cho tier đó. Bảng trả phí và miễn phí được quản lý riêng trong trang admin.

• auto — dùng bảng định tuyến trả phí; mô hình thực tế hoàn thành yêu cầu được tính theo giá công khai.
• auto:free — dùng bảng định tuyến miễn phí; trong hạn mức có phí 0 USD. Khi hết hạn mức, tài khoản có số dư có thể chuyển sang auto trả phí nếu chưa tắt fallback trả phí.

Cách sử dụng

Đặt model thành "auto" (trả phí) hoặc "auto:free" (miễn phí) để bật định tuyến tự động:

curl https://bazaarlink.ai/api/v1/chat/completions \
  -H "Authorization: Bearer $BAZAARLINK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"auto","messages":[{"role":"user","content":"Review this TypeScript function"}]}'

Cách v3 chọn tier

Tier chung gồm simple, standard, complex, reasoning. Tier chuyên biệt gồm coding, vision, image, video, data, search, social, email, calendar, trading. Kết quả sát biên có độ tin cậy thấp được nâng lên một bậc.

• Chấm tier: messages, tools, độ dài, từ khóa và tín hiệu cấu trúc chọn một trong 14 tier
• Quy tắc cứng: hình ảnh, suy luận hình thức và tác vụ chuyên biệt có thể chọn tier trực tiếp
• Tra route: đọc primary và tối đa 5 fallback hiện tại; tier bị tắt trả về 503
• Thực thi: thử primary rồi các fallback theo thứ tự cấu hình
• Theo dõi phản hồi: mô hình được chọn được trả về trong body phản hồi và header X-Auto-Resolved-Model

Bảng mô hình hiện tại

Các bảng dưới đây đọc cùng cấu hình trực tiếp mà inference và admin sử dụng. Primary, thứ tự fallback và trạng thái từng tier có thể đổi mà không cần triển khai lại.

auto

auto:free

Một số mô hình cung cấp bậc miễn phí có giới hạn tốc độ. Quyền miễn phí do nền tảng cấp theo từng mô hình — gọi mô hình bằng ID thông thường; hậu tố :free chỉ là bí danh tùy chọn (thêm vào mô hình trả phí không làm nó miễn phí).

Biến thể mô hình

Thêm hậu tố vào bất kỳ ID mô hình nào để thay đổi hành vi định tuyến. BazaarLink hỗ trợ 7 loại biến thể.

ID mô hình độc lập

Các biến thể này tồn tại như mô hình riêng biệt với giá và khả năng riêng.

:free
:extended
:thinking
:exacto

Phím tắt định tuyến

Các hậu tố này thay đổi lựa chọn nhà cung cấp mà không thay đổi danh tính mô hình.

:floor   # lowest listed input price first
:nitro   # throughput-oriented shortcut
:online  # enable web-search routing

Hành vi đa nhà cung cấp

Đối với upstream hỗ trợ biến thể, hậu tố được chuyển tiếp nguyên trạng. Đối với nhà cung cấp trực tiếp, hậu tố bị loại bỏ và BazaarLink xử lý định tuyến cục bộ.

Mô hình miễn phí

Một số mô hình cung cấp bậc miễn phí có giới hạn tốc độ. Quyền miễn phí do nền tảng cấp theo từng mô hình — gọi mô hình bằng ID thông thường; hậu tố :free chỉ là bí danh tùy chọn (thêm vào mô hình trả phí không làm nó miễn phí).

• Gọi ID mô hình thông thường (ví dụ deepseek/deepseek-v4-flash). Yêu cầu trong hạn mức miễn phí được phục vụ miễn phí tự động.
• Mức dùng miễn phí bị giới hạn theo người dùng bằng số yêu cầu mỗi phút và trần hằng ngày. Giới hạn thay đổi theo hạng tài khoản (chưa nạp / đã nạp).
• Khi vượt hạn mức miễn phí và còn tín dụng, yêu cầu tự động tiếp tục ở bậc trả phí theo giá niêm yết. Gửi X-Free-Fallback: false để tắt chuyển tiếp tự động và nhận 429 thay thế. Không có tín dụng, yêu cầu vượt hạn mức trả về 429.
• GET /api/v1/models liệt kê mục :free cho mỗi mô hình có bậc miễn phí; auto:free luôn định tuyến đến một mô hình miễn phí.

Mô hình đang có hạn mức miễn phí

Gọi trực tiếp các model ID này để dùng hạn mức miễn phí. Danh sách thay đổi theo thời gian — hãy truy vấn API để lấy bản mới nhất.

deepseek/deepseek-v4-flash

Giới hạn hạn mức miễn phí

Ngân sách hằng ngày = ngân sách yêu cầu ở trên × hệ số hạng tài khoản, tính riêng cho từng mô hình miễn phí. auto:free còn áp thêm giới hạn song song theo IP. Từng mô hình có thể được đặt giới hạn chặt hơn hoặc rộng hơn; giá trị thực tế hiển thị ở khối "Hạn mức miễn phí" trên trang mô hình.

Sau khi hết hạn mức miễn phí

Khi hết hạn mức, nếu tài khoản còn số dư, yêu cầu sẽ tự động tiếp tục theo giá trả phí của mô hình đó — dịch vụ không gián đoạn và tính phí đúng như một lệnh gọi trả phí thông thường. Nếu bạn muốn lỗi thay vì bị tính phí, hãy gửi header X-Free-Fallback: false hoặc tắt tự động chuyển trong cài đặt khóa; khi đó bạn nhận 429. Không có số dư thì yêu cầu vượt hạn mức luôn trả về 429.

# Return 429 instead of switching to paid routing
-H "X-Free-Fallback: false"

Quản lý tổ chức

Tổ chức BazaarLink sử dụng kiến trúc ba cấp: Tổ chức → Nhóm → Thành viên. Tín dụng lưu ở cấp tổ chức; mỗi nhóm và thành viên có thể có giới hạn chi tiêu hàng tháng.

Hệ thống ngân sách ba cấp

Mỗi yêu cầu API được kiểm tra ba lớp ngân sách. Vượt bất kỳ lớp nào trả về HTTP 429:

1. Ngân sách hàng tháng thành viên (OrgMember.monthlyBudget)
2. Ngân sách hàng tháng nhóm (Team.monthlyBudget)
3. Số dư tín dụng tổ chức (Organization.credits)

Báo cáo sử dụng

Trang Báo cáo cung cấp phân tích chi tiêu hàng tháng theo bốn chiều:

• Tổng quan: tổng chi tiêu, tỷ lệ lợi nhuận, biểu đồ xu hướng hàng ngày
• Theo nhóm: chi tiêu theo nhóm, tỷ lệ %, phân tích mô hình
• Theo mô hình: chi tiêu theo mô hình, giá trung bình
• Theo thành viên: chi tiêu theo thành viên — chỉ org_admin

Tất cả chế độ xem hỗ trợ xuất CSV với tiền tố BOM cho Excel.

Tạo & Quản lý tổ chức

1. Vào Cài đặt → Tổ chức → Tạo tổ chức mới
2. Tạo nhóm trong cổng tổ chức
3. Mời thành viên bằng email, gán vai trò và nhóm
4. Phát hành khóa API cho thành viên
5. Xem trang Báo cáo để xem chi tiêu hàng tháng
6. Xem trang Báo cáo để biết chi tiêu hàng tháng được chia theo Nhóm, Người mẫu hoặc Thành viên

Vai trò thành viên

Tổ chức có thể quản lý những gì khác?

Ngoài các thành viên và nhóm, khu vực quản lý tổ chức còn cung cấp:

• API keys and model restrictions
• Content filtering before text reaches a model
• Allowed Models by organization, team, member, or key
• Monthly budgets and spend emergency brakes
• Reports, billing, change logs, and security logs
• Education sessions and quotas for eligible organizations
• Các kế hoạch của tổ chức: các tổ chức giáo dục có thể quản lý thêm các buổi học và chỉ tiêu của sinh viên

curl https://bazaarlink.ai/api/v1/orgs \
  -H "Authorization: Bearer sk-bl-YOUR_MANAGEMENT_KEY"

# Create a team
curl https://bazaarlink.ai/api/v1/orgs/{orgId}/teams \
  -X POST \
  -H "Authorization: Bearer sk-bl-YOUR_MANAGEMENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Engineering", "costCenterCode": "ENG-001", "monthlyBudget": 500}'

# Add a member
curl https://bazaarlink.ai/api/v1/orgs/{orgId}/members \
  -X POST \
  -H "Authorization: Bearer sk-bl-YOUR_MANAGEMENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email": "alice@example.com", "role": "member", "monthlyBudget": 50}'

# Remove a member
curl https://bazaarlink.ai/api/v1/orgs/{orgId}/members/{memberId} \
  -X DELETE \
  -H "Authorization: Bearer sk-bl-YOUR_MANAGEMENT_KEY"

# Monthly overview via management key
curl "https://bazaarlink.ai/api/orgs/{orgId}/reports/overview?year=2026&month=3" \
  -H "Authorization: Bearer sk-bl-YOUR_MANAGEMENT_KEY"

# By-team breakdown
curl "https://bazaarlink.ai/api/orgs/{orgId}/reports/by-team?year=2026&month=3" \
  -H "Authorization: Bearer sk-bl-YOUR_MANAGEMENT_KEY"

# Export CSV (downloads file)
curl "https://bazaarlink.ai/api/orgs/{orgId}/reports/export?year=2026&month=3&view=by-team" \
  -H "Authorization: Bearer sk-bl-YOUR_MANAGEMENT_KEY" \
  -o report.csv

Tham chiếu phản hồi lỗi

Mô hình được phép (Whitelist)

Hạn chế những mô hình mà tổ chức, nhóm hoặc thành viên cá nhân của bạn có thể gọi. Hữu ích để chặn các mô hình đắt tiền hoặc chưa được kiểm duyệt, áp dụng tiêu chuẩn mô hình, hoặc giới hạn một nhóm chỉ dùng một nhà cung cấp duy nhất.

Cách hoạt động

• Ba tầng độc lập — Tổ chức, Nhóm, Thành viên — mỗi tầng có danh sách riêng (String[] trong cơ sở dữ liệu).
• Khi cả ba tầng đều rỗng, mọi mô hình đều được phép (hành vi mặc định).
• Khi một hoặc nhiều tầng không rỗng, danh sách hiệu lực là giao của các tầng không rỗng — một mô hình phải được phép ở mọi tầng có hạn chế thì mới được thông qua.
• Thay đổi có hiệu lực trong vài giây (cache bộ nhớ 60s + cache Redis 5 phút; cả hai đều bị xóa khi cập nhật).

Định dạng pattern

• Khớp chính xác — ví dụ openai/gpt-4o (chỉ riêng mô hình này).
• Wildcard nhà cung cấp — ví dụ openai/* (mọi mô hình dưới prefix openai/).
• Chỉ chữ thường. Tối đa 200 mục mỗi danh sách, 100 ký tự mỗi mục.

Nơi quản lý

Org Portal → Allowed Models. org_admin có thể chỉnh sửa danh sách org / team / member; team_admin có thể chỉnh sửa nhóm của mình và các thành viên trong nhóm đó.

Phản hồi lỗi khi bị chặn

Cuộc gọi đến mô hình không được phép trả về HTTP 403 với body sau:

HTTP/1.1 403 Forbidden
Content-Type: application/json

{
  "error": {
    "message": "Model is not allowed for this account",
    "code": "model_not_allowed"
  }
}

API quản lý

Tất cả endpoint chấp nhận Web Session hoặc Bearer Management Key (sk-bl-...). PATCH thay thế toàn bộ danh sách; truyền [] để xóa.

# Org-level list
GET    /api/orgs/:orgId/allowed-models
PATCH  /api/orgs/:orgId/allowed-models

# Team-level list
GET    /api/orgs/:orgId/teams/:teamId/allowed-models
PATCH  /api/orgs/:orgId/teams/:teamId/allowed-models

# Member-level list
GET    /api/orgs/:orgId/members/:memberId/allowed-models
PATCH  /api/orgs/:orgId/members/:memberId/allowed-models

# Example: restrict an org to OpenAI + a specific Anthropic model
curl -X PATCH https://bazaarlink.ai/api/orgs/$ORG_ID/allowed-models \
  -H "Authorization: Bearer sk-bl-..." \
  -H "Content-Type: application/json" \
  -d '{"allowedModels": ["openai/*", "anthropic/claude-sonnet-4.6"]}'

Cầu dao chi tiêu (Spend Kill Switch)

Một mức trần chi tiêu theo cửa sổ kép, chặn các yêu cầu tiếp theo khi chi phí upstream tăng đột biến. Được thiết kế để khống chế các script chạy loạn, vòng lặp vô hạn, hoặc lạm dụng key bị đánh cắp trước khi gây tổn thất tiền thực.

Cách hoạt động

• Hai cửa sổ cố định được theo dõi trong Redis cho mỗi scope: chi phí upstream 1 phút và 1 giờ (USD).
• Nếu chi tiêu của một trong hai cửa sổ chạm ngưỡng, mọi yêu cầu tiếp theo trong scope đó sẽ bị từ chối cho đến khi cửa sổ đặt lại.
• Mặc định: $5 / phút, $20 / giờ, bật theo mặc định.
• Bộ đếm sống trong Redis với TTL — phục hồi tự động, không cần reset thủ công cho các trip ở cấp org/team/member.

Scopes (member ghi đè team ghi đè org)

Mỗi tầng có thể đặt ngưỡng riêng. Thứ tự phân giải là member → team → org → mặc định nền tảng — giá trị non-null đầu tiên thắng cho mỗi field (cbEnabled, cbMinuteUsd, cbHourlyUsd).

• Cấp Org — áp dụng cho tất cả khóa thuộc tổ chức. Đặt trong Org Portal → Circuit Breaker.
• Cấp Team — áp dụng cho tất cả khóa được gắn thẻ vào nhóm đó. Ghi đè org cho các khóa này.
• Cấp Member — chỉ áp dụng cho các khóa được gắn thẻ vào thành viên đó. Ghi đè team và org.

Hành vi khi trip

Khi bị trip, các yêu cầu thất bại nhanh (không thực hiện cuộc gọi upstream nào). Phản hồi là HTTP 429 với body sau:

HTTP/1.1 429 Too Many Requests
Content-Type: application/json

{
  "error": {
    "message": "Spend circuit breaker tripped at member scope (minute window: $5.2341 ≥ $5.00). Try again later or contact your organization owner."
  }
}

Nhật ký audit

Mọi sự kiện trip và mọi thay đổi cấu hình đều được ghi lại:

• Sự kiện trip — actions org.cb.tripped / team.cb.tripped / org_member.cb.tripped. Khử trùng lặp thành một entry mỗi scope+window mỗi giờ, để một trip kéo dài không làm tràn nhật ký.
• Thay đổi cấu hình — actions org.cb.update / team.cb.update / org_member.cb.update. Ghi lại giá trị before/after kèm theo actor.

API quản lý

Org admin có thể đọc và cập nhật cài đặt qua API. Tất cả endpoint chấp nhận Web Session hoặc Bearer Management Key (sk-bl-...). Gửi bất kỳ tập con field nào trong body PATCH; null xóa một field và quay về tầng cha.

# Org-level config
GET    /api/orgs/:orgId/circuit-breaker
PATCH  /api/orgs/:orgId/circuit-breaker

# Team-level config
GET    /api/orgs/:orgId/teams/:teamId/circuit-breaker
PATCH  /api/orgs/:orgId/teams/:teamId/circuit-breaker

# Member-level config
GET    /api/orgs/:orgId/members/:memberId/circuit-breaker
PATCH  /api/orgs/:orgId/members/:memberId/circuit-breaker

# Example: tighten the org-level cap to $2/min, $10/hr
curl -X PATCH https://bazaarlink.ai/api/orgs/$ORG_ID/circuit-breaker \
  -H "Authorization: Bearer sk-bl-..." \
  -H "Content-Type: application/json" \
  -d '{"cbMinuteUsd": 2, "cbHourlyUsd": 10, "cbEnabled": true}'

# GET response (org scope)
{
  "settings":         { "cbEnabled": true, "cbMinuteUsd": 2,  "cbHourlyUsd": 10  },
  "resolvedSettings": { "cbEnabled": true, "cbMinuteUsd": 2,  "cbHourlyUsd": 10  },
  "liveSpend":        { "minuteSpend": 0.4123, "hourSpend": 3.8721 }
}

Xoay vòng khóa API

Xoay vòng khóa API định kỳ là thực hành bảo mật tốt. BazaarLink hỗ trợ xoay vòng không đình chỉ.

Các bước xoay vòng

1. Tạo khóa API mới
2. Cập nhật ứng dụng sử dụng khóa mới
3. Xác minh khóa mới hoạt động
4. Vô hiệu hóa khóa cũ

# Key CRUD via Bearer auth requires a MANAGEMENT key (keyType: "management").
# Standard keys get 403 on /api/v1/keys — create a management key first,
# or rotate keys from the dashboard UI instead.

# Step 1: Create new key (management key auth)
POST https://bazaarlink.ai/api/v1/keys
Authorization: Bearer $BL_MANAGEMENT_KEY
{"name": "Production v2"}
# → saves new key: sk-bl-NEW_KEY_VALUE

# Step 2: Update your application
# export BAZAARLINK_API_KEY=sk-bl-NEW_KEY_VALUE

# Step 3: Verify new key works
curl https://bazaarlink.ai/api/v1/models \
  -H "Authorization: Bearer sk-bl-NEW_KEY_VALUE"

# Step 4: Revoke old key (management key auth again)
DELETE https://bazaarlink.ai/api/v1/keys/:old_key_id
Authorization: Bearer $BL_MANAGEMENT_KEY

Xuất hoạt động

Tải lịch sử sử dụng API đầy đủ dạng CSV.

Xuất CSV

Đăng nhập và vào trang Nhật ký. Nhấp Xuất CSV.

Cột CSV

API sử dụng JSON

Truy vấn thống kê tổng hợp theo chương trình:

# Query usage data (grouped / aggregated)
GET https://bazaarlink.ai/api/v1/usage
Authorization: Bearer sk-bl-YOUR_KEY

# With period filtering (day | week | month | year)
GET https://bazaarlink.ai/api/v1/usage?period=month

# Response
{
  "period": "month",
  "since": "2025-01-01T00:00:00.000Z",
  "credits": 10.5000,
  "totals": {
    "spend": 0.1812,
    "requests": 309,
    "tokens": 161200,
    "promptTokens": 95000,
    "completionTokens": 66200
  },
  "byModel": [{ "model": "openai/gpt-4o", "spend": 0.0028, "tokens": 1200, "requests": 5 }],
  "byKey":   [{ "keyName": "My Agent", "spend": 0.0028, "tokens": 1200, "requests": 5 }],
  "byApp":   [{ "appName": "MyApp", "spend": 0.0015, "tokens": 600, "requests": 3 }],
  "timeSeries": [{ "date": "2025-01-15", "model": "openai/gpt-4o", "cost": 0.0012, "tokens": 500, "requests": 2 }]
}

Kế toán sử dụng

Truy vấn thống kê sử dụng chi tiết qua API.

Tham chiếu trường phản hồi

import httpx

# Aggregated stats (Bearer token — period: day | week | month | year)
response = httpx.get(
    "https://bazaarlink.ai/api/v1/usage",
    headers={"Authorization": "Bearer sk-bl-YOUR_KEY"},
    params={"period": "month"},
)

data = response.json()
totals = data["totals"]
print("This month: US$%.4f  (%d requests)" % (totals["spend"], totals["requests"]))

# Cost breakdown by model
for m in data["byModel"]:
    print("  %s: US$%.4f  (%d reqs, %d tokens)" % (m["model"], m["spend"], m["requests"], m["tokens"]))

Kế hoạch tổ chức

Gói Institution cho phép bất kỳ tổ chức nào (trường học, doanh nghiệp, hội nghị, cơ quan chính phủ, v.v.) cấp các session token ngắn hạn cho thành viên từ một khóa cấp tổ chức duy nhất. Thành viên không cần tạo tài khoản trên nền tảng. Tổ chức kiểm soát những thành viên nào có thể yêu cầu token theo domain email (ví dụ nthu.edu.tw); toàn bộ mức sử dụng được tính phí vào tài khoản của tổ chức. Trang này sử dụng kịch bản giáo dục làm ví dụ — cơ chế tương tự áp dụng cho bất kỳ tổ chức nào cần truy cập tạm thời ngắn hạn cho nhiều người dùng.

Tổng quan kiến trúc

• Khóa tổ chức Mã thông báo phiên thành viên — Bắt đầu bằng sk-edu-. Được tạo bởi org_admin trên trang khóa của tổ chức. Không thể dùng trực tiếp làm Bearer token để gọi API — gọi trực tiếp sẽ trả về 403.
• — Bắt đầu bằng edu-sess-. Học sinh nhận được sau khi xác minh email. Thời hạn mặc định là 24 giờ; có thể bị thu hồi bởi quản trị viên tổ chức.
• Tên miền được phép — Tổ chức cấu hình các domain email nào (khớp chính xác, không bypass theo hậu tố) có thể yêu cầu session.
• Phân bổ sử dụng — Mọi yêu cầu của học sinh đều được tính phí vào tài khoản tổ chức. Mức sử dụng có thể xem theo từng session và theo từng email trong bảng điều khiển tổ chức.

Bước 1 — Quản trị viên nền tảng đặt loại tổ chức là Education

Từ sales@bazaarlink.ai / support@bazaarlink.ai, tìm tổ chức mục tiêu, chuyển sang tab "Org Type", chọn Education và đặt các domain email được phép:

{
  "orgType": "education",
  "eduConfig": {
    "allowedDomains": ["nthu.edu.tw", "student.nthu.edu.tw"],
    "sessionTtlSeconds": 86400,
    "verificationTtlSeconds": 900,
    "maxSessionsPerEmailPerKey": 5
  }
}

Bước 2 — Quản trị viên tổ chức tạo Institution Key

Trên trang API Keys của tổ chức, chọn "Education" làm loại khóa khi tạo khóa mới. Hệ thống sinh ra khóa sk-edu-... và chỉ hiển thị MỘT LẦN — hãy lưu lại và phân phối qua các kênh chính thức của bạn cho học sinh của tổ chức đó.

Bước 3 — Học sinh yêu cầu mã xác minh

Học sinh truy cập /access và nhập khóa edu + email trường của họ; hoặc gọi API trực tiếp:

curl -X POST https://bazaarlink.ai/api/edu/request-code \
  -H "Content-Type: application/json" \
  -d '{
    "key": "sk-edu-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
    "email": "alice@nthu.edu.tw"
  }'

# Success (incl. unknown key/email — enumeration defence) → {"ok":true,"sent":true}
# Rate limit / resend cooldown → 429 {"error":"rate_limited"} or {"error":"cooldown"}
# Sends a 6-digit verification code to the email; default 15-minute lifetime

Bước 4 — Học sinh nộp mã để đổi lấy session token

curl -X POST https://bazaarlink.ai/api/edu/verify \
  -H "Content-Type: application/json" \
  -d '{
    "key":   "sk-edu-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
    "email": "alice@nthu.edu.tw",
    "code":  "646291"
  }'

# Success → 200
{
  "token":     "edu-sess-827d11a1ec67d175cfd4f67f929261f4",
  "expiresAt": "2026-05-04T11:16:00.163Z",
  "organization": { "id": "...", "name": "NTHU AI Lab" }
}

# Wrong code → 400 {"error":"invalid"}
# 5 wrong attempts → 429 {"error":"too_many_attempts"} (code invalidated; re-request)

Bước 5 — Sử dụng session token để gọi API

Sử dụng token edu-sess-... làm Bearer token cho bất kỳ endpoint chat / completions / embeddings nào:

curl -X POST https://bazaarlink.ai/api/v1/chat/completions \
  -H "Authorization: Bearer edu-sess-827d11a1ec67d175cfd4f67f929261f4" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "anthropic/claude-haiku-4.5",
    "messages": [{"role": "user", "content": "Hello"}]
  }'

Bảng điều khiển tổ chức — giám sát và thu hồi

Các tổ chức loại Education có thêm tab Education ở thanh điều hướng bên, cung cấp:

• Cài đặt — Điều chỉnh các domain được phép, TTL, số session tối đa cho mỗi email cho mỗi khóa, và hạn mức request / token / USD trên mỗi session.
• Phiên — Liệt kê tất cả các session đang hoạt động / hết hạn / đã thu hồi; lọc theo email; thu hồi từng session riêng lẻ.
• Số liệu thống kê sử dụng — Số lần gọi, lượng token tiêu thụ và chi phí tích lũy theo từng session.

Bảo mật và giới hạn

Tính phí và quy kết mức sử dụng

Mọi yêu cầu được thực hiện qua session token đều được tính phí 100% cho tổ chức sở hữu khóa edu, phù hợp với cách các nhà cung cấp upstream (OpenAI / Anthropic / v.v.) tính phí (theo token). Bảng điều khiển tổ chức hỗ trợ phân tích chi tiết theo session, theo email và theo khóa.

Phản hồi

Giúp chúng tôi cải thiện BazaarLink bằng cách báo cáo vấn đề, lỗi hoặc đề xuất.

Cách báo cáo

Cần bao gồm

• ID yêu cầu (từ trường id phản hồi)
• Mô hình sử dụng và tham số gửi
• Hành vi mong đợi so với thực tế
• Thời gian và tần suất vấn đề
• Thông báo lỗi hoặc mã trạng thái HTTP

Truy cập trang Liên hệ để gửi phản hồi.

FAQ