Wire Hy4 In With Three Params: Five Steps and Three Traps

Wiring a large language model into your own scripts rarely fails because the model is weak. It fails on the first call: a wrong base URL, a mistyped auth header, a model name with one extra prefix, and the endpoint returns an error code you cannot parse. When Tencent shipped the official Hunyuan Hy4 on November 4, 2026, the documented path was short: the same OpenAI or Anthropic SDK code you already have usually runs after swapping three values, the Base URL, the API key, and the model. The word "usually" hides regional sites, protocol paths, naming rules, per-model capability gaps, error codes, and mid-stream failures. Any one out of place stops the call. This SOP lays them out so the first request goes through.

First, the boundaries. This article covers one job: getting the official Hy4 API into your workflow, from creating a key to passing verification. It does not do billing math, which belongs to the LLM API pricing comparison; it does not cover the launch event, the subject of two hotspot articles on the official release and the August 28 preview open-source announcement; and choosing among models for vision input is this batch's multi-model vision comparison. One point matters most: the weights of the official Hy4 release have not been open-sourced. The vendor says it will publish the model weights and a system card in the near future, so this article is about hosted API access only, with no self-hosting path for the official release. A separate self-hosting SOP on the site targets the previous-generation hy4-preview weights on vLLM and SGLang, a different road entirely. The five steps below are followed by three traps and three pricing ledgers; dates are absolute, and figures follow Tencent Cloud documentation and the November 4, 2026 disclosures.

The map: one gateway, three knobs, two protocol families

Tencent Cloud places Hy4 behind a single gateway, TokenHub. OpenAI-style and Anthropic-style requests both land on one Base URL; TokenHub dispatches by path and authenticates at that same layer, so you keep your existing client and change three values. The Base URL sets the region and protocol entry, the API key controls authentication, and the model picks the target. Three protocol paths hang off the same Base URL: /v1/chat/completions speaks OpenAI Chat Completions, covers every model, and is the most universal; /v1/responses speaks OpenAI Responses with limited model support; /v1/messages speaks Anthropic Messages. The auth header follows the family: the two OpenAI paths use Authorization: Bearer YOUR_API_KEY, the Anthropic path uses x-api-key: YOUR_API_KEY. YOUR_API_KEY is a documentation placeholder; real scripts read the key from an environment variable and never commit it. Mark one red line early: the TokenHub model name is hy4, while the OpenRouter id is tencent/hy4, and neither belongs in the other's slot.

Step 1: Get the key and enable the model (where 402 comes from)

Step one happens in the Tencent Cloud TokenHub console: create an API key and enable the Hy4 model service, in that order, without stopping halfway. Many people fire a request immediately, get a 402, and blame auth or payload syntax, when the service was never enabled. The documentation is explicit that 402 is protocol-independent: OpenAI and Anthropic paths alike return it, and calls made before enablement or with exhausted quota land in the 402xxx family. After enabling, confirm what is online with a read-only GET /v1/models under the same Base URL and auth header. The documented sample response contains {"id":"hy4","status":"online"}, where id is the value for the model field in step two and a status of online means callable:

{
  "data": [
    {"id": "hy4", "status": "online"},
    {"id": "hy4-preview", "status": "online"}
  ]
}

One more thing almost everyone hits once: Guangzhou and Singapore are independent sites with separate API keys. A key created in Guangzhou cannot be used against Singapore, or the reverse. Decide the region while creating the key, because the Base URL and key must be a matched pair; this split reappears under 401002.

Step 2: Change three parameters: region, path, auth header

The official line that the same SDK code usually only needs the Base URL, API key, and model replaced becomes three concrete edits. Pick a Base URL by region: Guangzhou uses https://tokenhub.tencentmaas.com/v1, Singapore uses https://tokenhub-intl.tencentmaas.com/v1, and the international docs also list an equivalent https://tokenhub-intl.tencentcloudmaas.com/v1 for the same Singapore site, so choose one and do not concatenate hostnames. The regions are independent sites, API keys are not shared, and the Base URL and key must be paired.

Paths and headers line up below. All three paths sit under one Base URL, so switching protocols changes the path and auth header, not the hostname:

YOUR_API_KEY stays a placeholder and real scripts use an environment variable. A standard call looks like this OpenAI-style curl example, with the key read from the environment:

curl https://tokenhub.tencentmaas.com/v1/chat/completions \
  -H "Authorization: Bearer $TOKENHUB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"hy4","messages":[{"role":"user","content":"hello"}]}'

Step 3: Get the model name right, with a minimal Python example

Circle this step in red. TokenHub model names are hy4 for the official release and hy4-preview for the previous generation; OpenRouter ids are tencent/hy4 and tencent/hy4-preview. They may be the same model underneath, but the strings and platforms differ: putting tencent/hy4 into a TokenHub model field, or treating hy4 as an OpenRouter id, is wrong. Every TokenHub call here fills hy4, and tencent/hy4 appears only as OpenRouter catalog data; the two are never mixed. hy4-preview is the previous generation from August 28, not the official release of November 4, 2026, and pricing, capabilities, and context specs are tracked per model.

This minimal runnable Python uses the official OpenAI SDK, reads the key from an environment variable, points the Base URL at Guangzhou, and fills hy4 with no hardcoded secret:

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["TOKENHUB_API_KEY"],
    base_url="https://tokenhub.tencentmaas.com/v1",
)

response = client.chat.completions.create(
    model="hy4",
    messages=[{"role": "user", "content": "Introduce yourself in one sentence"}],
)

print(response.choices[0].message.content)

For Singapore, swap the base_url and that site's key and nothing else, which is the whole point of "change three parameters": structure fixed, values swapped. Anthropic-style clients additionally change the path and header to /v1/messages and x-api-key.

Step 4: Feed it an image

For vision, the official Tencent Cloud image-understanding example turns content in messages from a string into an array with two element types: {"type":"image_url","image_url":{"url":"IMAGE_URL"}} for the image and {"type":"text","text":"Please describe this image..."} for the question. The url accepts a reachable image address or an inline data URL. For a local file, encode with base64.b64encode(...) and assemble data:image/jpeg;base64,... into that same url:

import base64
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["TOKENHUB_API_KEY"],
    base_url="https://tokenhub.tencentmaas.com/v1",
)

with open("photo.jpg", "rb") as f:
    encoded = base64.b64encode(f.read()).decode("utf-8")
data_url = "data:image/jpeg;base64," + encoded

response = client.chat.completions.create(
    model="hy4",
    messages=[
        {
            "role": "user",
            "content": [
                {"type": "image_url", "image_url": {"url": data_url}},
                {"type": "text", "text": "Describe what is in this image"},
            ],
        }
    ],
)

print(response.choices[0].message.content)

Keep the types straight, image_url for images and text for text, and match the MIME type to the file, jpeg or png. A live fetch of GET https://openrouter.ai/api/v1/models on November 4, 2026 records tencent/hy4 as text+image->text, context_length 1,048,576, max_completion_tokens 65,536, and supported parameters including reasoning, reasoning_effort, response_format, structured_outputs, tools, tool_choice, temperature, max_tokens, and stop. That is OpenRouter catalog data for tencent/hy4, useful for sizing, but do not copy the id back into TokenHub code. Model selection for vision belongs to the multi-model vision comparison (/en/posts/llm-vision-input-comparison-review).

Step 5: Wire it into your toolchain and verify

Compatible clients listed officially include CodeBuddy Code, Claude Code, Codex, OpenCode, OpenClaw, Cursor, Cline, Roo Code, Kilo Code, WorkBuddy, and Hermes Agent, and all wire up in three moves: create a key and enable the model (step one), point the client's endpoint at the Base URL, and replace the model name while confirming the protocol path, OpenAI style to /v1/chat/completions or /v1/responses, Anthropic style to /v1/messages. Send a plain text request first, then enable images and tool calls. Verification is more than a 200: confirm the model is hy4, the auth header matches the path, the reply reads from choices[0].message.content, the token counts in usage are plausible, and rerun the image request separately.

Enable thinking with thinking: {"type":"enabled"}; the Python SDK does not declare that field, so pass it through extra_body:

response = client.chat.completions.create(
    model="hy4",
    messages=[{"role": "user", "content": "Explain what this code does"}],
    extra_body={"thinking": {"type": "enabled"}},
)

message = response.choices[0].message
print(message.content)
reasoning = getattr(message, "reasoning_content", None)
if reasoning:
    print(reasoning)

The chain of thought lands in reasoning_content, which is not an SDK-declared field, so read it with getattr(message, "reasoning_content", None); direct attribute access can be blocked or raise in some SDK versions. The Anthropic path exposes thinking in a thinking content block instead, a different retrieval pattern.

Three traps: behavioral gaps, error codes, streaming failures

Trap one is treating TokenHub as a one-to-one wrapper around the standard API. Four differences matter: a unified gateway and unified auth where all protocols share one Base URL while the header still splits by family; a model field that takes the platform name hy4; model-dependent support for thinking, tool calls, multimodal input, caching, and some sampling parameters, where individual fields may be silently ignored or downgraded; and a usage field, especially cached-token breakdowns, that is not fully consistent across models, so trust the actual response.

Trap two is reading error codes at the wrong layer. Business codes are six digits whose first three map to the HTTP status: 400xxx parameters, 401xxx authentication, 429xxx rate limiting. 401002 means an invalid API key, most often from the regional split, a Guangzhou key against Singapore or the reverse; 402xxx means the model is not enabled or quota is short, pointing back to step one; 429xxx means rate limiting and may carry a Retry-After header, so back off exponentially instead of retrying harder. Debug in order: key and region paired, then model enabled and funded, then rate limiting.

Trap three is that streaming errors hide mid-response. The documentation states that when a fault occurs during transmission, the error is delivered as an SSE error frame wedged into the middle of the stream. Checking only the first chunk either crashes on a different frame structure or swallows the frame as content, yielding a truncated but seemingly successful output. Parse every frame as a potential error frame, extract the message and stop consuming when one appears, and close the connection and buffers cleanly. Streaming is common in toolchain clients, so manufacture one mid-stream fault during verification.

Pricing and promotions: three separate ledgers

Keep three ledgers apart. Ledger one is the Tencent Cloud list price in yuan per million tokens: 6 yuan input, 18 yuan output, and 0.3 yuan per cache hit, the same as preview and the basis for every discount. Ledger two is time-limited promotions on TokenHub only: through December 31, 2026 TokenHub settles at 50 percent of list price, Token Plan credit consumption at 25 percent runs through November 18, 2026, and WorkBuddy and CodeBuddy offer a certain amount of free usage from November 4 to November 15, 2026, with the exact quota on the official page and no unpublished number invented here. Read the free window strictly as that official date range. Billing math belongs to the LLM API pricing comparison (/en/posts/llm-api-pricing-comparison-review).

Ledger three is OpenRouter's dollar catalog price from a live fetch of GET https://openrouter.ai/api/v1/models on November 4, 2026: tencent/hy4 is $0.417 per million input tokens, $1.2505 output, and $0.021 cached read, while tencent/hy4-preview is $0.834, $2.501, and $0.042. OpenRouter's catalog price is not the official Tencent Cloud price, and the TokenHub 50 percent promotion applies only to Tencent Cloud's own list price, not to OpenRouter. Estimate TokenHub cost with ledger one times the active ledger-two discount; compare platforms with ledger three; mixing discounts, platforms, and currencies ends in an invoice that does not add up.

FAQ

Q1: Are three parameters really enough? A1: For most code on the OpenAI or Anthropic SDK, yes, and those three are the Base URL, the API key, and the model. But the protocol path must line up, OpenAI style on /v1/chat/completions or /v1/responses, Anthropic style on /v1/messages, and the auth header changes with the family. Thinking, images, and tool calls need extra fields, which are capability parameters rather than the three integration values.

Q2: Why do I get a 402 the moment I use my new key? A2: 402xxx means the model is not enabled or quota is insufficient, unrelated to auth or payload syntax. Go back to step one, confirm the Hy4 service is enabled and funded, then use GET /v1/models to check that the entry with id equal to hy4 is online. Do not rewrite the auth header; that is a 401 concern.

Q3: Should the model field be hy4 or tencent/hy4? A3: Use hy4. It is the TokenHub platform model name, while tencent/hy4 is an OpenRouter id, and the two naming schemes must not be mixed. hy4-preview is the previous generation from August 28, not the official release of November 4, 2026, so fill hy4 for the official model.

Q4: Can a key created in Guangzhou call the Singapore site? A4: No. Guangzhou at https://tokenhub.tencentmaas.com/v1 and Singapore at https://tokenhub-intl.tencentmaas.com/v1 are independent sites with API keys that are not shared, and using the wrong site produces 401002 for an invalid key. Decide the region when creating the key and keep the Base URL and key as a matched pair; do not assume a key minted in one place is accepted everywhere.

Q5: Can I download the weights and self-host the official Hy4? A5: Not at the time of writing. The weights of the official release have not been open-sourced; the vendor says it will publish the model weights and a system card in the near future, so there is no self-hosting path for the official release, and this article covers hosted API access only. The separate self-hosting SOP on the site is about the previous-generation hy4-preview weights on vLLM and SGLang, a different matter entirely.

Related reading

• Hy4 preview self-hosting SOP: running weights on vLLM and SGLang
• LLM API pricing comparison: how the token math works
• Tencent Hy4 preview open-source release hotspot (August 28)
• Tencent Hy4 official release hotspot
• Multi-model vision input comparison: choosing for image understanding