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.
• → Phương thức thanh toán và phí theo từng kênh được hiển thị tại trang thanh toán trực tiếp.
• → Kênh TWD đủ điều kiện hiển thị thuế áp dụng và điều kiện hóa đơn điện tử Đài Loan trước khi trả tiền.
• → 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.
• Hóa đơn chỉ có qua kênh đang được cung cấp và đánh dấu đủ điều kiện, hoặc theo điều khoản doanh nghiệp đã xác nhận. Nếu cần mã số thuế, báo giá hoặc thanh toán hàng tháng, hãy liên hệ kinh doanh trước khi trả tiền.

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í

usage.cost là số USD tính cho yêu cầu. Phản hồi có 0 output token vẫn có thể bị tính input token; xem usage.cost hoặc bản ghi Activity để biết số tiền 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

Với các yêu cầu dài hơn 100 giây, nên dùng stream:true. Với yêu cầu không stream, sau khoảng 12 giây (giá trị mặc định, có thể điều chỉnh qua cấu hình deployment), hệ thống sẽ trả về 200 trước và bắt đầu gửi khoảng trắng keepalive; nếu xảy ra lỗi sau đó, lỗi sẽ được trả về dưới dạng 200 + error JSON. Keepalive là khoảng trắng trước JSON body và parser JSON tiêu chuẩn sẽ bỏ qua phần này.

Base URL

https://api.bazaarlink.ai/v1

api.bazaarlink.ai là điểm vào chỉ dành cho API, được triển khai tách biệt với trang web. Base URL trước đây https://bazaarlink.ai/api/v1 vẫn được hỗ trợ đầy đủ — các tích hợp hiện có không cần thay đổi.

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://api.bazaarlink.ai/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)

Kết nối khóa API upstream với tài khoản cá nhân hoặc tổ chức. Yêu cầu đủ điều kiện sẽ dùng khóa của bạn trước. Sau lỗi upstream, yêu cầu có thể thử một nguồn khả dụng khác; nếu không có, yêu cầu sẽ trả lỗi. Quản lý khóa cá nhân ở trang khóa và khóa tổ chức 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 →

Tìm kiếm web (:online)

Tìm kiếm web trước khi model trả lời và cung cấp kết quả tìm kiếm cho model làm tài liệu tham khảo. Phù hợp với câu hỏi cần thông tin mới nhất như tin tức, giá cả, chính sách hoặc sản phẩm vừa phát hành.

Endpoint được hỗ trợ

• POST /api/v1/chat/completions
• POST /api/v1/messages
• POST /api/v1/responses

Hỗ trợ cả streaming (stream: true) và non-streaming.

Cách sử dụng

Cách 1: thêm :online sau tên model

curl https://bazaarlink.ai/api/v1/chat/completions \
  -H "Authorization: Bearer $BAZAARLINK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.4-mini:online",
    "messages": [{ "role": "user", "content": "Hôm nay Đài Loan có tin tức AI nào?" }]
  }'

Cách 2: dùng tham số plugins

{
  "model": "gpt-5.4-mini",
  "messages": [{ "role": "user", "content": "..." }],
  "plugins": [{
    "id": "web",
    "max_results": 5,
    "query_source": "last_user",
    "country": "taiwan",
    "time_range": "week"
  }]
}

Cách 3: dùng web_search_options

{
  "model": "gpt-5.4-mini",
  "messages": [{ "role": "user", "content": "..." }],
  "web_search_options": { "search_context_size": "high", "query_source": "conversation" }
}

Có thể chọn một cách bất kỳ hoặc kết hợp các cách này.

Tham số tìm kiếm

Các tham số sau có thể đặt trong mục web của plugins hoặc trong web_search_options; nếu cả hai nơi có giá trị khác nhau thì ưu tiên plugins.

Ưu tiên độ sâu: engine (bốn giá trị ở trên) > mode > search_context_size > mặc định medium.

Định dạng tham số của plugins và web_search_options tương thích với OpenRouter, nên các request hiện có có thể dùng trực tiếp.

Cú pháp công cụ tìm kiếm cũng tương thích với Vercel AI Gateway

tools của Chat Completions cũng nhận định dạng công cụ tìm kiếm sau. Định dạng này được xem là một lần tìm kiếm web, do dịch vụ tìm kiếm web của nền tảng xử lý, với cách tính phí và định dạng trích dẫn như trên:

{
  "model": "gpt-5.4-mini",
  "messages": [{ "role": "user", "content": "..." }],
  "tools": [{
    "type": "vercel:perplexity_search",
    "config": { "query": "xuất khẩu chất bán dẫn Đài Loan năm 2026", "max_results": 5 }
  }]
}

• type được chấp nhận: vercel:perplexity_search, vercel:exa_search, vercel:parallel_search, vercel:tako_search. Các type này có hành vi và chi phí giống nhau.
• config.query được xem như search_prompt; config.max_results (hoặc num_results), config.country và các trường tương tự ánh xạ vào tham số cùng tên ở trên; trường không nhận diện được sẽ bị bỏ qua.
• Các công cụ tìm kiếm này không được chuyển tiếp cho model.
• Nếu một request có nhiều công cụ tìm kiếm, chỉ dùng công cụ đầu tiên.

Cũng chấp nhận công cụ `web_search_preview`

Đưa { "type": "web_search_preview" } vào tools của Responses hoặc endpoint khác cũng được xem là một lần tìm kiếm web do dịch vụ của nền tảng xử lý, với cách tính phí và định dạng trích dẫn như trên. Công cụ này không được chuyển tiếp cho model.

Khi dùng nhiều cách cùng lúc

Có thể dùng :online, plugins, web_search_options và công cụ tìm kiếm (gồm web_search_preview) cùng lúc, nhưng mỗi request chỉ thực hiện một lần tìm kiếm và tính một lần phí; search_queries tính theo số truy vấn. Thứ tự ưu tiên truy vấn là search_queries > config.query của công cụ > search_prompt > query_source. Các tham số khác được gộp theo thứ tự ưu tiên ở trên.

Chỉ trả về 400 invalid_web_search_options khi kiểu tham số sai, chẳng hạn truyền số cho engine hoặc include_domains không phải mảng chuỗi, hoặc giá trị nằm ngoài phạm vi.

Cấp độ tìm kiếm

Khi không chỉ định cấp độ, dùng medium.

Nguồn trích dẫn trong response

Các nguồn tìm được trả về qua annotations theo định dạng url_citation phổ biến:

"annotations": [
  {
    "type": "url_citation",
    "url_citation": {
      "url": "https://example.com/article",
      "title": "Tiêu đề bài viết",
      "content": "Nội dung tóm tắt nguồn…",
      "start_index": 0,
      "end_index": 0
    }
  }
]

• Mỗi nguồn tham khảo có một mục trích dẫn.
• Nếu model đánh dấu nguồn tương ứng trong câu trả lời (ví dụ [source-1]), start_index và end_index chỉ vị trí dấu đó trong văn bản trả lời; nếu không có dấu, cả hai đều là 0.

Vị trí theo endpoint:

• Chat Completions: non-streaming ở choices[].message.annotations; streaming gửi thêm một block chỉ có delta.annotations trước [DONE].
• Responses: ở annotations trong nội dung output_text; streaming gửi cùng các event hoàn tất như response.output_text.done.
• Messages: đính kèm ở annotations của block nội dung văn bản; streaming gửi trong event text_delta trước khi kết thúc.

Tính phí

• Chi phí mỗi request = chi phí model + chi phí tìm kiếm web.
• Tìm kiếm web tính phí theo mỗi lần tìm, theo bảng giá nền tảng; độ sâu nâng cao (high hoặc chọn nâng cao bằng engine/mode) có đơn giá cao hơn.
• Model miễn phí vẫn phát sinh phí tìm kiếm web; bản thân model vẫn miễn phí.
• Mỗi request mặc định tìm một lần. Với search_queries, số lần tìm bằng số truy vấn và phí cũng tính theo số đó. Việc retry sau khi backend đổi route không lặp lại tìm kiếm hay tính phí.
• Các trường hợp sau không phát sinh phí tìm kiếm web:
  • Bản thân việc tìm kiếm thất bại (trả về 503, xem bên dưới).
  • Các truy vấn thất bại khi dùng search_queries (chỉ tính các truy vấn thành công).
  • Tìm kiếm thành công nhưng model cuối cùng không tạo được response.
• Phí tìm kiếm được tính khi giữ trước số dư. Khoản trừ thực tế thể hiện trong usage.cost của response và bản ghi thanh toán.

Lỗi và giới hạn

• Rate limit, quyền model, kiểm duyệt nội dung và các kiểm tra request thông thường hoàn tất trước khi tìm kiếm; request bị chặn bởi các kiểm tra này sẽ không tìm.
• Các tham số và công cụ liên quan đến tìm kiếm (hậu tố :online, mục web trong plugins, web_search_options, các công cụ ở trên và web_search_preview) chỉ do nền tảng này xử lý và không chuyển tiếp cho model.

Dữ liệu mạng xã hội (:social)

Thêm :social vào sau tên mô hình khi câu hỏi liên quan đến một nền tảng mạng xã hội. Trước khi mô hình trả lời, BazaarLink lấy các bài đăng, hồ sơ hoặc bình luận phù hợp từ nền tảng đó và cung cấp làm tài liệu tham khảo. Nếu không lấy kịp dữ liệu từ nền tảng, yêu cầu sẽ chuyển dự phòng sang tìm kiếm web thông thường, nên bạn vẫn nhận được câu trả lời.

Ví dụ

curl https://bazaarlink.ai/api/v1/chat/completions \
  -H "Authorization: Bearer $BAZAARLINK_API_KEY" \
  -H "Content-Type: application/json" \
  --max-time 60 \
  -d '{
    "model": "gpt-5.4-mini:social",
    "messages": [{ "role": "user", "content": "Các bài đăng gần đây trên X về GPT-6" }]
  }'

Cần lưu ý

• Thời gian chờ: dữ liệu mạng xã hội được lấy trực tiếp, nên một yêu cầu :social có thể mất 20 đến 40 giây trước khi câu trả lời bắt đầu. Sau 40 giây, yêu cầu chuyển dự phòng sang tìm kiếm web. Hãy đặt timeout của client ít nhất 60 giây. :online vẫn nhanh vì đó là tìm kiếm web thông thường.
• Giá: các truy vấn được trả lời bằng dữ liệu mạng xã hội dùng chung hạn mức tìm kiếm miễn phí hằng ngày với :online (5 lượt mỗi ngày nếu không có số dư, 10 lượt nếu có số dư hoặc gói đăng ký, đặt lại vào 00:00 UTC). Vượt hạn mức, mỗi truy vấn được tính theo bảng giá Data API (xem GET /v1/data/catalog), cộng thêm phí token của chính mô hình. Truy vấn chuyển dự phòng sang tìm kiếm web được tính như :online.
• Phạm vi: :social chỉ đọc một số nền tảng mạng xã hội, danh sách phụ thuộc vào cấu hình đang bật; danh sách hiện tại nằm ở /solutions/data-api#social-suffix. Nền tảng có trong danh mục Data API nhưng không có trong danh sách đó sẽ không được :social đọc, nên truy vấn về nền tảng đó, hoặc không nêu nền tảng nào, được trả lời bằng tìm kiếm web.
• Tương thích: hoạt động trên POST /api/v1/chat/completions, /api/v1/messages và /api/v1/responses, cả streaming và không streaming, với cùng cách trích dẫn như :online. Không thể kết hợp :online và :social trong cùng một tên mô hình (400 invalid_web_search_options).

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://api.bazaarlink.ai/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://api.bazaarlink.ai/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 /v1/models
4. Dự phòng models[], 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://api.bazaarlink.ai/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. Xử lý yêu cầu

Khi nguồn upstream gặp sự cố, yêu cầu có thể thử một nguồn khác đang khả dụng. Nếu không có nguồn nào khả dụng, yêu cầu sẽ trả lỗi.

Đ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://api.bazaarlink.ai/v1/chat/completions \
  -H "Authorization: Bearer $BAZAARLINK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"google/gemini-3.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://api.bazaarlink.ai/v1/chat/completions \
  -H "Authorization: Bearer $BAZAARLINK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"google/gemini-3.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://api.bazaarlink.ai/v1/chat/completions \
  -H "Authorization: Bearer $BAZAARLINK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"google/gemini-3.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://api.bazaarlink.ai/v1/chat/completions \
  -H "Authorization: Bearer $BAZAARLINK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"google/gemini-3.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://api.bazaarlink.ai/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

Phản hồi có thể có x-request-id; x-generation-id với phản hồi không stream; x-ratelimit-*; retry-after khi áp dụng; và x-auto-resolved-model cho định tuyến auto hoặc auto:free.

x-request-id: 85e6f35c71a31f19-SJC
x-generation-id: 85e6f35c71a31f19-SJC
x-ratelimit-limit: 200
x-ratelimit-remaining: 198
x-ratelimit-reset: 1740000060
retry-after: 5
x-auto-resolved-model: openai/gpt-4o

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.

Danh sách cho phép IP

Bạn có thể đặt danh sách cho phép IP riêng cho từng khóa API, để chỉ các yêu cầu từ IP nguồn được chỉ định mới sử dụng được khóa đó.

Khi nào nên dùng

Tính năng này phù hợp với máy chủ production có IP outbound cố định. Nếu ứng dụng gửi yêu cầu từ mạng gia đình, mạng di động hoặc địa chỉ thay đổi, hãy kiểm tra IP outbound có ổn định trước; nếu không, bạn có thể tự khóa mình bên ngoài.

Cách thiết lập

Mở /keys , mở menu "⋯" của khóa cần dùng, chọn "Danh sách cho phép IP", nhập các mục rồi lưu.

Bạn cũng có thể dùng PATCH /api/v1/keys/:id với session đã đăng nhập hoặc Management API key:

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

{
  "allowedCidrs": [
    "203.0.113.7",
    "198.51.100.0/24"
  ]
}

# Clear the allowlist and return to unrestricted access
{"allowedCidrs": []}

Định dạng mục

Trong UI, nhập một giá trị trên mỗi dòng. Trong API, gửi các giá trị tương tự trong mảng `allowedCidrs`. Chấp nhận IPv4 thuần, IPv4 CIDR hoặc IPv6 literal (chỉ so khớp chính xác).

203.0.113.7
198.51.100.0/24
2001:db8::1

Cách hoạt động

Để trống (gửi mảng [] rỗng) nghĩa là không giới hạn IP nguồn. Đây là mặc định nên hành vi của các khóa hiện có không thay đổi.

IP nguồn được lấy từ header `cf-connecting-ip`.

Nếu danh sách không rỗng nhưng không thể xác định IP nguồn, yêu cầu sẽ bị từ chối (fail-closed).

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ồ.

Bảo mật tài khoản

Ngoài mật khẩu, BazaarLink còn hỗ trợ xác minh hai bước để tăng thêm một lớp bảo vệ khi đăng nhập.

Bật xác minh hai bước (TOTP)

1. Vào trang “Cài đặt”, tìm mục “Xác minh hai bước (TOTP)”, sau đó nhấn “Bật xác minh hai bước”.
2. Quét mã QR trên màn hình bằng ứng dụng authenticator (như Google Authenticator), hoặc nhập thủ công secret hiển thị bên dưới.
3. Nhập mã 6 chữ số do ứng dụng authenticator tạo ra và xác nhận để hoàn tất việc bật tính năng.

Sau khi bật, hệ thống sẽ hiển thị 8 mã dự phòng (chỉ hiển thị một lần) — mỗi mã gồm 10 ký tự và chỉ dùng được một lần. Hãy ghi lại hoặc sao chép và lưu ngay ở nơi an toàn khác ngoài điện thoại; dùng mã dự phòng để đăng nhập khi mất điện thoại hoặc không truy cập được ứng dụng authenticator.

Cách khác để bảo vệ tài khoản của bạn

Kết hợp các tính năng sau với xác minh hai bước để giảm thêm thiệt hại nếu key bị rò rỉ hoặc bị lạm dụng:

• Danh sách cho phép IP — giới hạn API key chỉ dùng được từ các IP nguồn được chỉ định.
• Phanh Khẩn Cấp Cá Nhân — đặt hạn mức chi tiêu theo phút và theo giờ, tự động tạm dừng khi vượt ngưỡng.
• Hạn mức chi tiêu theo từng key — đặt hạn mức chi tiêu theo ngày, tuần hoặc tháng khi tạo hoặc cập nhật API key.

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://api.bazaarlink.ai/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://api.bazaarlink.ai/v1/videos \
  -H "Authorization: Bearer $BAZAARLINK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"bytedance/seedance-2.0","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-3.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 đủ →

OAuth PKCE

OAuth 2.0 PKCE cho phép ứng dụng client công khai gọi API thay mặt người dùng.

Khi nào sử dụng OAuth PKCE

• SPA hoặc ứng dụng di động cần thanh toán theo người dùng
• SaaS đa thuê
• Client công khai
• Cần khóa riêng, có thể thu hồi cho từng người dùng (không tự hết hạn) thay vì một khóa API dùng chung

Người dùng của bạn sẽ thấy gì

Hãy mô tả các bước này trên màn hình đăng nhập của riêng bạn:

1. Trong ứng dụng của bạn, họ chọn "Đăng nhập bằng BazaarLink" (hoặc tên nút bạn đặt).
2. Trình duyệt của họ mở trang cấp quyền của BazaarLink. Nếu chưa đăng nhập, họ đăng nhập trước rồi tự động quay lại trang này.
3. Trang hiển thị địa chỉ ứng dụng của bạn và điều sẽ xảy ra nếu họ cho phép: một khóa API mới được tạo cho ứng dụng, mức sử dụng được tính vào số dư BazaarLink của họ, và họ có thể thu hồi khóa bất cứ lúc nào. Họ có thể đặt tên khóa và đặt hạn mức chi tiêu hằng tháng (cả hai đều không bắt buộc).
4. Họ nhấp Cho phép và được chuyển về ứng dụng của bạn. Nếu nhấp Từ chối, không có khóa nào được tạo, ứng dụng của bạn không được thông báo và họ thấy trang "Đã từ chối truy cập".
5. Để thu hồi quyền truy cập sau này, họ mở trang Khóa API (https://bazaarlink.ai/keys) và vô hiệu hóa hoặc xóa khóa được đặt tên theo ứng dụng của bạn.

Cách hoạt động

Bước 1 — Khởi tạo xác thực — Tạo code_verifier ngẫu nhiên và hash SHA-256 làm code_challenge.

https://bazaarlink.ai/auth?callback_url=https://yourapp.com/callback&code_challenge=CODE_CHALLENGE&code_challenge_method=S256

Tham số URL ủy quyền

• callback_url (bắt buộc) — nơi người dùng quay lại sau khi cho phép. Quy tắc bên dưới.
• code_challenge (bắt buộc) — SHA-256 của code_verifier được mã hóa base64url (43 ký tự, không có padding).
• code_challenge_method (bắt buộc) — phải là S256.
• state (tùy chọn) — giá trị CSRF mờ đục của riêng bạn, từ 1 đến 256 ký tự ASCII in được. BazaarLink trả lại nguyên vẹn dưới dạng &state=… ngay sau code. State sai định dạng sẽ khiến trang cấp quyền hiển thị "Yêu cầu cấp quyền không hợp lệ".
• key_label (tùy chọn) — tối đa 100 ký tự. Điền sẵn tên khóa trên trang đồng ý (người dùng vẫn có thể thay đổi). Nhãn quá dài hoặc để trống sẽ bị bỏ qua.
• Headless tools (CLI / desktop, no callback_url) — omit callback_url. After the user allows, the page shows a one-time code (valid 5 minutes, single use) for them to enter into your tool; exchange it exactly like a redirected code. The page cannot show which app is asking, so tell users to enter the code only in a tool they started themselves.

Không được hỗ trợ

• workspace_id và required_workspace_id — không được hỗ trợ. Khóa luôn thuộc về tài khoản của chính người dùng.
• code_challenge_method=plain — không được hỗ trợ (chỉ S256).

Quy tắc của callback_url

• Phải là https://. http:// chỉ được chấp nhận cho localhost, 127.0.0.1 và [::1] (mọi cổng); khi đó trang đồng ý hiển thị cảnh báo phát triển cục bộ.
• Không có fragment (#), không có tên người dùng hoặc mật khẩu trong URL, tối đa 2048 ký tự.
• Trang đồng ý hiển thị tên host callback của bạn để người dùng biết ứng dụng nào đang yêu cầu.
• Sau khi người dùng cho phép, trình duyệt được chuyển đến callback_url của bạn kèm code=… (và state=… nếu bạn đã gửi; query string hiện có được giữ nguyên). Code có hiệu lực 10 phút và chỉ dùng được một lần.

Bước 2 — Đổi code lấy khóa API — Sau khi người dùng ủy quyền yêu cầu, BazaarLink chuyển hướng đến callback_url của bạn kèm một code dùng một lần. Code có hiệu lực 10 phút và chỉ dùng được một lần; code_verifier sai sẽ làm code bị hủy. POST code, code_verifier và code_challenge_method (cả ba đều bắt buộc) để nhận khóa API của người dùng.

curl https://bazaarlink.ai/api/v1/auth/keys \
  -H "Content-Type: application/json" \
  -d '{
    "code": "<CODE_FROM_CALLBACK_URL>",
    "code_verifier": "<CODE_VERIFIER>",
    "code_challenge_method": "S256"
  }'

# Response
# { "key": "sk-bl-...", "user_id": "..." }

Bước 3 — Sử dụng khóa — Khóa trả về là khóa API BazaarLink thông thường thuộc về người dùng đã ủy quyền — mức sử dụng được tính vào số dư của người dùng đó, không phải của bạn.

curl https://bazaarlink.ai/api/v1/chat/completions \
  -H "Authorization: Bearer sk-bl-..." \
  -H "Content-Type: application/json" \
  -d '{"model": "google/gemini-3.5-flash", "messages": [{"role": "user", "content": "Hello"}]}'

Ví dụ JavaScript (trình duyệt)

// 1) Create a verifier + S256 challenge, then send the user to BazaarLink
const b64url = (buf) => btoa(String.fromCharCode(...new Uint8Array(buf)))
  .replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
const verifier = b64url(crypto.getRandomValues(new Uint8Array(32)));
const challenge = b64url(await crypto.subtle.digest("SHA-256", new TextEncoder().encode(verifier)));
sessionStorage.setItem("bl_verifier", verifier);
// "state" is optional: BazaarLink hands it back unchanged next to the code.
const state = b64url(crypto.getRandomValues(new Uint8Array(16)));
sessionStorage.setItem("bl_state", state);
location.href =
  "https://bazaarlink.ai/auth?callback_url=" + encodeURIComponent(location.origin + "/callback") +
  "&code_challenge=" + challenge + "&code_challenge_method=S256&state=" + state;

// 2) On /callback: check your own state, then exchange the one-time code for a user key
const params = new URLSearchParams(location.search);
if (params.get("state") !== sessionStorage.getItem("bl_state")) throw new Error("state mismatch");
const res = await fetch("https://bazaarlink.ai/api/v1/auth/keys", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    code: params.get("code"),
    code_verifier: sessionStorage.getItem("bl_verifier"),
    code_challenge_method: "S256",
  }),
});
if (!res.ok) throw new Error((await res.json()).error?.message ?? "exchange failed"); // 403 invalid_code: ask the user to authorize again
const { key } = await res.json(); // use as: Authorization: Bearer <key>

Trang /auth và POST /api/v1/auth/keys được phục vụ từ https://bazaarlink.ai (không phải api.bazaarlink.ai). Khóa bạn nhận được dùng được với cả hai base URL: https://bazaarlink.ai/api/v1 và https://api.bazaarlink.ai/v1.

Nếu người dùng đặt hạn mức chi tiêu khi cấp quyền, đó là hạn mức hằng tháng và được đặt lại theo chu kỳ tháng của tài khoản.

Lỗi

Lỗi dùng định dạng kiểu OpenAI {"error":{"message","type","code"}}. POST /api/v1/auth/keys có thể trả về:

• 400 invalid_code_challenge_method — thiếu code_challenge_method, là plain, hoặc khác S256.
• 400 — nội dung JSON không hợp lệ, hoặc thiếu code / code_verifier.
• 403 invalid_code — code không tồn tại, đã hết hạn hoặc đã dùng, code_verifier sai, hoặc tài khoản không còn được phép. Tất cả các trường hợp này cố ý trả về cùng một thông báo để bên gọi không thể phân biệt. code_verifier sai cũng làm code bị hủy: hãy yêu cầu người dùng ủy quyền lại.
• 429 rate_limited — hơn 30 lần thử đổi trong 10 phút từ một IP (xem header Retry-After).
• 429 key_total_cap — tài khoản đã có tối đa 200 khóa API.
• 405 — chỉ chấp nhận POST.

Tạo mã từ máy chủ của bạn (khóa quản lý)

Chủ sở hữu khóa quản lý (Management Key) cá nhân có thể tạo mã ủy quyền trực tiếp bằng POST /api/v1/auth/keys/code mà không cần đưa người dùng qua trang trình duyệt (tương thích với OpenRouter). Mã gắn với chủ sở hữu khóa quản lý, nên khóa nhận được khi đổi là một khóa tiêu chuẩn trong tài khoản của chủ sở hữu đó, với hạn mức, chu kỳ, thời hạn và tên được chọn tại đây. Dùng khi công cụ của bạn đã có khóa quản lý và muốn trao cho một ứng dụng một khóa bị giới hạn. Bước đổi mã (POST /api/v1/auth/keys) giống như ở trên.

• callback_url (bắt buộc) và code_challenge + code_challenge_method=S256 (bắt buộc) — cùng quy tắc với URL ủy quyền.
• key_label (tùy chọn) — tối đa 100 ký tự; tên của khóa. Mặc định: "App: <host callback của bạn>".
• limit (tùy chọn) — hạn mức chi tiêu bằng USD, từ 0 trở lên; 0 hoặc bỏ trống nghĩa là không giới hạn.
• usage_limit_type (tùy chọn) — daily, weekly hoặc monthly: tần suất đặt lại hạn mức. Chỉ dùng cùng với limit; mặc định là monthly.
• expires_at (tùy chọn) — thời điểm khóa hết hạn: thời gian ISO 8601 UTC trong tương lai có kèm giây, ví dụ 2026-12-31T23:59:59Z. Giá trị chỉ chính xác đến phút sẽ bị từ chối. Nếu bỏ trống, khóa vẫn có hiệu lực cho đến khi bị thu hồi.
• workspace_id — không được hỗ trợ (400). spawn_agent và spawn_cloud được chấp nhận nhưng bị bỏ qua.

curl https://bazaarlink.ai/api/v1/auth/keys/code \
  -H "Authorization: Bearer sk-bl-YOUR_MGMT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "callback_url": "https://yourapp.com/callback",
    "code_challenge": "<CODE_CHALLENGE>",
    "code_challenge_method": "S256",
    "key_label": "My app",
    "limit": 10,
    "usage_limit_type": "monthly",
    "expires_at": "2026-12-31T23:59:59Z"
  }'

# Response
# { "data": { "id": "<ONE_TIME_CODE>", "app_id": 123456789, "created_at": "2026-10-22T12:00:00.000Z" } }
# Then POST { "code": "<ONE_TIME_CODE>", "code_verifier": "<CODE_VERIFIER>", "code_challenge_method": "S256" } to /api/v1/auth/keys

Phản hồi: { "data": { "id", "app_id", "created_at" } }. id là mã dùng một lần để đổi (có hiệu lực 10 phút, chỉ một lần). BazaarLink không có sổ đăng ký ứng dụng, nên app_id là một số nguyên cố định suy ra từ địa chỉ callback của bạn: cùng một địa chỉ luôn nhận cùng một app_id.

• 401 unauthorized — không có khóa Bearer, hoặc khóa không tồn tại.
• 403 management_key_required — khóa không phải khóa quản lý cá nhân (khóa tiêu chuẩn và khóa quản lý của tổ chức bị từ chối).
• 403 account_not_allowed — chủ sở hữu khóa đã bị đình chỉ hoặc xóa.
• 400 — invalid_callback_url, invalid_code_challenge_method, invalid_code_challenge, invalid_expires_at, workspace_not_supported, hoặc nội dung yêu cầu sai định dạng.
• 429 rate_limited — hơn 30 mã mỗi giờ cho một chủ sở hữu hoặc 120 mã mỗi giờ từ một IP (xem Retry-After).

Khóa bạn nhận được

• Một khóa API BazaarLink tiêu chuẩn (sk-bl-…), cùng loại với khóa tạo trên trang Khóa API. Khóa không tự hết hạn.
• Mức sử dụng được tính vào số dư BazaarLink của người dùng. Nếu người dùng đặt hạn mức chi tiêu trên trang đồng ý, đó là hạn mức hằng tháng.
• Hoạt động với cả hai base URL: https://bazaarlink.ai/api/v1 và https://api.bazaarlink.ai/v1.
• Được tính vào giới hạn 200 khóa của tài khoản và hiển thị trong danh sách Khóa API của người dùng, nơi họ có thể vô hiệu hóa hoặc xóa bất cứ lúc nào.
• Tài khoản bị đình chỉ hoặc đã xóa không thể cấp quyền cho ứng dụng, và code được cấp trước khi đình chỉ sẽ bị từ chối khi đổi (403 invalid_code).

Bạn nhận được gì

• Luồng Authorization Code + PKCE
• Thanh toán theo người dùng: mỗi người dùng tự trả cho mức sử dụng của mình từ số dư của chính họ
• Mỗi người dùng có một khóa riêng, hiển thị trên trang Khóa API của họ để họ có thể thu hồi

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://api.bazaarlink.ai/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://api.bazaarlink.ai/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://api.bazaarlink.ai/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://api.bazaarlink.ai/v1/keys/:id
Authorization: Bearer sk-bl-YOUR_MGMT_KEY

# Returns 204 No Content on success

Truy vấn số dư

GET https://api.bazaarlink.ai/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://api.bazaarlink.ai/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://api.bazaarlink.ai/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

Envelope lỗi khác nhau theo endpoint. Dựa vào HTTP status và error.type nếu có. error.code có thể là chuỗi hoặc số, đôi khi không có; error.message chỉ để hiển thị.

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

HTTP và error.code

Envelope lỗi khác nhau theo endpoint. Dựa vào HTTP status và error.type nếu có. error.code có thể là chuỗi hoặc số, đôi khi không có; error.message chỉ để hiển thị.

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.

Kiểm duyệt nội dung

Tất cả các yêu cầu đều được tự động kiểm duyệt trước khi gửi đến mô hình. Các yêu cầu vi phạm chính sách sử dụng của chúng tôi sẽ bị từ chối trước khi đến mô hình và trả về lỗi 403.

Các danh mục nội dung sẽ bị chặn

Việc kiểm duyệt dựa trên Chính sách Sử dụng Được chấp nhận (Acceptable Use Policy) của chúng tôi và chủ yếu chặn các danh mục nội dung sau:

• Nội dung bóc lột tình dục
• Đe dọa bạo lực
• Hướng dẫn thực hiện hành vi bất hợp pháp
• Nội dung liên quan đến nguy cơ sinh học

Định dạng phản hồi 403

Một yêu cầu bị chặn bởi kiểm duyệt sẽ trả về lỗi theo định dạng sau:

{
  "error": {
    "message": "Your prompt was blocked by content moderation.",
    "type": "invalid_request_error",
    "code": "content_filter"
  }
}

Các yêu cầu bị chặn sẽ không bị tính phí — bạn sẽ không bị tính phí cho một yêu cầu bị từ chối.

Khiếu nại khi bị chặn nhầm

Nếu bạn cho rằng một yêu cầu đã bị chặn không chính xác, vui lòng liên hệ bộ phận hỗ trợ kèm theo thời gian yêu cầu và (nếu thuận tiện) request id — chúng tôi sẽ xem xét lại.

Quyền riêng tư

Yêu cầu được tự động kiểm duyệt an toàn nội dung; văn bản và hình ảnh trong đầu vào mới nhất của bạn có thể được gửi tới dịch vụ chấm điểm an toàn nội dung của bên thứ ba.

Với yêu cầu bị xác định là vi phạm, nghi vi phạm, gần ngưỡng hoặc được lấy mẫu ngẫu nhiên, chúng tôi có thể lưu toàn văn hoặc phần đầu làm bằng chứng tuân thủ, xử lý tranh chấp và kiểm toán, và không cam kết thời hạn xóa cố định.

Các yêu cầu thành công thông thường khác không được lưu prompt và phản hồi; yêu cầu dùng khóa ZDR không thuộc hai điểm đầu.

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.

Envelope lỗi khác nhau theo endpoint. Dựa vào HTTP status và error.type nếu có. error.code có thể là chuỗi hoặc số, đôi khi không có; error.message chỉ để hiển thị.

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://api.bazaarlink.ai/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-4o",
            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.

Sau khi stream bắt đầu, phản hồi HTTP đã là 200. Hãy phân tích từng SSE data frame và coi error cấp cao nhất hoặc choices[0].finish_reason === "error" là phản hồi thất bại, chưa hoàn chỉnh.

Nếu stream thất bại sau khi bắt đầu, BazaarLink có thể phá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]. Hãy coi phản hồi là chưa hoàn chỉnh; không dùng đầu ra một phần như kết quả đã hoàn tất.

data: {"error":{"message":"The request could not be completed.","type":"upstream_error","code":502}}

data: [DONE]

// 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://api.bazaarlink.ai/v1/chat/completions \
  -H "Authorization: Bearer $BAZAARLINK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-4o",
    "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-4o",
        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-4o",
    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-4o",
        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://api.bazaarlink.ai/v1/chat/completions \
  -H "Authorization: Bearer $BAZAARLINK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-4o",
    "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://api.bazaarlink.ai/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

The client-supplied transforms field is ignored and removed before an upstream request. It cannot enable or disable message transformations. BazaarLink may apply context handling under its own server-side rules; shorten the input or select a model with a larger context window when needed.

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

Với các yêu cầu thành công thông thường, BazaarLink không lưu trữ nội dung tin nhắn (ngoại lệ: xem Chính sách quyền riêng tư); chế độ khóa ZDR cung cấp zero data retention nghiêm ngặt hơn.

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

• Nội dung tin nhắn: không lưu trữ với yêu cầu thành công thông thường (ngoại lệ: xem Chính sách quyền riêng tư); chế độ khóa ZDR nghiêm ngặt hơn
• Bản ghi mức sử dụng cho thanh toán và vận hành: số token, thời gian, mô hình, chi phí, độ trễ và trạng thái
• Nhật ký sử dụng: với yêu cầu thành công thông thường chỉ có thống kê mức sử dụng, không có nội dung tin nhắn
• 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-4o",
    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/gpt-5.5",
  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.7-flash",
    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 GPT-5.6 Sol — specify effort level
const response2 = await client.chat.completions.create({
  model: "openai/gpt-5.6-sol",
  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 },
});

Đọc nội dung suy nghĩ

Mô hình suy luận có thể trả về nội dung suy nghĩ cùng với câu trả lời. Với các mô hình liệt kê bên dưới, chế độ suy nghĩ được bật theo mặc định: yêu cầu không gửi tham số suy luận nào sẽ chạy với suy nghĩ được bật, trả về nội dung suy nghĩ và bị tính phí theo số token suy nghĩ thực tế đã dùng. Gửi reasoning: { exclude: true } hoặc include_reasoning: false để tắt. Mọi mô hình khác chỉ trả về nội dung suy nghĩ khi bạn yêu cầu: gửi reasoning_effort, đối tượng reasoning, include_reasoning: true, thinking hoặc enable_thinking.

Các mô hình suy nghĩ theo mặc định: gemini-4-argon, deepseek-v4.1-flash, deepseek-v4.1-flash-1017

Cách yêu cầu

Gửi một trong các tham số sau trong yêu cầu: reasoning_effort (low, medium hoặc high), đối tượng reasoning (effort, max_tokens), include_reasoning: true, thinking: { type: "enabled" } hoặc enable_thinking: true. Gửi reasoning.exclude: true hoặc include_reasoning: false để tắt nội dung suy nghĩ (mô hình vẫn suy luận).

Xem mô hình hỗ trợ mức nào bằng GET /v1/models: mỗi mô hình reasoning liệt kê reasoning.supported_efforts, reasoning.default_effort và reasoning.mandatory (ví dụ gemini-4-argon hỗ trợ high, medium và low).

Ví dụ: gemini-4-argon

response = client.chat.completions.create(
    model="gemini-4-argon",
    messages=[{"role": "user", "content": "Which is larger, 9.11 or 9.9?"}],
    reasoning_effort="high",  # or: extra_body={"include_reasoning": True}
)

message = response.choices[0].message
print(message.reasoning)          # the thinking text (only returned because we asked)
print(message.content)            # the answer

const stream = await client.chat.completions.create({
  model: "gemini-4-argon",
  messages: [{ role: "user", content: "Which is larger, 9.11 or 9.9?" }],
  stream: true,
  // @ts-ignore - BazaarLink extension
  reasoning: { effort: "high" },
});

for await (const chunk of stream) {
  const delta: any = chunk.choices[0]?.delta;
  if (delta?.reasoning) process.stdout.write(delta.reasoning); // thinking text
  if (delta?.content) process.stdout.write(delta.content);     // answer
}

Với /v1/responses, yêu cầu bằng reasoning: { effort, summary: "auto" }; nội dung suy nghĩ được trả về trong mục reasoning của mảng output. Với /v1/messages, gửi thinking: { type: "enabled", budget_tokens } để nhận khối thinking.

Độ 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
• Chọn mô hình nhỏ hơn (flash/mini/haiku) cho tình huống nhạy cảm độ trễ
• 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-3.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://api.bazaarlink.ai/v1/generation?id=BAZAARLINK_REQUEST_ID" \
  -H "Authorization: Bearer $BAZAARLINK_API_KEY"

# Response
{
  "data": {
    "id": "85e6f35c71a31f19-SJC",
    "model": "google/gemini-3.5-flash",
    "duration_ms": 842,
    "throughput": 61.2,
    "usage": { "prompt_tokens": 12, "completion_tokens": 48, "total_tokens": 60 }
  }
}

Tối ưu hóa Uptime

Sau lỗi upstream, yêu cầu có thể thử một nguồn khả dụng khác. Nếu không nguồn nào xử lý được, yêu cầu sẽ trả lỗi. Circuit breaker giới hạn việc thử lại và trạng thái nhà cung cấp được theo dõi.

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
• Khi nguồn upstream gặp sự cố, yêu cầu có thể thử một nguồn khác đang khả dụng. Nếu không có nguồn nào khả dụng, yêu cầu sẽ trả lỗi.
• 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

# If an upstream source returns an error, the request can try another available source.
# Requests handled by a platform model are billed at that model's catalog price.

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

# Check whether another source handled the request (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://api.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 /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 để upstream 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 dành riêng cho nhà cung cấp khi upstream không hỗ trợ — 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 upstream 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 của mô hình 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-v4.1-flash

Ư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://api.bazaarlink.ai/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

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

Các biến thể danh mục như :free, :extended và :thinking có thể xác định mục có khả năng hoặc giá danh mục khác nhau. Tuyến upstream và giá khách hàng do danh mục cùng quy tắc phía máy chủ của BazaarLink quyết định.

:free
:extended
:thinking

:nitro
:floor
:exacto

:online

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 /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.

qwen/qwen3.7-flash
reflection/beam-free
stealth/glyph-cluster
nvidia/nemotron-3.5-lightning-free
inclusionai/ling-3.1-flash-1019
deepseek/deepseek-v4-flash-0731free

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. Hạn mức miễn phí được tính theo "đơn vị", không đơn thuần là số lượt yêu cầu: số đơn vị mà một yêu cầu tiêu thụ tăng theo độ dài context của prompt. Vì vậy với cùng hạn mức mỗi ngày, yêu cầu có context dài sẽ dùng được ít lượt hơn đáng kể so với prompt ngắn.

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

Sau khi dùng hết hạn mức miễn phí, yêu cầu vượt mức được tính theo giá trả phí của model nếu tài khoản còn số dư. Để nhận lỗi 429, hãy gửi `X-Free-Fallback: false` hoặc tắt chuyển sang mức trả phí trong cài đặt khóa. Nếu không còn số dư, yêu cầu vượt mức trả về 429.

Khi một yêu cầu thực sự bị hạ cấp theo cách này, phản hồi sẽ mang theo header x-bl-free-fallback: daily hoặc x-bl-free-fallback: rpm cho biết giới hạn nào đã kích hoạt, giúp bạn phát hiện sự chuyển đổi ngay tại thời điểm gửi yêu cầu thay vì chỉ biết qua hóa đơn. Header này không xuất hiện ở các yêu cầu không bị hạ cấp.

# 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 and billing
• Change logs and security logs

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

# Create a team
curl https://api.bazaarlink.ai/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://api.bazaarlink.ai/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://api.bazaarlink.ai/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ờ. Tắt theo mặc định — cần tự bật.
• 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

Thay khóa API định kỳ là một thực hành bảo mật. Hãy tạo khóa mới, cập nhật và kiểm tra tích hợp, rồi thu hồi khóa cũ. Quy trình này không đảm bảo không có downtime.

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 /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://api.bazaarlink.ai/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://api.bazaarlink.ai/v1/models \
  -H "Authorization: Bearer sk-bl-NEW_KEY_VALUE"

# Step 4: Revoke old key (management key auth again)
DELETE https://api.bazaarlink.ai/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://api.bazaarlink.ai/v1/usage
Authorization: Bearer sk-bl-YOUR_KEY

# With period filtering (day | week | month | year)
GET https://api.bazaarlink.ai/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://api.bazaarlink.ai/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"]))

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