# HY4 Preview API（TokenRa）

模型 ID：`hy4-preview`
获取 API Key：https://tokenra.io/sign-up?utm_source=llms-agent&utm_medium=model-llms
更新日期：2026-10-30

> HY4 Preview 是腾讯混元新一代模型的预览版，作答前会进行较长的推理，推理过程在 `reasoning_content` 中返回，只支持文本输入。

- 厂商：腾讯混元
- 类型：文本模型
- 接口格式：Chat Completions, Responses, Messages
- 输入：文本
- 输出：文本（含推理过程）

## 价格

以下为本文件最后更新时 TokenRa 控制台的价格，单位美元，默认分组。请以实时价格为准：https://tokenra.io/pricing（JSON：https://tokenra.io/api/pricing）。

- `hy4-preview`：输入 $1.02 / 100 万 token，输出 $3.04 / 100 万 token，缓存命中输入 $0.05 / 100 万 token

## 能力与接口

对话生成，支持三种接口格式，均已于 2026-10-23 在 tokenra.io 实测调用成功。

- `POST https://tokenra.io/v1/chat/completions`：OpenAI SDK，`base_url` 设为 `https://tokenra.io/v1`；鉴权用 `Authorization: Bearer`。推荐使用。
- `POST https://tokenra.io/v1/responses`：OpenAI Responses 接口，SDK 和 Key 与上面相同，回答在 `output_text` 中。
- `POST https://tokenra.io/v1/messages`：Anthropic SDK 或 Claude Code，Base URL 设为 `https://tokenra.io`；鉴权用 `x-api-key`（也可用 Bearer），并带上 `anthropic-version`。

## 调用示例

先把环境变量 `TOKENRA_API_KEY` 设为你的 API Key。文档页提供同一示例的 Python、JavaScript 和 Java 版本。

```bash
curl https://tokenra.io/v1/chat/completions \
  -H "Authorization: Bearer $TOKENRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "hy4-preview",
    "messages": [
      {"role": "system", "content": "你是一名简洁的技术助手。"},
      {"role": "user", "content": "用两句话解释 API 网关的作用。"}
    ]
  }'
```

## 请求参数

以下为 `POST /v1/chat/completions` 的字段，均已实测可用。

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `model` | string | 是 | 要调用的模型 ID，例如 `hy4-preview`。 |
| `messages` | array | 是 | 按顺序排列的对话消息（system、user、assistant、tool）。多轮对话把历史消息放回这个数组即可。该模型只支持文本，`content` 请传字符串。 |
| `stream` | boolean | 否 | 是否以 SSE 流式返回，默认 `false`。 |
| `stream_options` | object | 否 | 设置 `{"include_usage": true}` 后，最后一个数据块携带 `usage`，其 `choices` 为空数组。 |
| `max_tokens` | integer | 否 | 生成 token 上限。推理 token 也计入其中：设得太小时，模型可能把额度全部用于推理，正文为空，`finish_reason` 为 `length`。 |
| `max_completion_tokens` | integer | 否 | 全部生成 token 的上限，包含推理。设得太小时正文可能为空，`finish_reason` 为 `length`。 |
| `temperature` | number | 否 | 采样温度。 |
| `top_p` | number | 否 | 核采样阈值，一般与 temperature 二选一调整。 |
| `presence_penalty` | number | 否 | 对已出现过的内容施加惩罚，鼓励引入新话题。 |
| `frequency_penalty` | number | 否 | 按出现频率施加惩罚，减少重复。 |
| `response_format` | object | 否 | `{"type": "json_object"}` 返回 JSON 对象；`{"type": "json_schema", "json_schema": {...}}` 返回符合你的 Schema 的 JSON（已用 `strict: true` 实测）。 |
| `tools` | array | 否 | 模型可以调用的函数工具列表（`type` 为 `function`）。 |
| `tool_choice` | string / object | 否 | `auto`、`none`、`required`，或指定某个函数。 |
| `reasoning_effort` | string | 否 | 推理强度，例如 `low`、`medium`、`high`。实测该模型接受此参数，对推理长度的影响因模型而异。 |
| `user` | string | 否 | 你自己的终端用户标识，用于审计或风控，不会作为对话内容。 |

### 其他格式

| 格式 | 必填字段 | 回答位置 |
| --- | --- | --- |
| OpenAI Responses | `model`, `input` | `output_text` |
| Anthropic Messages | `model`, `max_tokens`, `messages` | `content[]` 中 type 为 `text` 的块 |

## 响应格式

**响应示例**

```json
{
  "id": "chatcmpl-1792766122484",
  "object": "chat.completion",
  "created": 1792766122,
  "model": "hy4-preview",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "API 网关是接收客户端请求的统一入口，负责把请求转发到对应的后端服务；同时统一处理鉴权、限流和日志等通用逻辑。",
        "reasoning_content": "用户需要两句话解释 API 网关……"
      },
      "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
    }
  }
}
```

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `id` | string | 本次请求的 ID，联系支持时请一并提供。 |
| `object` | string | 固定为 `chat.completion`，流式时为 `chat.completion.chunk`。 |
| `created` | integer | Unix 时间戳（秒）。 |
| `model` | string | 实际生成回答的模型。 |
| `choices[].message.content` | string | 回答正文。 |
| `choices[].message.reasoning_content` | string | 模型的推理过程，与正文分开返回。 |
| `choices[].message.tool_calls` | array | 传入 `tools` 时，模型请求调用的工具。 |
| `choices[].finish_reason` | string | `stop`、`length` 或 `tool_calls`。 |
| `usage` | object | `prompt_tokens`、`completion_tokens`、`total_tokens`，以及 `prompt_tokens_details.cached_tokens`（缓存命中）和 `completion_tokens_details.reasoning_tokens`（推理 token）。 |

设置 `stream: true` 后，回答以 `data:` 开头的 `chat.completion.chunk` 数据行逐段返回，最后一行是 `data: [DONE]`。

## 错误与限制

### 常见错误

| HTTP | error.code | 含义 | 处理建议 |
| --- | --- | --- | --- |
| `401` | — | API Key 缺失、错误或已删除，message 为 `Invalid token`。 | 检查 `Authorization: Bearer` 请求头，并在控制台核对 Key。 |
| `400` | — | 请求体不是合法 JSON。 | 修正 JSON，并带上 `Content-Type: application/json`。 |
| `500` | `invalid_request` | 缺少必填字段，例如未传 `messages`。 | 按 message 补全字段，重试无效。 |
| `403` | `insufficient_user_quota` | 账户余额或套餐额度不足。 | 在控制台充值后重试。 |
| `503` | `model_not_found` | 模型 ID 不存在，或你的分组下没有可用渠道。 | 在模型列表或 `GET /v1/models` 中核对模型 ID。 |
| `429` | — | 请求过于频繁。 | 指数退避后重试。 |
| `5xx` | — | 上游服务商出错或超时。 | 稍后重试几次；持续出错时保留 request id 联系支持。 |

### 使用限制与说明

- 不支持图片输入。实测中模型描述了一张它并没有收到的图片，请不要发送图片。
- 推理过程在 `reasoning_content` 中单独返回，与 `content` 中的回答分开，展示给终端用户时请按需取舍。
- 推理可能很长：实测一个图片请求把 4000 个 token 全部用于推理，一个需要两次工具调用的请求在 240 秒内没有返回。请预留足够的 `max_tokens` 和超时时间。

## 更多链接

- [HY4 Preview API 文档页](https://tokenra.io/zh/docs/hy4-preview.html)：参数表和 cURL、Python、JavaScript、Java 代码示例
- [公共信息](https://tokenra.io/zh/docs/common.html)：Base URL、鉴权、错误码与重试
- [快速开始](https://tokenra.io/zh/docs/quickstart.html)：创建 Key 并发出第一个请求
- [全部模型](https://tokenra.io/zh/docs/models.html)：所有模型 ID
- [本指南的英文版](https://tokenra.io/docs/hy4-preview/llms.txt)
- [面向 AI 代理的站点索引](https://tokenra.io/llms.txt)

---

本文档的规范地址：https://tokenra.io/zh/docs/hy4-preview/llms.txt