Hy3 API Guide: Reasoning, Tool Calls, and Long Context

Hy3 is a text-only MoE model for coding, reasoning, long-context work, and agents. For a first integration, use a hosted OpenAI-compatible endpoint, send a normal Chat Completions request, and evaluate the one workflow you would actually automate. Do not standardize on it until it follows your tool schema and retains the constraints that matter in your long inputs.

Provider details below were checked on July 14, 2026. DeepInfra documents the model as tencent/Hy3 at its OpenAI-compatible Chat Completions endpoint. SiliconFlow also lists Hy3 under the same model ID. Provider prices, limits, and aliases can change, so confirm the live provider page before you ship.

Start with a hosted Hy3 API call

DeepInfra publishes this minimal request for its hosted Hy3 endpoint. Replace the token with your own provider token; do not put it in browser code or a client app.

curl "https://api.deepinfra.com/v1/openai/chat/completions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DEEPINFRA_TOKEN" \
  -d '{
    "model": "tencent/Hy3",
    "messages": [
      {"role": "user", "content": "Return three API acceptance checks."}
    ]
  }'

The response uses the standard Chat Completions shape. Parse the answer and billing fields like this:

{
  "id": "chatcmpl-...",
  "object": "chat.completion",
  "model": "tencent/Hy3",
  "choices": [{
    "message": {"role": "assistant", "content": "..."},
    "finish_reason": "stop"
  }],
  "usage": {
    "prompt_tokens": 0,
    "completion_tokens": 0,
    "total_tokens": 0
  }
}

Read choices[0].message.content for the answer and usage for token accounting. Add "stream": true only after a non-streaming request works; DeepInfra documents streaming as server-sent events that end with [DONE].

The provider choices in the table are deliberately narrow. They are verified public access routes, not a price ranking.

Tencent's July 6, 2026 release announcement introduced Hy3 as an open-weight Mixture-of-Experts model. Its official pricing announcement and model card make it a candidate for a hosted evaluation, but an API page is not evidence that it fits a production workload.

What Hy3 is, and what it is not

Hy3 is a 295B-parameter MoE model with 21B active parameters per token. The official Hy3 model card lists 192 experts with top-8 routing, an 80-layer backbone, one MTP layer, a 256K-token context window, and an Apache 2.0 license.

Those numbers describe a text model designed for reasoning, coding, long-running conversations, and tool-using agents. They do not make Hy3 an image or OCR model. A workflow whose key input is a scanned invoice, screenshot, product photo, or chart needs a vision or OCR model before it needs Hy3. Keeping that boundary clear prevents a common architecture mistake: asking a capable text model to recover information it never received.

Tencent positions Hy3 for coding, office work, financial modeling, frontend work, and game development. Treat those as candidate workloads, not a universal ranking.

Read the benchmark claims with their limits

Tencent's release announcement reports a blind evaluation with 270 experts performing work tasks in which Hy3 scored 2.67 out of 4 and GLM-5.1 scored 2.51 out of 4. The same source says Hy3's SWE-Bench Verified accuracy varied by less than four percentage points across CodeBuddy, Cline, and KiloCode scaffolds. These are Tencent-reported results, not an independent guarantee that Hy3 will beat a named rival in your environment.

Artificial Analysis is another reference point for model-level measurements. Read benchmark numbers as model-selection inputs, not as a substitute for application-level acceptance criteria.

Choose the reasoning mode by failure cost

Hy3 exposes no_think, low, and high reasoning effort in its official serving examples. The choice should follow the cost of an incorrect answer, not the prestige of using a reasoning model.

Keep no-think for bounded work

no_think is the default direct-response mode. It is the right baseline when the source is already structured, the answer has a known shape, and a slower response would not add useful reasoning. For example, a support workflow that chooses one documented status and calls one function should first be tested in this mode. Add a strict JSON schema and reject responses that have extra fields instead of hoping a longer chain of reasoning will repair a vague contract.

Use low or high reasoning when an error changes the next action

Move to low when the model must reconcile several rules or make a bounded change to code. Reserve high for work where a weak intermediate decision causes a costly retry: diagnosing a failure across files, choosing an order of operations, or checking calculations before a tool call.

The tradeoff is measurable. Compare the whole completed task: request latency, output-token count, tool-call retries, test failures, and the minutes a reviewer spends repairing the answer. A mode that looks more thoughtful but doubles tokens without reducing review time is not the better production setting.

Run a four-part API trial before you adopt Hy3

This trial creates evidence for your system rather than a generic model verdict. Use real but non-sensitive tasks. Freeze prompts, schemas, and pass criteria before running the models so you do not move the goalposts after reading an answer.

Prove the request path with a minimal self-hosted call

The following example follows Hy3's official self-hosted, OpenAI-compatible serving pattern. It uses a local vLLM-compatible endpoint and the model name configured by that server. Hosted model IDs are provider-specific; use the provider table above for the verified hosted IDs.

from openai import OpenAI

client = OpenAI(
    base_url="http://127.0.0.1:8000/v1",
    api_key="EMPTY",
)

response = client.chat.completions.create(
    model="hy3",
    messages=[
        {"role": "user", "content": "List the acceptance checks for a JSON tool call."}
    ],
    temperature=0.9,
    top_p=1.0,
    extra_body={
        "chat_template_kwargs": {"reasoning_effort": "low"}
    },
)

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

Get this trivial call working before evaluating a complicated agent. It separates an authentication, endpoint, template, or model-name problem from a model-quality problem. Log the provider, model revision if available, reasoning mode, timestamp, input tokens, output tokens, and elapsed time for every trial.

Test structured output and tool calls with your real schema

Tool calling should not be graded as "the model chose a plausible action." Send an explicit schema and validate the returned arguments in your application. This is an OpenAI-style request fragment; confirm the exact tool parameter support with the provider before relying on it.

{
  "model": "tencent/Hy3",
  "messages": [
    {"role": "user", "content": "Check the status of incident INC-1042."}
  ],
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "get_incident",
        "description": "Look up one incident by its identifier.",
        "parameters": {
          "type": "object",
          "properties": {"incident_id": {"type": "string"}},
          "required": ["incident_id"],
          "additionalProperties": false
        }
      }
    }
  ]
}

For this request, a correct tool decision means a get_incident call whose incident_id is exactly INC-1042. Your code should reject a missing field, a malformed JSON argument string, or an unexpected tool before it touches the downstream system. Inspect five things:

1. The selected tool is allowed for the task.

2. Every required argument is present and typed correctly.

3. IDs, dates, and amounts come from the supplied context instead of being invented.

4. The model asks for a missing required value rather than guessing it.

5. A tool error leads to a bounded repair or escalation path, not a loop.

Run enough examples to include valid inputs, ambiguous requests, missing fields, and one deliberately failing tool response. Reliable JSON on the happy path is useful; reliable behavior when the system rejects an argument is what keeps an agent from creating work for an operator.

Test long context for constraint retention, not headline length

Hy3's 256K context is valuable only when the relevant facts survive in your prompt format. Build a test from a representative repository, policy bundle, or customer-history thread. Put several specific constraints in different locations, add realistic distractors, and ask for an answer that must cite or transform those constraints.

Score exact retrieval, adherence to every named constraint, unsupported claims, and total request cost. Then repeat with your production retrieval layer enabled. This exposes whether a failure belongs to the model, chunking, retrieval ranking, or the prompt assembly code. Passing one large pasted document is not enough evidence to turn off guardrails.

Test the workload that would justify a migration

Pick one task where a better model outcome has a clear business value: repairing a failing test across several files, extracting obligations from a long policy, or completing a multi-step internal operation with tools. Compare the current production path and Hy3 under the same timeout and review rule.

Record completed-task rate, p50 and p95 latency, input and output tokens, number of tool retries, and reviewer correction time. This is also where mixed community feedback becomes useful. Do not decide from a claim that Hy3 is exceptional or disappointing in the abstract. Decide from the task you would actually pay to automate.

Hosted API or self-hosting?

Use a hosted API first when you are evaluating the model, traffic is still uncertain, or your team does not already operate the necessary GPU capacity. It shortens the path to the tests above and keeps provider availability separate from your application logic.

Self-host only when you have a concrete control, privacy, volume, or latency reason and the infrastructure to support it. The official model card recommends eight H20-3e GPUs or other large-memory GPUs for serving Hy3, with vLLM or SGLang recipes. That is Tencent's production-serving recommendation, not a claim that a consumer laptop provides an equivalent deployment. Measure the cost of GPU reservations, upgrades, monitoring, batching, and on-call ownership against the hosted bill before treating open weights as free infrastructure.

Pricing and availability can change faster than the weights

Tencent listed Hy3 API pricing at 1 RMB per million input tokens, 4 RMB per million output tokens, and 0.25 RMB per million cached input tokens on July 6. Use that as a dated reference point, then confirm the actual endpoint price before you ship. A provider's free tier, introductory credit, or temporary free model alias is availability for an experiment, not a permanent unit-cost promise.

For a simple cost check, 100 daily requests containing 20K input tokens and 1K output tokens use 2M input and 0.1M output tokens. At Tencent's published reference price, that is 2.4 RMB per day, or about 72 RMB for 30 days. If all 2M input tokens qualify for cached pricing, the same arithmetic is 0.9 RMB per day. This is a token-only estimate: it excludes provider markup, free-tier limits, retries, and any context your application adds.

When budgeting a trial, include retrieved context, system prompt, tool definitions, retries, and the output produced by the chosen reasoning setting. Do not choose Hy3 when the key input is visual, a lightweight local deployment is a hard requirement, or the application cannot validate tool arguments and downstream side effects.

For a text-heavy agent that needs a large context window, configurable reasoning, and open weights, Hy3 is a reasonable model to evaluate. Keep it only when it reduces correction time at an acceptable total cost.

FAQ

Is Hy3 multimodal?

No. Hy3 is a text-input, text-output model. Use a vision or OCR model when the task starts with images, scans, or screenshots.

What is the Hy3 context window?

Tencent's model card lists a 256K-token context window. A long context limit does not guarantee relevant facts will be retrieved or followed, so validate it with representative source material.

Which Hy3 reasoning mode should I start with?

Start with no_think for bounded, latency-sensitive work. Move to low or high only after the task's failure cost and measured improvement justify the extra tokens and time.

Can I self-host Hy3?

Yes. Tencent provides vLLM and SGLang deployment guidance and recommends eight large-memory GPUs for serving. Self-hosting should follow a capacity and operations decision, not the open-weight license alone.

Is a free Hy3 API a permanent pricing plan?

No. Free access is provider-specific and can end or change limits. Confirm the current provider terms and the paid rate before committing a production workflow.