騰訊 TokenHub API 接入指南

先確認站點、服務權限與模型

本指南使用騰訊TokenHub的OpenAI相容Chat Completions介面。前提是已有獲授權的帳號、相應地區的TokenHub API Key，並已開通擬呼叫的模型服務。協定相容說明請求格式，不表示平台銷售全部OpenAI或Anthropic模型；不要因用戶端名稱推斷GPT或Claude供應情況。

先記錄站點、地區、計費帳號、模型服務開通狀態及網路存取方式。模型目錄和帳號開通是兩項檢查：清單中的online狀態可協助選型，但不能代替該帳號的模型授權、餘額與配額核對。Responses、工具、快取、推理和多模態能力也要按具體模型分別確認。

選擇當前地區端點

目前預設OpenAI相容Base URL為新加坡 https://tokenhub-intl.tencentmaas.com/v1 或廣州 https://tokenhub.tencentmaas.com/v1。以下以新加坡為例，Key與服務開通站點、地區必須一致，不能跨站點混用。不要照搬舊教學中的其他網域；若需備用接入，按官方當期表格核對後再實施。

新加坡的資源調度範圍為全球，不能把新加坡接入當成推論只在新加坡進行的保證。廣州的調度範圍與國際站不同。涉及敏感資料時先確認實際處理、日誌和合約條件，不透過切換網域繞過既定資料邊界。

安裝、查詢實際模型ID

python3 -m venv .venv
. .venv/bin/activate
python -m pip install --upgrade openai

以下為占位設定；由授權服務端環境安全注入 TOKENHUB_API_KEY，不要把Key放入瀏覽器或儲存庫。先保留模型占位值，查詢後再填寫。

export TOKENHUB_BASE_URL='https://tokenhub-intl.tencentmaas.com/v1'
export TOKENHUB_MODEL='YOUR-ACTUAL-ONLINE-MODEL-ID'

儲存以下初始化至 tokenhub_chat.py。client.models.list()對應帶Bearer認證的 GET /v1/models，只輸出模型ID與status，不輸出金鑰。選擇當前清單中的online文字模型，另在控制台核對該帳號服務已開通，再把ID填入 TOKENHUB_MODEL。不要從範例日期推斷型號長期可用。

import os
from openai import OpenAI

client = OpenAI(
    base_url=os.environ["TOKENHUB_BASE_URL"],
    api_key=os.environ["TOKENHUB_API_KEY"],
    timeout=30.0,
    max_retries=0,
)
for item in client.models.list().data:
    print(item.id, getattr(item, "status", "status unavailable"))

發出最小聊天請求

確認測試權限和費用後，把以下程式接在初始化後執行 python tokenhub_chat.py。先選支援一般文字與 max_tokens 的模型。128輸出上限、30秒用戶端逾時和0次SDK自動重試都是範例控制值，不是平台配額或回應承諾。

request = {
    "model": os.environ["TOKENHUB_MODEL"],
    "messages": [{"role": "user", "content": "Reply with one short greeting."}],
    "max_tokens": 128,
}
answer = client.chat.completions.create(**request)
if not answer.choices:
    raise RuntimeError("No completion choice returned")
print(answer.choices[0].message.content or "")
print("finish_reason:", answer.choices[0].finish_reason)
print(answer.usage.model_dump() if answer.usage else "usage unavailable")

檢查finish reason，區分正常完成、長度截斷、內容篩選與工具請求。HTTP200或收到一段文字，不足以證明業務問題已解決。首次測試維持單次短請求，確認計量和權限後再考慮並行。

串流輸出與用量

用下面程式替換非串流呼叫。檢查空choices，讀取 delta.content 並單獨儲存usage；結束原因出現後繼續讀取至串流結束，避免漏掉尾部用量區塊。不同模型的快取明細可能不同，沒有usage不能視為零收費。此例不解析推理內容或工具參數。

from openai import APIError

usage = None
finish_reason = None
try:
    with client.chat.completions.create(
        **request, stream=True, stream_options={"include_usage": True}
    ) as events:
        for part in events:
            if part.usage is not None:
                usage = part.usage
            if not part.choices:
                continue
            choice = part.choices[0]
            if choice.delta.content:
                print(choice.delta.content, end="", flush=True)
            if choice.finish_reason is not None:
                finish_reason = choice.finish_reason
except APIError:
    print("Stream failed; partial output is not a completed task.")
    raise
print()
print("finish_reason:", finish_reason)
print(usage.model_dump() if usage else "usage unavailable")

SDK例外必須記錄為失敗。自寫SSE解析器還要識別串流中 error 事件；即使回應標頭已是200，也可能中途出錯。不要把部分回答寫成成功結果，或在重試時重複執行外部動作。

錯誤排查與驗收

• 401/401002：檢查Key與新加坡／廣州站點是否匹配及是否有效。
• 402或402xxx：檢查模型服務開通、額度與計費安排，不能誤判為不支援該協定。
• 400/404：核對實際ID、API路徑和模型可用參數，先移除可選功能。
• 429/429xxx：檢查呼叫量、Token和並行量；有Retry-After時遵循等待提示，並限制退避重試總量。
• 逾時/5xx/串流錯誤：保留去識別化請求編號和時間，核對任務狀態後決定重試，不記錄完整認證標頭。

按模型與呼叫路徑儲存用量，核對快取、推理及附加功能費用；不要套用其他渠道價格或預先承諾節省。上線前測試截斷、空用量區塊、中途失敗、權限與額度不足，並設定並行、輸出與總任務時限。日誌最小化、金鑰輪替和退出安排由實際帳號負責人落實。

本例只作離線語法與合成串流檢查，未讀取真實Key、查詢你的模型清單或呼叫模型；帳號可用性與費用須在獲授權環境驗證。

官方依據

核驗日期：2026-10-17。

• TokenHub API、地區與模型清單
• 模型協定支援與錯誤分類
• Chat Completions欄位與串流錯誤