Tencent TokenHub API 接続ガイド

サイト、権限、モデルを確認する

Tencent TokenHub の OpenAI 互換 Chat Completions を利用する手順です。権限を持つアカウント、対象地域の TokenHub API キー、有効化したモデルサービスが必要です。プロトコル互換はリクエストの形式であり、OpenAI や Anthropic の全モデルの供給を示しません。SDK 名から GPT や Claude の利用可否を推定しないでください。

サイト、地域、請求アカウント、モデルの有効化、ネットワークを記録します。モデル一覧とアカウントの有効化は別です。online は ID 選択の手掛かりですが、権限、残高、クォータの確認を代用しません。Responses、ツール、キャッシュ、推論、マルチモーダル対応もモデルごとに調べます。

現在の地域エンドポイントを選ぶ

標準の Base URL はシンガポールが https://tokenhub-intl.tencentmaas.com/v1、広州が https://tokenhub.tencentmaas.com/v1 です。本例はシンガポールを使用します。キーは有効化したサイトと地域に合わせ、相互に流用しないでください。旧手順の別ドメインをそのまま使わず、代替ホストも現在の公式表で確認します。

シンガポールのリソース配置範囲はグローバルです。接続先がシンガポールでも、推論がそこだけに留まる保証にはなりません。広州は異なる範囲です。機密資料の前に処理、ログ、契約条件を確認し、ドメイン変更で承認済みの境界を迂回しないでください。

インストールとモデル ID の取得

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

次は仮設定です。TOKENHUB_API_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() は認証付き GET /v1/models に対応し、キーではなく ID と status を表示します。online のテキストモデルを選び、アカウントでの有効化をコンソールでも確認して 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は例の制御であり、サービスのクォータや応答保証ではありません。

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 フレームも検出します。HTTP200 のヘッダー送信後に失敗することもあります。途中回答を完了扱いにせず、再試行で外部操作を重複させないでください。

障害調査と受入確認

• 401/401002：キーの有効性とシンガポール・広州との一致を確認する。
• 402/402xxx：モデル有効化、残高、請求を確認し、プロトコル非対応と即断しない。
• 400/404：ID、経路、モデルのパラメーターを確認し、任意機能を外して絞り込む。
• 429/429xxx：呼び出し、トークン、同時実行を確認し、Retry-After があれば従って有限の再試行を行う。
• タイムアウト/5xx/ストリームエラー：機密情報を除いた番号と時刻を残し、状態を確認する。認証ヘッダー全体を記録しない。

モデルと経路ごとの使用量を請求と照合し、キャッシュ、推論、追加機能も確認します。他経路の単価や削減約束を流用しないでください。公開前に打ち切り、空の使用量チャンク、中断、権限、残高不足を検証し、出力、同時実行、全体時間の上限を定めます。ログ最小化、キー更新、終了手続きの責任者も決めます。

本例はオフライン構文と合成ストリームの確認のみです。実キーの読み取り、アカウントのモデル一覧取得、モデル呼び出しは行っていません。利用可否と料金は承認された環境で検証してください。

公式資料

確認日：2026-10-17。

• TokenHub API、地域、モデル一覧
• モデルのプロトコルとエラー
• Chat フィールドとストリームエラー