Tencent TokenHub API setup

Check the site, permissions and model first

This guide uses Tencent TokenHub’s OpenAI-compatible Chat Completions interface. Start with an authorised account, a TokenHub API key for the required region and an enabled model service. Protocol compatibility describes request format; it does not establish that every OpenAI or Anthropic model is sold through the platform. Do not infer GPT or Claude availability from the client library’s name.

Record the site, region, billing account, service activation and network access. A model directory and account activation are separate checks. An online listing helps select an ID, but does not replace verification of the account’s permissions, balance and quota. Check Responses, tools, caching, reasoning and multimodal features for the particular model.

Select the current regional endpoint

The default OpenAI-compatible base is https://tokenhub-intl.tencentmaas.com/v1 for Singapore or https://tokenhub.tencentmaas.com/v1 for Guangzhou. This example uses Singapore. Match the key to the activated site and region; they are not interchangeable. Avoid domains copied from older tutorials. Verify any alternate host against current official guidance before changing a working configuration.

Singapore has a global resource scheduling scope. Its access endpoint does not guarantee that inference stays in Singapore. Guangzhou has a different scope. For sensitive material, review actual processing, logging and contractual requirements before use; changing a hostname is not a way to bypass an approved data boundary.

Install and discover the actual model ID

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

These are placeholders. Have an authorised server environment supply TOKENHUB_API_KEY; keep it out of browser code and source control. Leave the model placeholder until discovery is complete.

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

Save this initialisation as tokenhub_chat.py. The SDK list operation maps to authenticated GET /v1/models. It prints IDs and status, not the key. Choose an online text model, confirm its activation for your account in the console, then set TOKENHUB_MODEL. A dated example does not guarantee continuing availability.

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"))

Make a minimal chat request

After approving test access and charges, append this code and run python tokenhub_chat.py. Select a model supporting ordinary text and max_tokens. The cap of 128, client timeout of 30 seconds and disabled SDK retries are example controls rather than service quotas or response commitments.

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")

Inspect the finish reason to distinguish completion, truncation, filtering and tool requests. HTTP 200 or some returned text is not proof that the business task succeeded. Start with one short request and check permission and metering before adding concurrency.

Handle streaming and usage

Replace the non-streaming call with this code. Guard empty choices, consume text deltas and capture usage independently. Continue reading after a finish reason to avoid losing later usage. Cache details can differ by model; absent usage does not mean zero charges. This example does not parse reasoning or tool arguments.

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")

Treat SDK exceptions as failures. A custom SSE parser must also detect in-stream error frames: an error can occur after HTTP 200 headers. Do not report partial output as completion or repeat external actions blindly on a retry.

Troubleshoot and accept the integration

401/401002: check validity and whether the key matches Singapore or Guangzhou.
402/402xxx: check model activation, credits and billing; this is not automatically a protocol-support problem.
400/404: verify exact ID, route and model parameters, removing optional features first.
429/429xxx: check requests, tokens and concurrency. Honour Retry-After where supplied and bound total retries.
Timeout/5xx/stream error: retain sanitised request identifiers and times, check task state and avoid recording full authentication headers.

Reconcile model and route usage, including relevant cache, reasoning and extra feature charges, under the actual billing arrangement. Do not import another channel’s prices or promise savings. Before release, test truncation, empty usage chunks, interrupted streams, permission failures and insufficient credit. Set concurrency, output and overall task limits. Assign responsibility for minimal logs, key rotation and exit arrangements.

Only offline syntax and synthetic stream checks were performed. No real key was read, no account model list was fetched and no model was called. Account availability and costs need verification in an authorised environment.

Official references

Checked on 17 October 2026.