Hướng dẫn sử dụng API XCoffee

Kết nối Codex, Claude Code, OpenClaw, Hermes, Pi và Cursor với ví dụ có thể sao chép và các bước kiểm tra kết nối.

Cập nhật lần cuối: 2026-11-07

Chọn công cụ

Sao chép khóa khách hàng, Base URL đúng giao thức và tên nhóm khả dụng từ bảng điều khiển API, rồi chọn hướng dẫn. Các phần Codex, Claude Code và OpenClaw được mở sẵn để đọc và sao chép.

Kết nối

  1. Mua thẻ và sao chép khóa khách hàng trong trung tâm người dùng. Không dùng khóa quản trị hoặc khóa Magpie nội bộ.
  2. Trong bảng điều khiển API, chọn giao thức của ứng dụng rồi sao chép Base URL và ví dụ.
  3. Đặt model bằng tên API của nhóm khả dụng. Trang chủ liệt kê thành viên do người vận hành công bố; tên và thành viên có thể thay đổi.

Định tuyến dùng nhóm bạn yêu cầu. Ứng dụng của bạn phân chia tác vụ và chọn nhóm cho tác vụ con. Magpie có thể thử thành viên khác trong nhóm trước khi bắt đầu đầu ra, tùy cài đặt nhóm của người vận hành. Trang web không chạy lại tác vụ tạo nội dung sau khi đã có đầu ra một phần hoặc người gọi hủy.

Chọn Agent

Chuẩn bị ứng dụng đã cài, thẻ còn hiệu lực và khóa khách hàng. Ví dụ lập trình dùng xcoffee-coding. Nếu nhóm này không có trong bảng điều khiển API, thay bằng tên API đã công bố và khả dụng.

Ứng dụngGiao thứcBase URL
Claude Code / cài đặt Claude Code trong CC SwitchAnthropic Messageshttps://api.xcoff.ee
Codex CLIOpenAI Responseshttps://api.xcoff.ee/v1
OpenClawOpenAI Chat Completionshttps://api.xcoff.ee/v1
Hermes / PiOpenAI Chat Completionshttps://api.xcoff.ee/v1
Cursor (cần hỗ trợ điểm cuối tùy chỉnh)OpenAI Compatiblehttps://api.xcoff.ee/v1
Agent khác hỗ trợ Chat CompletionsOpenAI Compatible / Chat Completionshttps://api.xcoff.ee/v1

Dùng tên API của nhóm, không dùng tên mô hình thành viên trên trang chủ. Ví dụ: xcoffee-coding cho lập trình và công cụ, xcoffee-fast cho tác vụ ngắn, xcoffee cho tác vụ chung. Bảng điều khiển API xác định nhóm, giao thức khả dụng và hệ số hiện tại. Dịch vụ định tuyến trong nhóm đã chọn; không thể chọn mô hình thành viên riêng lẻ.

Đặt khóa trên máy

Ví dụ terminal yêu cầu CLI tương ứng đã cài và dùng Bash hoặc Zsh trên macOS/Linux. Chạy trong cùng terminal sẽ khởi động Agent, dán khóa khách hàng khi được hỏi rồi nhấn Enter. Nội dung nhập được ẩn:

Ví dụ cấu hình
printf 'XCoffee API Key: '
read -rs XCOFFEE_API_KEY
export XCOFFEE_API_KEY
printf '\n'

Biến chỉ tồn tại trong terminal này và tiến trình con. Đặt lại sau khi đóng terminal. Không đưa khóa vào dự án, commit hoặc dán vào trò chuyện. Dùng cài đặt thông tin xác thực của ứng dụng nếu cần lưu lâu dài. Ứng dụng máy tính và terminal khác không tự kế thừa biến này.

Windows PowerShell: nhập khóa

Chạy trong cửa sổ PowerShell mới và dán khóa khách hàng khi được hỏi:

Ví dụ cấu hình
$secret = Read-Host "XCoffee API Key" -AsSecureString
$env:XCOFFEE_API_KEY = [System.Net.NetworkCredential]::new("", $secret).Password
Remove-Variable secret

Kiểm tra địa chỉ và khóa trước

macOS / Linux:

Ví dụ cấu hình
curl --fail-with-body https://api.xcoff.ee/v1/models \
  -H "Authorization: Bearer $XCOFFEE_API_KEY"

PowerShell:

Ví dụ cấu hình
Invoke-RestMethod -Uri "https://api.xcoff.ee/v1/models" `
  -Headers @{ Authorization = "Bearer $env:XCOFFEE_API_KEY" }

Phản hồi thành công có danh sách mô hình. Bước này kiểm tra địa chỉ, xác thực và tên nhóm hiển thị; vẫn cần chọn đúng giao thức rồi kiểm tra hội thoại và công cụ bên dưới.

Cài đặt trong ứng dụng máy tính khác

Thêm nhà cung cấp tùy chỉnh với địa chỉ tương ứng ở trên, khóa khách hàng và tên API nhóm khả dụng. Lưu rồi chọn nhà cung cấp đó. Trường khóa thường chỉ nhận khóa, không có tiền tố Bearer . Nếu trường yêu cầu rõ URL yêu cầu đầy đủ, dùng https://api.xcoff.ee/v1/chat/completions cho Chat Completions. Không lặp /v1.

Thiết lập cho ứng dụng

Mở công cụ bạn dùng. Không cần đọc mọi hướng dẫn.

Claude Code: kết nối XCoffee

1. Cài đặt và kiểm tra phiên bản

Nếu cần, làm theo hướng dẫn cài Claude Code chính thức, rồi chạy claude --version. Phần này dành cho CLI. Ứng dụng máy tính và tiện ích trình soạn thảo có vị trí cấu hình khác.

2. macOS / Linux: chạy từ cùng terminal

Đặt XCOFFEE_API_KEY theo hướng dẫn trên. Chọn Anthropic Messages trong bảng điều khiển API và xác nhận xcoffee-coding khả dụng. Thay giá trị model bên dưới nếu nhóm có tên khác.

Ví dụ cấu hình
env -u ANTHROPIC_API_KEY \
  ANTHROPIC_BASE_URL=https://api.xcoff.ee \
  ANTHROPIC_AUTH_TOKEN="$XCOFFEE_API_KEY" \
  claude --model xcoffee-coding

Dùng địa chỉ gốc của trang làm Base URL, không thêm /v1/messages. ANTHROPIC_AUTH_TOKEN gửi khóa khách hàng trong header Bearer. XCoffee cũng chấp nhận x-api-key; chọn một phương thức xác thực khi thiết lập lần đầu.

3. Windows: dùng cửa sổ PowerShell mới

Trước hết nhập khóa theo hướng dẫn PowerShell ở trên, rồi chạy:

Ví dụ cấu hình
Remove-Item Env:ANTHROPIC_API_KEY -ErrorAction SilentlyContinue
$env:ANTHROPIC_BASE_URL = "https://api.xcoff.ee"
$env:ANTHROPIC_AUTH_TOKEN = $env:XCOFFEE_API_KEY
claude --model xcoffee-coding

Các biến áp dụng cho terminal này và chương trình khởi động từ đó. Gửi “Chỉ trả lời: kết nối thành công”, chạy /status để kiểm tra Base URL XCoffee và xác nhận yêu cầu xuất hiện trong bảng điều khiển API XCoffee.

4. Cài đặt lâu dài và cách khởi động khác

Để dùng lâu dài, hợp nhất cài đặt env vào ~/.claude/settings.json (%USERPROFILE%\.claude\settings.json trên Windows). Giữ cài đặt không liên quan và không đưa khóa thật vào quản lý phiên bản. Giá trị env trong tệp có thể ghi đè biến shell; kiểm tra nếu yêu cầu vẫn dùng URL cũ.

Trong CC Switch, cấu hình nhà cung cấp Claude Code tùy chỉnh với tên XCoffee, địa chỉ gốc https://api.xcoff.ee, khóa khách hàng và tên nhóm khả dụng. Chọn Anthropic Messages nếu có. Với tiện ích VS Code, theo hướng dẫn gateway chính thức cho claudeCode.environmentVariables; trình soạn thảo mở từ Dock hoặc menu Start không tự kế thừa biến xuất từ terminal.

Nếu lịch sử yêu cầu có lệnh gọi bổ sung đến tên sonnet, opus hoặc haiku không khả dụng, ánh xạ bí danh cần thiết vào cùng nhóm Messages khả dụng hoặc các nhóm khác tài khoản có thể dùng:

Ví dụ cấu hình
export ANTHROPIC_DEFAULT_SONNET_MODEL=xcoffee-coding
export ANTHROPIC_DEFAULT_OPUS_MODEL=xcoffee-coding
export ANTHROPIC_DEFAULT_HAIKU_MODEL=xcoffee-coding

Xử lý sự cố

  • Với Model isn't recognized, kiểm tra nhóm và giao thức. Kích thước ngữ cảnh ứng dụng giả định không phải cam kết năng lực từ XCoffee.
  • Khi có xung đột xác thực, kiểm tra ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN và tệp cài đặt trước khi thay khóa.
  • Nếu upstream từ chối trường công cụ thử nghiệm, chỉ dùng cách chạy thu hẹp sau khi cần xử lý lỗi:
Ví dụ cấu hình
env -u ANTHROPIC_API_KEY \
  ANTHROPIC_BASE_URL=https://api.xcoff.ee \
  ANTHROPIC_AUTH_TOKEN="$XCOFFEE_API_KEY" \
  ENABLE_TOOL_SEARCH=false \
  CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1 \
  claude --model xcoffee-coding

Kiểm tra trả lời cơ bản, đọc tệp thử và tạo rồi đọc lại tệp trước khi dùng dự án thật. Tính năng còn phụ thuộc upstream và phiên bản ứng dụng.

Codex CLI: hồ sơ riêng và cách chạy

1. Kiểm tra phiên bản và giao thức

Cài Codex CLI theo hướng dẫn OpenAI chính thức, rồi chạy codex --version. Chọn OpenAI Responses trong bảng điều khiển API XCoffee và xác nhận tên nhóm. Hồ sơ riêng bên dưới dành cho Codex CLI 0.134.0 trở lên.

2. Tạo tệp hồ sơ XCoffee

Tạo ~/.codex/xcoffee.config.toml (%USERPROFILE%\.codex\xcoffee.config.toml trên Windows). Sao lưu và hợp nhất tệp hiện có, tránh khai báo bảng trùng. Thay xcoffee-coding bằng nhóm Responses khả dụng:

Ví dụ cấu hình
model = "xcoffee-coding"
model_provider = "xcoffee"
model_reasoning_effort = "medium"

[model_providers.xcoffee]
name = "XCoffee"
base_url = "https://api.xcoff.ee/v1"
env_key = "XCOFFEE_API_KEY"
wire_api = "responses"
requires_openai_auth = false
supports_websockets = false

Dùng cài đặt cấp cao nhất trong tệp, không bọc bằng [profiles.xcoffee]. --profile hiện đọc tệp riêng. env_key là tên biến môi trường, không phải khóa thật; không cần viết lại auth.json.

3. Đặt khóa và chạy

Đặt XCOFFEE_API_KEY trong cùng terminal theo các bước trên, vào thư mục thử rồi chạy:

Ví dụ cấu hình
codex --profile xcoffee

Lệnh khởi động giống nhau trong PowerShell. Bắt đầu phiên mới, yêu cầu một câu trả lời ngắn, thử đọc và ghi tệp thử, rồi kiểm tra lịch sử yêu cầu XCoffee.

Để bật tìm kiếm web, thêm --search. Đây là tùy chọn cấp cao nhất và phải đứng trước exec (codex exec --search sẽ thất bại).

Tương tác:

Ví dụ cấu hình
codex --profile xcoffee --search

Không tương tác:

Ví dụ cấu hình
codex --profile xcoffee --search exec "…"

Hồ sơ chỉ áp dụng khi bạn chọn. Tiếp tục cách chạy cũ để dùng mặc định toàn cục. Ứng dụng cũ và giao diện cần nhà cung cấp toàn cục có thể hợp nhất cùng cài đặt vào ~/.codex/config.toml cấp người dùng rồi chạy codex, nhưng sẽ đổi mặc định toàn cục. Không đặt định tuyến thông tin xác thực trong .codex/config.toml của dự án.

Xử lý sự cố

  • 401: kiểm tra terminal chạy Codex có XCOFFEE_API_KEY và đó là khóa khách hàng XCoffee.
  • Mô hình hoặc điểm cuối không hỗ trợ: xác nhận nhóm đã bật Responses. Cấu hình Codex này không dùng Chat Completions.
  • Vẫn gọi nhà cung cấp khác: kiểm tra --profile xcoffee và tham số dòng lệnh ghi đè.
  • XCoffee dùng HTTP Responses nên ví dụ tắt WebSocket. Gửi đầy đủ lịch sử; không có previous_response_id và hội thoại lưu tại upstream. Không sao chép kích thước ngữ cảnh mô hình chính thức vào cấu hình nhóm.

Agent con và công cụ cục bộ khác công cụ do nhà cung cấp lưu trữ. Nhiều agent dùng chung điểm và đồng thời của tài khoản. Xem phạm vi hỗ trợ và bảng điều khiển để biết tìm kiếm cùng năng lực bổ sung.

OpenClaw: thêm nhà cung cấp XCoffee
  1. Cài OpenClaw và chạy openclaw --version. Sao lưu ~/.openclaw/openclaw.json trước.
  2. Chọn Chat Completions trong bảng điều khiển API và xác nhận tên nhóm.
  3. Hợp nhất vào cấu hình hiện có, giữ các nhà cung cấp, agent và kênh khác. Thay xcoffee-coding trong ví dụ bằng nhóm khả dụng:
Ví dụ cấu hình
{
  "models": {
    "mode": "merge",
    "providers": {
      "xcoffee": {
        "baseUrl": "https://api.xcoff.ee/v1",
        "api": "openai-completions",
        "apiKey": {
          "source": "env",
          "provider": "default",
          "id": "XCOFFEE_API_KEY"
        },
        "models": [{ "id": "xcoffee-coding", "name": "XCoffee Coding" }]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": { "primary": "xcoffee/xcoffee-coding" }
    }
  }
}

xcoffee/ là tiền tố nhà cung cấp nội bộ của OpenClaw; model gửi đến XCoffee vẫn là xcoffee-coding. SecretRef đọc biến môi trường cục bộ thay vì lưu khóa thật vào JSON. Cung cấp XCOFFEE_API_KEY cho tiến trình thực sự chạy OpenClaw.

  1. Khởi động hoặc khởi động lại OpenClaw theo thiết lập hiện có. Nếu Gateway chạy dạng dịch vụ, cấu hình biến cho dịch vụ đó; xuất biến trong terminal khác không cập nhật dịch vụ đang chạy.
  2. Kiểm tra cấu hình và danh sách mô hình bằng các lệnh sau, rồi thử hội thoại mới, gồm trả lời cơ bản và công cụ cục bộ:
Ví dụ cấu hình
openclaw models status
openclaw models list

Kiểm tra trạng thái hay danh sách không xác nhận tạo nội dung hoạt động. Danh sách mô hình cho phép ở cấp agent hoặc ghi đè model theo phiên cũng có thể cần chọn xcoffee/xcoffee-coding. Dùng ngữ cảnh và năng lực hình ảnh thực của nhóm thay vì sao chép số từ nhà cung cấp khác.

Hermes: cấu hình terminal và Telegram

Thoát phiên Hermes hiện tại, rồi chạy:

Ví dụ cấu hình
hermes model
  1. Chọn Custom endpoint, không chọn gói đăng ký ChatGPT hay đăng nhập Anthropic chính thức.
  2. Nhập Base URL https://api.xcoff.ee/v1 và dùng khóa khách hàng làm API key.
  3. Nếu hỏi transport, chọn chat_completions. Dùng xcoffee-coding hoặc nhóm khả dụng khác trong bảng điều khiển API.
  4. Ban đầu để trống độ dài ngữ cảnh để tự khám phá. Giá trị dự phòng 256K hiển thị không xác nhận năng lực thực của mọi thành viên nhóm.
  5. Lưu, chạy hermes và thử phiên mới.

Phiên bản hỗ trợ nhà cung cấp có tên cũng có cách khác: sao lưu ~/.hermes/config.yaml và hợp nhất mục này vào providers hiện có. Nó dùng biến môi trường đã đặt:

Ví dụ cấu hình
providers:
  xcoffee:
    api: https://api.xcoff.ee/v1
    key_env: XCOFFEE_API_KEY
    transport: chat_completions
    default_model: xcoffee-coding

Dùng /model để chọn nhóm XCoffee. Với Telegram, cấu hình máy và thư mục cấu hình chạy gateway Hermes, không chỉ máy khác. Cung cấp biến cho dịch vụ gateway; xuất biến từ terminal không cập nhật dịch vụ đang chạy. Khởi động lại gateway bằng trình quản lý dịch vụ hiện có và thử phiên mới vì phiên cũ có thể giữ lựa chọn mô hình riêng. Lưu khóa cục bộ; không gửi khóa cho bot Telegram.

Pi: thêm nhóm tùy chỉnh

Phần này nói về coding agent pi-mono. Đặt XCOFFEE_API_KEY ở trên rồi sao lưu và sửa ~/.pi/agent/models.json (hoặc tệp trong thư mục agent tùy chỉnh). Hợp nhất xcoffee vào providers, giữ nhà cung cấp khác:

Ví dụ cấu hình
{
  "providers": {
    "xcoffee": {
      "baseUrl": "https://api.xcoff.ee/v1",
      "api": "openai-completions",
      "apiKey": "${XCOFFEE_API_KEY}",
      "models": [
        { "id": "xcoffee-coding", "name": "XCoffee Coding" },
        { "id": "xcoffee-fast", "name": "XCoffee Fast" },
        { "id": "xcoffee", "name": "XCoffee" }
      ]
    }
  }
}

Chỉ giữ nhóm khả dụng trong bảng điều khiển API. apiKey tham chiếu biến môi trường; không thay bằng bí mật thật trong tệp. Chạy pi và chọn XCoffee bằng /model; mở lại bộ chọn sẽ tải lại cấu hình. Không sao chép ngữ cảnh hoặc năng lực hình ảnh của mô hình khác. Dùng năng lực được công bố của nhóm khi cần siêu dữ liệu cụ thể.

Cursor: kiểm tra tùy chọn điểm cuối tùy chỉnh trước
  1. Mở Cursor Settings → Models và tìm cài đặt khóa API.
  2. Nếu phiên bản có ghi đè OpenAI Base URL hoặc nhà cung cấp tùy chỉnh, nhập https://api.xcoff.ee/v1 và khóa khách hàng.
  3. Nếu thêm được tên mô hình tùy chỉnh, thêm nhóm khả dụng như xcoffee-coding rồi chọn trong bộ chọn mô hình hội thoại.
  4. Thử hội thoại mới bằng ba tác vụ bên dưới. Chỉ xác minh khóa thành công chưa xác minh được sửa tệp hay chạy công cụ.

Nếu không có các cài đặt tùy chỉnh này, không nhập khóa XCoffee vào điểm cuối nhà cung cấp chính thức. Tài liệu BYOK chính thức của Cursor không đảm bảo hỗ trợ ID nhóm bên thứ ba tùy ý. Đây là hướng dẫn có điều kiện, không phải chứng nhận tương thích đầy đủ XCoffee/Cursor. Khóa tùy chỉnh không thay thế mô hình tích hợp của Cursor Tab. Agent, mô hình suy luận và tính năng chuyên biệt khác tùy phiên bản Cursor và phạm vi hỗ trợ. Yêu cầu đi qua backend Cursor, không hoàn toàn kết nối trực tiếp từ máy bạn.

Xác minh bằng ba tác vụ nhỏ

Chạy Agent trong thư mục thử trống rồi gửi lần lượt:

  1. “Chỉ trả lời: kết nối thành công.” Kiểm tra hội thoại cơ bản.
  2. “Liệt kê tệp trong thư mục thử này.” Kiểm tra gọi công cụ cục bộ.
  3. “Tạo hello.txt chứa Hello XCoffee rồi đọc lại.” Phê duyệt thao tác tệp thử khi ứng dụng hỏi.

Sau đó kiểm tra lịch sử yêu cầu của khóa và điểm trong trung tâm người dùng. Chỉ có phản hồi văn bản không chứng minh công cụ hoạt động. Khi báo lỗi, gửi phiên bản ứng dụng, thời gian, nhóm và mã lỗi hoặc ID yêu cầu. Không gửi khóa hay bản ghi hội thoại riêng tư.

Nhờ Agent cấu hình kết nối

Gửi nội dung này cho Agent đọc được trang web và sửa cấu hình cục bộ. Thay “ứng dụng của tôi” bằng Claude Code, Codex hoặc công cụ bạn chọn:

Ví dụ cấu hình
Đọc https://api.xcoff.ee/vi/guide và giúp kết nối “ứng dụng của tôi” với XCoffee.
Kiểm tra phiên bản ứng dụng và sao lưu cấu hình trước. Chỉ đổi cài đặt kết nối, giữ nhà cung cấp khác.
Dùng xcoffee-coding nếu có trong bảng điều khiển API; nếu không, hỏi tôi chọn nhóm khả dụng.
Tôi sẽ tự đặt XCOFFEE_API_KEY trên máy. Không đọc, hiển thị hoặc yêu cầu tôi dán khóa.
Theo giao thức và URL trong hướng dẫn. Không tự đặt kích thước ngữ cảnh hoặc tắt yêu cầu phê duyệt thao tác công cụ.
Giải thích cách chạy và xác minh thiết lập. Không sửa hoặc triển khai dự án khác.

Đây là chỉ dẫn cho Agent, không phải trình cài trên web tự thay đổi máy bạn.

Giao thức và địa chỉ

Thay https://YOUR_HOST bằng địa chỉ gốc của trang và YOUR_GROUP bằng tên nhóm khả dụng. Điểm cuối không có tiền tố ngôn ngữ.

Giao thứcBase URL ứng dụngĐiểm cuối tạo nội dungHeader khóa
OpenAI Chat Completionshttps://YOUR_HOST/v1/v1/chat/completionsAuthorization: Bearer YOUR_KEY
OpenAI Responseshttps://YOUR_HOST/v1/v1/responsesAuthorization: Bearer YOUR_KEY
Anthropic Messageshttps://YOUR_HOST/v1/messagesx-api-key: YOUR_KEY
Gemini nativehttps://YOUR_HOST/v1beta/models/YOUR_GROUP:generateContentx-goog-api-key: YOUR_KEY

Có JSON và truyền trực tiếp SSE. Anthropic cũng chấp nhận Bearer và yêu cầu header anthropic-version (mặc định 2023-06-01). Gemini truyền trực tiếp dùng :streamGenerateContent?alt=sse; đặt khóa trong header, không trong truy vấn URL. Khám phá mô hình dùng /v1/models hoặc /v1beta/models và cần khóa.

Quản trị viên phải bật từng API được hỗ trợ cho upstream. Upstream hiện có mặc định Chat Completions; thêm điểm cuối trên trang không khiến nhà cung cấp chỉ có Chat hỗ trợ API gốc. Trung tâm người dùng liệt kê nhóm theo giao thức đã chọn. Lệnh gọi hàm/công cụ phía ứng dụng và trường cấu trúc được chuyển tiếp; hỗ trợ cụ thể vẫn tùy mô hình.

Ví dụ Responses

Ví dụ cấu hình
curl https://YOUR_HOST/v1/responses \
  -H "Authorization: Bearer $CUSTOMER_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"YOUR_GROUP","input":"Hello","max_output_tokens":128,"stream":true,"store":false}'

Ví dụ Anthropic

Ví dụ cấu hình
curl https://YOUR_HOST/v1/messages \
  -H "x-api-key: $CUSTOMER_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{"model":"YOUR_GROUP","messages":[{"role":"user","content":"Hello"}],"max_tokens":128,"stream":true}'

Ví dụ Gemini

Ví dụ cấu hình
curl 'https://YOUR_HOST/v1beta/models/YOUR_GROUP:streamGenerateContent?alt=sse' \
  -H "x-goog-api-key: $CUSTOMER_KEY" \
  -H "Content-Type: application/json" \
  -d '{"contents":[{"role":"user","parts":[{"text":"Hello"}]}],"generationConfig":{"maxOutputTokens":128}}'
Cài đặt ứng dụng và phạm vi hỗ trợ

Ứng dụng như Codex, Claude Code và Gemini CLI cần cấu hình đúng giao thức HTTP, URL nhà cung cấp tùy chỉnh và tên nhóm khả dụng. Đặt ngân sách đầu ra phù hợp với mô hình upstream. Trang hỗ trợ các đường dẫn API này, không phải mọi tính năng của mọi phiên bản CLI.

Ngân sách đầu ra mặc định là 4096 token. Giới hạn nhóm mặc định là 128.000 cho coding, 32.000 cho fast và 64.000 cho xcoffee; người vận hành có thể chỉnh. Giới hạn thấp hơn của upstream vẫn áp dụng, độc lập với độ dài ngữ cảnh. Ngân sách yêu cầu lớn hơn được giảm về trần. Chat dùng max_tokens hoặc max_completion_tokens, Responses dùng max_output_tokens, Anthropic dùng max_tokens, Gemini dùng generationConfig.maxOutputTokens. Mức suy luận chỉ định bị giới hạn ở medium; mức thấp hơn giữ nguyên. Ngân sách suy nghĩ dạng số có trần riêng. Không thêm tham số suy luận khi chưa bật. Suy luận mặc định của upstream không có điều khiển công khai vẫn do upstream quản lý. Token suy luận được báo cáo tính một lần vào đầu ra.

Gửi đầy đủ lịch sử hội thoại. Responses luôn chuyển store:false; không có previous_response_id, hội thoại lưu, chạy nền và tham chiếu tệp upstream dùng chung. Có thể chuyển tiếp mục suy luận mã hóa do ứng dụng mang theo. Tìm kiếm web chỉ hỗ trợ Responses (web_search, Codex) và Anthropic (web_search_*, Claude Code). Mỗi lượt gateway báo cáo tốn 1 điểm ngoài token, tối đa 50 lượt mỗi ngày UTC. Chat web_search_options và Gemini googleSearch / googleSearchRetrieval bị gỡ trước khi chuyển, phần còn lại giữ nguyên. Cache lưu và tham chiếu tệp từ xa Gemini, container/MCP do máy chủ Anthropic quản lý, web_fetch, chạy mã, API tải tệp, tạo ảnh và WebSocket nằm ngoài tập điểm cuối này. Nội dung nhúng vẫn tùy mô hình upstream.

Sử dụng chung và giới hạn

Mọi khóa, giao thức và nhóm dùng chung điểm ngày, điểm giờ trượt, tốc độ yêu cầu và đồng thời của tài khoản. Xem bảng điều khiển người dùng để biết hạn mức hiện tại. Điểm ngày đặt lại lúc 00:00 UTC, không chuyển dư. Hạn mức ngày và giờ trượt được đặt riêng theo gói đã mua, không tính từ số dư ngày còn lại. Yêu cầu qua nửa đêm thuộc ngày UTC bắt đầu; sử dụng giờ trượt không đặt lại. Tạm dừng, xóa hoặc thay khóa không đặt lại sử dụng hay kéo dài hiệu lực.

Đồng thời và giới hạn yêu cầu/token mỗi phút hay cửa sổ trượt khác tùy gói đã mua; dùng điều kiện xác nhận khi mua và quyền đang hoạt động trong bảng điều khiển. Mọi khóa dùng chung giới hạn và luồng giữ vị trí đồng thời đến khi kết thúc. Khi áp dụng yêu cầu có trọng số, tổng đầu vào gồm cache tốn 1 đơn vị đến 32.000 token, 2 khi vượt mức đó và 4 khi trên 80.000. Điểm đầu vào/đầu ra được giữ trước khi chuyển tiếp và đối soát khi hoàn tất. Không tính thêm hoặc đổi giá hồi tố cho lịch sử.

Điểm = (đầu vào không cache + đọc cache × hệ số cache + đầu ra × hệ số đầu ra) ÷ token tính phí mỗi điểm × hệ số nhóm, cộng 1 điểm cho mỗi lượt tìm kiếm web được báo cáo trên Responses hoặc Anthropic. Xem bảng điều khiển người dùng để biết đơn giá, hạn mức và số lượt tìm kiếm hôm nay; xem nhóm mô hình trang chủ để biết hệ số nhóm. Ghi cache tính đủ giá; thiếu chi tiết cache không giảm phí. Đọc/ghi cache Anthropic thuộc tổng đầu vào chuẩn hóa; cache Gemini đã thuộc đầu vào prompt. Suy luận báo cáo tính vào đầu ra một lần. Điểm hiển thị hai chữ số thập phân, lưu độ chính xác 10^-8. Điểm cuối đếm token không tốn điểm nhưng vẫn chiếm hạn mức yêu cầu và đồng thời. Giới hạn tìm kiếm là 50 mỗi tài khoản mỗi ngày UTC, chỉ áp dụng Responses và Anthropic; yêu cầu bắt đầu dưới trần có thể kết thúc hơi vượt trần.

POST /v1/messages/count_tokens và POST /v1beta/models/YOUR_GROUP:countTokens yêu cầu quản trị viên bật đếm token gốc cho upstream. Chúng dùng khóa và quyền nhóm của bạn, tiêu thụ lượt yêu cầu cùng vị trí đồng thời nhưng không tiêu thụ token tạo nội dung. Số đếm là ước tính của upstream.

Từ chối rõ ràng trước tạo nội dung tiêu thụ lượt yêu cầu nhưng không tiêu thụ token. Lệnh gọi gián đoạn hoặc thiếu dữ liệu sử dụng giữ ước tính thận trọng, không miễn phí. Xem ngày còn lại, tổng hôm nay và sử dụng từng khóa trong trung tâm người dùng.

Trong một nhóm, từ chối rõ ràng trước tạo nội dung (401/403/404/405/429) có thể thử upstream cấu hình khác, tổng cộng tối đa ba đích khác nhau. Yêu cầu giữ một phần hạn mức dự phòng và một bản ghi sổ. Không tự chạy lại lỗi mạng, 5xx, hủy hoặc phản hồi đã bắt đầu; định tuyến nhóm mô hình riêng của Magpie cấu hình độc lập.

Lỗi và hỗ trợ

Với 401 kiểm tra khóa và thẻ; 403 kiểm tra quyền nhóm; 429 kiểm tra giới hạn tài khoản/upstream; 502/503/504 kiểm tra upstream, tương thích giao thức và thời gian chờ. Thử lại mù sau đầu ra một phần có thể tiêu thụ thêm hạn mức.

Gửi thời gian và ID yêu cầu qua hỗ trợ trong trung tâm người dùng. Không gửi khóa hoặc prompt đầy đủ nhạy cảm.

Tài liệu chính thức và ngày cập nhật

Tài liệu cấu hình ứng dụng được kiểm tra ngày 7 tháng 11 năm 2026. Bảng điều khiển API XCoffee vẫn là nguồn xác định nhóm, giao thức và hạn mức khả dụng.