Tencent HY3 API Setup: Endpoint, Model ID, Pricing, and Python Example

A Tencent HY3 API key is useful only when the endpoint, model ID, request body, and response parser all match the route you are calling. A valid key can still fail if the application sends the request to a generic chat path without the correct model ID, uses a display name instead of the API model ID, or omits the Authorization: Bearer header that OurToken requires.

This guide focuses on the OurToken route for Tencent HY3. It shows how to get an API key, copy the exact base URL and full endpoint, send a cURL request, call the same endpoint from Python, calculate token cost using the live pricing table, and troubleshoot common 401, 404, and model_not_found errors. It is intentionally not a generic Hunyuan overview — the goal is to get one real request working through the current Tencent HY3 API page.

The current OurToken model page lists HY3 as an OpenAI Chat Completions-compatible route with model ID hy3, a 60% savings over the official price, and this configuration:

Base URL:     https://api.ourtoken.ai/v1
Full URL:     https://api.ourtoken.ai/v1/chat/completions
Model ID:     hy3
Auth header:  Authorization: Bearer YOUR_API_KEY

The request and response shape follows the OpenAI Chat Completions API reference. You send messages and receive a choices array with usage.prompt_tokens and usage.completion_tokens. This is the same OpenAI-compatible pattern used by other OurToken model routes, so existing integrations can usually switch to hy3 by changing only the model ID.

Verification status: This article was checked against the public OurToken HY3 model page and the OpenAI Chat Completions API reference on 2026-08-12. The examples are documentation-verified and require your own OurToken API key for live execution.

Tencent HY3 API Key Setup

The setup has three separate values. Keep them separate in your configuration so a future model change does not require editing every request call.

Exact values to copy

Create the credential from the OurToken API Keys page, then store it in a server-side environment variable. The API Keys page may redirect to login before you can manage credentials.

On macOS or Linux:

export OURTOKEN_API_KEY="paste-your-key-locally"

On Windows PowerShell:

$env:OURTOKEN_API_KEY = "paste-your-key-locally"

Do not paste the key into frontend JavaScript, a public repository, a shared notebook, a screenshot, or a bug report. Treat the key like a production password.

Do not use these model names

The exact model ID is hy3. If you see model_not_found, check this value first before changing code.

First Request with cURL and Python

cURL smoke test

Start with a minimal request to verify the endpoint, key, and model ID before adding complexity:

curl https://api.ourtoken.ai/v1/chat/completions \
  -H "Authorization: Bearer $OURTOKEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "hy3",
    "messages": [
      {"role": "user", "content": "Summarize the key features of a 295B MoE model in one sentence."}
    ],
    "max_tokens": 256
  }'

If the request succeeds, the response follows the standard OpenAI Chat Completions shape:

{
  "id": "chatcmpl-...",
  "object": "chat.completion",
  "model": "hy3",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "A 295B MoE model activates only 21B parameters per token, combining large-capacity knowledge with efficient inference for cost-sensitive chat and reasoning workloads."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 18,
    "completion_tokens": 32,
    "prompt_tokens_details": {
      "cached_tokens": 0
    }
  }
}

The usage.prompt_tokens_details.cached_tokens field is important for cost calculation. When the route serves a cached copy of your prompt prefix, this field reports how many input tokens were served from cache at the lower cached-input rate.

Python example with httpx

For Python, use httpx for a raw HTTP client that gives you full control over headers, timeouts, and response parsing. The OpenAI Python SDK also works because the endpoint is Chat Completions-compatible — set base_url to https://api.ourtoken.ai/v1 and pass api_key — but the example below uses httpx to make the request structure fully explicit:

import os
import httpx

API_KEY = os.environ["OURTOKEN_API_KEY"]
BASE_URL = "https://api.ourtoken.ai/v1"
ENDPOINT = f"{BASE_URL}/chat/completions"

response = httpx.post(
    ENDPOINT,
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json",
    },
    json={
        "model": "hy3",
        "messages": [
            {"role": "system", "content": "You are a concise technical assistant."},
            {"role": "user", "content": "What is Tencent Hunyuan HY3 in one sentence?"},
        ],
        "max_tokens": 256,
        "temperature": 0.7,
    },
    timeout=60.0,
)

response.raise_for_status()
data = response.json()

content = data["choices"][0]["message"]["content"]
usage = data["usage"]

print(content)
print(f"prompt_tokens: {usage['prompt_tokens']}")
print(f"completion_tokens: {usage['completion_tokens']}")
cached = usage.get("prompt_tokens_details", {}).get("cached_tokens", 0)
print(f"cached_tokens: {cached}")

Multi-turn conversation

For multi-turn chat, append the assistant response to the messages array and send the next user message. This is standard OpenAI Chat Completions behavior — no special handling is needed:

messages = [
    {"role": "system", "content": "You are a helpful coding assistant."},
    {"role": "user", "content": "What is a MoE model?"},
]

# First turn
response = httpx.post(
    ENDPOINT,
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json",
    },
    json={"model": "hy3", "messages": messages, "max_tokens": 256},
    timeout=60.0,
)
first = response.json()
assistant_msg = first["choices"][0]["message"]

# Append and continue
messages.append(assistant_msg)
messages.append({"role": "user", "content": "How does that affect inference cost?"})

# Second turn
response2 = httpx.post(
    ENDPOINT,
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json",
    },
    json={"model": "hy3", "messages": messages, "max_tokens": 256},
    timeout=60.0,
)
second = response2.json()
print(second["choices"][0]["message"]["content"])

When the conversation includes tool calls, preserve the full assistant message including tool_calls and any tool results. Do not reconstruct the assistant message manually — append the complete message object returned by the API.

Using the OpenAI Python SDK

Because the HY3 route is OpenAI Chat Completions-compatible, the OpenAI Python SDK works with a custom base_url and api_key:

from openai import OpenAI

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

response = client.chat.completions.create(
    model="hy3",
    messages=[
        {"role": "user", "content": "Explain sparse activation in one sentence."}
    ],
    max_tokens=128,
)

print(response.choices[0].message.content)
print(response.usage.prompt_tokens, response.usage.completion_tokens)

Pricing, Cached Tokens, and Cost Calculation

The OurToken model page lists explicit pricing for the HY3 route alongside official reference prices. The page title states "60% of official price" — this section reproduces those numbers and shows how to calculate cost from a real usage object.

Pricing table

All prices are per 1,000,000 tokens. The OurToken page shows the official reference prices with a strikethrough to highlight the discount. Always confirm current pricing on the Tencent HY3 API page before production rollout.

Cost formula

The usage.prompt_tokens field includes both uncached and cached input tokens. To avoid double-counting, calculate uncached input as prompt_tokens - cached_tokens, then apply the correct rate to each category:

uncached_input = prompt_tokens - prompt_tokens_details.cached_tokens
input_cost  = uncached_input / 1,000,000 × $0.0880
cached_cost = cached_tokens / 1,000,000 × $0.0220
output_cost = completion_tokens / 1,000,000 × $0.3530
total_cost  = input_cost + cached_cost + output_cost

Python cost helper

RATES = {
    "input": 0.0880,
    "output": 0.3530,
    "cached_input": 0.0220,
    "cache_write": 0.0,
}


def estimate_cost_usd(usage: dict) -> float:
    prompt_tokens = usage.get("prompt_tokens", 0)
    cached_tokens = (
        usage.get("prompt_tokens_details", {}).get("cached_tokens", 0)
    )
    uncached_input = max(prompt_tokens - cached_tokens, 0)
    completion_tokens = usage.get("completion_tokens", 0)

    return round(
        uncached_input / 1_000_000 * RATES["input"]
        + cached_tokens / 1_000_000 * RATES["cached_input"]
        + completion_tokens / 1_000_000 * RATES["output"],
        8,
    )

Worked example

A request with 100,000 input tokens (of which 40,000 are cached) and 8,000 output tokens costs:

uncached_input = 100,000 - 40,000 = 60,000
input_cost  = 60,000 / 1,000,000 × $0.0880 = $0.005280
cached_cost = 40,000 / 1,000,000 × $0.0220 = $0.000880
output_cost = 8,000 / 1,000,000 × $0.3530  = $0.002824
total_cost  = $0.008984

For comparison, the same workload at the official reference price would cost:

input_cost  = 60,000 / 1,000,000 × $0.147  = $0.008820
cached_cost = 40,000 / 1,000,000 × $0.0367 = $0.001468
output_cost = 8,000 / 1,000,000 × $0.588   = $0.004704
total_cost  = $0.014992

The OurToken route saves approximately 40% on this workload. The exact savings depend on your cache hit ratio. Cached tokens are billed at roughly 25% of the uncached input rate, so prompts with high prefix repetition benefit most. If your application sends the same system prompt, few-shot examples, or long context prefix on every request, the cache read rate applies to the repeated portion and the uncached input rate applies only to the new user message. Over thousands of requests, this difference compounds — a workload with 80% cache hit ratio on input tokens can cut total input cost by more than half compared to the uncached rate. If your workload sends a large fixed system prompt on every request, review the OpenAI-compatible prompt caching guide to understand how caching reduces repeated input costs across model routes.

When to use HY3

Public Tencent Hy3 model card materials describe a 295B-parameter Mixture-of-Experts architecture with 21B active parameters per token. This makes HY3 suitable for cost-sensitive chat, assistant, and reasoning workloads where you want large-model capacity without paying full output-token rates. Teams evaluating multiple Chinese-origin models can compare HY3 alongside DeepSeek V4 Pro and GLM 5.2 on the same OpenAI-compatible endpoint, switching only the model ID to benchmark quality, latency, and cost. The OurToken model directory lists all available routes for side-by-side comparison.

Troubleshooting and Production Checklist

Common errors

Do not retry malformed requests unchanged. Retry helps with transient failures such as 429, 529, some 5xx errors, and network timeouts. It does not repair a bad endpoint, bad model ID, or missing Authorization header.

Production checklist

[ ] API key is stored server-side only
[ ] Raw cURL request works before SDK integration
[ ] Base URL is https://api.ourtoken.ai/v1
[ ] Full endpoint is /v1/chat/completions
[ ] Model ID is hy3
[ ] Auth header is Authorization: Bearer YOUR_API_KEY
[ ] Parser reads choices[0].message.content
[ ] Usage and cost are logged per feature
[ ] 400/401/404 are not retried blindly
[ ] 429/529/5xx retries are bounded with jitter
[ ] Prompts and Authorization headers are redacted in logs

A strong production rollout starts with one small use case. For example, a customer-support assistant can send a concise policy document, a user question, and ask HY3 for a structured response. With a 295B MoE architecture, the route can handle nuanced reasoning, but that also makes token logging mandatory — large prompts can be useful, but invisible large prompts are quiet budget leaks.

For teams using multiple routes, keep model selection on the server. A client should not be allowed to send arbitrary model IDs. Start with one HY3 route, measure cost per successful task, then decide whether simpler work should move to a lower-cost model. If your traffic includes both simple and complex queries, consider an LLM model routing strategy that sends each query to the most cost-effective model.

Conclusion and FAQ

A working Tencent HY3 setup on OurToken is compact: create an API key, call https://api.ourtoken.ai/v1/chat/completions, send Authorization: Bearer YOUR_API_KEY, set model to hy3, and parse the standard OpenAI Chat Completions choices array. Start with cURL, repeat the same request in Python, then add streaming, tools, or multi-turn conversations after the basic request succeeds.

When you are ready to test live traffic, create or manage a credential through OurToken API Keys, confirm the current endpoint and pricing on the Tencent HY3 API page, and use OurToken Docs for broader integration guides.

FAQ

How do I get a Tencent HY3 API key?

Create an OurToken account and generate a key from the OurToken API Keys page. Use that key with Authorization: Bearer when calling api.ourtoken.ai.

What is the Tencent HY3 API endpoint?

The current full endpoint is https://api.ourtoken.ai/v1/chat/completions. The base URL is https://api.ourtoken.ai/v1.

What is the HY3 model ID?

Use hy3. Do not use the display name, a provider prefix, or a slug-style variant.

Is there a free Tencent HY3 API?

Do not assume a permanent free tier. Check the current OurToken dashboard or promotions for any account credits, then budget using the live model page pricing.

Can I use the OpenAI Python SDK?

Yes. The HY3 route is OpenAI Chat Completions-compatible. Set base_url to https://api.ourtoken.ai/v1 and pass your OurToken API key.

How much does the Tencent HY3 API cost?

The current OurToken pricing is $0.0880 per 1M input tokens, $0.3530 per 1M output tokens, and $0.0220 per 1M cached input tokens. This is approximately 60% of the official reference price. Always confirm on the live model page.

Why does my request return model_not_found?

The usual cause is a model string mismatch. Confirm the request body uses "model": "hy3" and that the route is available to your account.