# Hy4 API on TokenRa

Model ID: `hy4`
Get an API key: https://tokenra.io/register?utm_source=llms-agent&utm_medium=model-llms
Updated: 2026-11-04

> Hy4 is the final release of Tencent Hunyuan's open-weight flagship, a 770B-class sparse MoE with 49B active parameters and a 1M-token context. It takes text input and returns text, with reasoning in `reasoning_content` where the model produces it.

- Provider: Tencent Hunyuan
- Type: Text model
- Released: 2026-11-04 (final release; Hy4 Preview shipped 2026-08-28)
- API formats: Chat Completions, Responses, Messages
- Input: Text
- Output: Text with reasoning
- Context: 1M tokens

## Pricing

Rates in the TokenRa console when this file was last updated, in US dollars for the default group. The live price list is authoritative: https://tokenra.io/pricing (JSON: https://tokenra.io/api/pricing).

- `hy4`: $0.667 per 1M input tokens, $2.001 per 1M output tokens, $0.034 per 1M cached input tokens

## Capabilities & endpoints

Chat generation through three API formats. Each is OpenAI- or Anthropic-compatible, so an existing SDK works by changing the base URL and model ID.

- `POST https://tokenra.io/v1/chat/completions`: OpenAI SDK with `base_url="https://tokenra.io/v1"`. Auth: `Authorization: Bearer`. Recommended.
- `POST https://tokenra.io/v1/responses`: OpenAI Responses API, same SDK and key. Text answer in `output_text`.
- `POST https://tokenra.io/v1/messages`: Anthropic SDK or Claude Code with base URL `https://tokenra.io`. Auth: `x-api-key` (or Bearer) plus `anthropic-version`.

## Example

Set `TOKENRA_API_KEY` to your API key first.

```bash
curl https://tokenra.io/v1/chat/completions \
  -H "Authorization: Bearer $TOKENRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "hy4",
    "messages": [
      {"role": "system", "content": "You are a concise technical assistant."},
      {"role": "user", "content": "Explain in two sentences what an API gateway does."}
    ]
  }'
```

Python:

```python
from openai import OpenAI

client = OpenAI(base_url="https://tokenra.io/v1", api_key="YOUR_API_KEY")

response = client.chat.completions.create(
    model="hy4",
    messages=[{"role": "user", "content": "Explain in two sentences what an API gateway does."}],
)
print(response.choices[0].message.content)
```

## Request parameters

Fields for `POST /v1/chat/completions`.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `model` | string | Yes | The model ID to call: `hy4`. |
| `messages` | array | Yes | Conversation messages in order (system, user, assistant, tool). For multi-turn chat, send the earlier turns back. |
| `stream` | boolean | No | Return the answer as server-sent events. Default `false`. |
| `stream_options` | object | No | With `{"include_usage": true}`, the last chunk carries `usage` and an empty `choices` array. |
| `max_tokens` | integer | No | Upper limit for generated tokens. |
| `max_completion_tokens` | integer | No | Upper limit for all generated tokens, reasoning included. |
| `temperature` | number | No | Sampling temperature. |
| `top_p` | number | No | Nucleus sampling threshold. Usually tune either this or temperature. |
| `presence_penalty` | number | No | Penalises tokens that already appeared, nudging the model toward new topics. |
| `frequency_penalty` | number | No | Penalises frequent tokens to reduce repetition. |
| `response_format` | object | No | `{"type": "json_object"}` returns a JSON object; `{"type": "json_schema", ...}` returns JSON matching your schema. |
| `tools` | array | No | Function tools the model may call (`type: "function"`). |
| `tool_choice` | string / object | No | `auto`, `none`, `required`, or a specific function. |
| `reasoning_effort` | string | No | Reasoning depth such as `low`, `medium` or `high`. How much it changes the reasoning varies by model. |
| `user` | string | No | Your own end-user identifier for auditing or abuse handling. Not part of the conversation. |

### Other formats

| Format | Required fields | Answer location |
| --- | --- | --- |
| OpenAI Responses | `model`, `input` | `output_text` |
| Anthropic Messages | `model`, `max_tokens`, `messages` | `content[]` blocks of type `text` |

## Response format

**Example response**

```json
{
  "id": "chatcmpl-1793768500",
  "object": "chat.completion",
  "created": 1793768500,
  "model": "hy4",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "An API gateway is the single entry point that receives client requests and routes them to the right backend service. It also handles shared concerns such as authentication, rate limiting and logging.",
        "reasoning_content": "The user wants two sentences about API gateways..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 26,
    "completion_tokens": 58,
    "total_tokens": 84,
    "prompt_tokens_details": {"cached_tokens": 0},
    "completion_tokens_details": {"reasoning_tokens": 21}
  }
}
```

| Field | Type | Description |
| --- | --- | --- |
| `id` | string | Completion ID. Include it when you contact support. |
| `object` | string | `chat.completion`, or `chat.completion.chunk` when streaming. |
| `created` | integer | Unix timestamp in seconds. |
| `model` | string | The model that produced the answer. |
| `choices[].message.content` | string | The answer text. |
| `choices[].message.reasoning_content` | string | The model's reasoning, returned separately from the answer when present. |
| `choices[].message.tool_calls` | array | Tool calls requested by the model, when `tools` were sent. |
| `choices[].finish_reason` | string | `stop`, `length` or `tool_calls`. |
| `usage` | object | `prompt_tokens`, `completion_tokens`, `total_tokens`, plus `prompt_tokens_details.cached_tokens` and `completion_tokens_details.reasoning_tokens`. |

With `stream: true` the answer arrives as `data:` lines of `chat.completion.chunk` objects and ends with `data: [DONE]`.

## Errors & limits

### Common errors

| HTTP | error.code | Meaning | What to do |
| --- | --- | --- | --- |
| `401` | - | Missing, wrong or deleted API key. The message is `Invalid token`. | Check the `Authorization: Bearer` header and the key in the console. |
| `400` | - | The body is not valid JSON. | Fix the JSON and send `Content-Type: application/json`. |
| `500` | `invalid_request` | A required field is missing, for example `messages`. | Add the field named in the message. Retrying will not help. |
| `403` | `insufficient_user_quota` | Your balance or plan quota is used up. | Top up in the console, then retry. |
| `503` | `model_not_found` | Unknown model ID, or no channel serves it for your group. | Check the ID in the model list or with `GET /v1/models`. |
| `429` | - | Too many requests. | Back off exponentially and retry. |
| `5xx` | - | The upstream provider failed or timed out. | Retry a few times; keep the request id if it persists. |

### Limits and notes

- **Hy4 is not Hy4 Preview.** The final release continued training and expanded post-training. Prompts tuned on `hy4-preview` can behave differently here; re-run your own evaluations rather than assuming parity.
- Pin the model ID in a config value. A preview or promotional identifier can be renamed or withdrawn.
- Reasoning, where the model produces it, comes back in `reasoning_content` separately from the answer in `content`. Keep it out of what you show users unless you want to display it.
- Leave a generous `max_tokens` and timeout: reasoning tokens count toward the limit, and a low cap can end the request with `finish_reason: "length"` and an empty answer.
- The 1M-token context covers large repositories and long documents, but context growth is billed — trim stale turns and summarise history as conversations lengthen.
- Rates here reflect the console at the time of writing. Pricing is set per channel and account, so confirm the current numbers before committing to a budget.

## More

- [Hy4 API model guide](https://tokenra.io/models/hy4-api.html): release timeline, Preview comparison and integration notes
- [HY4 Preview guide](https://tokenra.io/docs/hy4-preview/llms.txt): the August 2026 early checkpoint this release supersedes
- [API basics](https://tokenra.io/docs/common.html): base URL, authentication, errors, retries
- [Quickstart](https://tokenra.io/docs/quickstart.html): create a key and send a first request
- [All models](https://tokenra.io/docs/models.html): every model ID
- [Site index for agents](https://tokenra.io/llms.txt)

---

Canonical version of this document: https://tokenra.io/docs/hy4-api/llms.txt