Skip to contentOceanToken

6 min read

Call Tencent Hy3 With the OpenAI SDK

Call Tencent Hy3 with the OpenAI SDK outside China: base URL, model id, streaming, tool calls, reasoning_effort values, Hy3 vs Hy3 preview, and token billing.

By OceanToken Team

Call Tencent Hy3 With the OpenAI SDK

Editor's note: Hy3 is Tencent's open-weight reasoning model, a 295B-total, 21B-active MoE under Apache 2.0, and for developers outside China the practical question is often access rather than the model itself. An OpenAI-compatible endpoint removes that, with one catch most migration notes skip: the reasoning switch is spelled differently from Tencent's own docs, and the default is the expensive end.

Short answer: To call Tencent Hy3 with the OpenAI SDK, point the client at https://api.oceantoken.ai/v1, use your key and model tencent/hy3. Streaming, tools and JSON output use the familiar Chat Completions fields. Set reasoning_effort (none, low, high) yourself, because it defaults to high. Billing is per million tokens; see /hunyuan-api.

Diagram: Moving an OpenAI client to Hy3

01 · What Hy3 is, and which id to use

Tencent's model card  describes Hy3 as a Mixture-of-Experts model with 295B total and 21B active parameters, released under Apache 2.0 and built on Hy3 preview with more post-training and reinforcement learning. Two Hy3 ids are in the catalog, and the Hunyuan API page lists both alongside the Hy4 preview and the translation models.

tencent/hy3 tencent/hy3-preview
Context window 262,144 tokens 262,144 tokens
Max output 128,000 tokens 235,929 tokens
reasoning_effort none, low, high (default high) none, low, high (default high)
Tools Yes Yes
response_format json_object, json_schema Not in the parameter table
Image input Not listed Not listed

For new code, use tencent/hy3. It is the later model, and it is the one with structured output in its parameter list. The preview only wins when a single response must run past 128,000 tokens, which is rare outside long document generation.

02 · How to call Tencent Hy3 with the OpenAI SDK

Nothing about the client changes except two values. The FAQ  says the official OpenAI SDKs work once the base URL is https://api.oceantoken.ai/v1 and the key is yours. You don't need a Tencent Cloud account; you add credits by card and call the endpoint.

import os
from openai import OpenAI

client = OpenAI(base_url="https://api.oceantoken.ai/v1",
                api_key=os.environ["OCEANTOKEN_API_KEY"])

resp = client.chat.completions.create(
    model="tencent/hy3",
    messages=[{"role": "user", "content": "Summarize the CAP theorem in three sentences."}],
    reasoning_effort="low",
    max_tokens=2000,
)
msg = resp.choices[0].message
print(msg.content)
print(getattr(msg, "reasoning_content", None))   # reasoning, when returned
print(resp.usage)

The Node SDK is the same shape:

import OpenAI from "openai";
const client = new OpenAI({ baseURL: "https://api.oceantoken.ai/v1", apiKey: process.env.OCEANTOKEN_API_KEY });

const stream = await client.chat.completions.create({
  model: "tencent/hy3",
  messages: [{ role: "user", content: "Write a haiku about latency." }],
  reasoning_effort: "none",
  stream: true,
  stream_options: { include_usage: true },
});
for await (const chunk of stream) process.stdout.write(chunk.choices[0]?.delta?.content ?? "");

With include_usage, the last stream event carries token counts, which is what you want for cost tracking.

03 · The reasoning switch: where Tencent's docs and the API differ

This is the part to read twice. Tencent's model card  sets reasoning through chat_template_kwargs with the values no_think, low and high, and names no_think as the default. Tencent's thinking-mode documentation  adds a separate thinking object. Neither spelling appears in the OceanToken reference for Hy3 , which lists a top-level reasoning_effort of none, low or high, defaults to high, and says anything outside its parameter table is left out before the request reaches the model.

Diagram: Which reasoning_effort for this task?

Two practical consequences follow. Code ported from Tencent examples that sends chat_template_kwargs or thinking will not switch reasoning off; use reasoning_effort="none" instead. And a request that omits the field runs at high, so a quick classification call can produce thousands of reasoning tokens. The model page says thinking tokens are billed at the output price, and max_tokens caps output with reasoning included, so a low cap on a high request can end with little or no visible answer.

Task reasoning_effort Why
Classification, extraction, rewriting none No benefit from long reasoning
Everyday Q&A, short code edits low Some planning, modest token use
Math, multi-step coding, agent planning high The model card recommends high for these

04 · Tools and JSON output

Tool calling uses the standard tools array, with tool_choice and parallel_tool_calls available. One extra rule comes from Tencent's thinking-mode doc: when tools are used in thinking mode, the earlier reasoning_content should go back with each turn. The OceanToken response carries reasoning_content on the assistant message, but its reference does not say whether that field is accepted on input, so test a two-turn tool loop with reasoning on before relying on it. If the loop misbehaves, run tool-heavy turns at none or low.

For JSON, Hy3 accepts response_format with json_object or json_schema. Generic differences between models behind one OpenAI-compatible client, such as which sampling fields each accepts, are covered in our model-switching gotchas guide; this article only covers what is specific to Hy3.

05 · Billing per million tokens

Hy3 is billed per 1M tokens, split into input and output, and the model page also lists a cached-input rate. The response tells you which bucket each token fell into: usage.prompt_tokens, usage.completion_tokens, prompt_tokens_details.cached_tokens for cache reads, and completion_tokens_details.reasoning_tokens, which is counted inside output. So the cost of one call is uncached input, cached input and output (reasoning included), each times its rate.

The model page also says a request that never ran is not charged, while a stream that breaks off is billed for tokens already processed. For the rates themselves, see /hunyuan-api. If several services share one account, our guide to prepaid balance guardrails shows how to cap spend per key.

How to test this on your workload

We have not benchmarked Hy3 for this article. Before switching traffic, run a short check:

  1. Send 20 of your real prompts at none, low and high; record answer quality, reasoning_tokens and latency for each.
  2. Send one request with chat_template_kwargs and no reasoning_effort, and confirm from reasoning_tokens that it ran at the default.
  3. Run a two-turn tool call with reasoning on, once returning reasoning_content and once without, and compare the second turn.
  4. Request a json_schema response on tencent/hy3 and validate it against your schema.

Our take: Hy3 is worth a slot in any OpenAI-compatible stack that needs a strong open-weight reasoner, and the migration is a base URL, a key and one explicit reasoning_effort. The mistake to avoid is leaving reasoning at its default. Set reasoning_effort on every request, start with low, and raise it only for tasks where you can see the difference.

Running it on OceanToken

OceanToken serves Hy3 as tencent/hy3 on https://api.oceantoken.ai/v1, on both /v1/chat/completions and /v1/responses. The Hunyuan API page puts it plainly: "change the base URL and the key, and keep your code." The same key then reaches every other model in the catalog, so comparing Hy3 with another reasoning model is a change of model id. Billing comes from a prepaid balance with no subscription, and each key can carry its own spending limit. See the current rate on /hunyuan-api.

FAQ

What is the Hy3 model id? tencent/hy3; the earlier release is tencent/hy3-preview.

How do I turn Hy3 reasoning off? Send reasoning_effort: "none". Tencent's no_think, chat_template_kwargs and thinking spellings are not in the parameter list.

What is the Hy3 context window? 262,144 tokens, with up to 128,000 output tokens.

Are reasoning tokens billed? Yes, at the output price, and they count toward max_tokens.

Does Hy3 support structured output? Yes, response_format with json_object or json_schema on tencent/hy3.

Do I need a Tencent Cloud account? No. You create an account, add credits by card, and call the endpoint with your key.

Sources

  1. OceanToken docs: tencent/hy3 reference  (checked 2026-11-13)
  2. OceanToken docs: tencent/hy3-preview reference  (checked 2026-11-13)
  3. oceantoken.ai: Hy3 model page (checked 2026-11-13)
  4. oceantoken.ai: Hunyuan API (checked 2026-11-13)
  5. Tencent: Hy3 model card  (checked 2026-11-13)
  6. Tencent Cloud: deep thinking mode documentation  (checked 2026-11-13)
  7. OceanToken docs: FAQ  (checked 2026-11-13)

Get your OceanToken API key

  1. Create an OceanToken account and an API key.
  2. Copy the snippet below, paste your key, and run it.
  3. Check the current rate on /hunyuan-api.
curl https://api.oceantoken.ai/v1/chat/completions \
  -H "Authorization: Bearer $OCEANTOKEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "tencent/hy3", "reasoning_effort": "low", "messages": [{"role": "user", "content": "Summarize the CAP theorem in three sentences."}]}'

Get API Key 

  • Hunyuan
  • LLM API
  • Tutorial
  1. 7 min read

    A Unified API for Chat, Image and Video

    Building on a unified API for chat, image and video: sync vs async calls, billing units, retries, timeouts and storage, with three calls and a launch checklist.

    • AI video
    • LLM API
    • Tutorial
  2. 7 min read

    Kimi K3 API International Access Guide

    Use the Kimi K3 API internationally: sign up with email, pay by card, create one key and call moonshotai/kimi-k3 with an OpenAI SDK. Steps, code and checks.

    • Kimi
    • LLM API
    • Tutorial
  3. 7 min read

    Call the Hailuo 3 Max API With an API Key

    How to call the Hailuo 3 Max API with an API key: the request, polling and download, the Max-only limits, what sets the cost of one video, and Max vs Hailuo 3.

    • Hailuo
    • Tutorial