# HY Image 3.5 Preview · API 接入

模型 ID：`hy-image-v3.5-preview`。支持文生图和参考图编辑，平台任务 API 异步受理；渠道调用同步返回结果。使用前核对实时模型目录和账号价格。

## 请求示例

设置平台 API 地址与服务端 `API_KEY`。文生图省略 `images`；参考图编辑传入公网可访问的 PNG/JPEG 图片 URL。

```bash
curl "https://newrouters.com/v1/tasks" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
    "model": "hy-image-v3.5-preview",
    "input": {
      "prompt": "Change the cup to blue while preserving its shape, lighting and background.",
      "images": ["https://your-domain.example/reference.jpg"],
      "resolution": "1k",
      "aspect_ratio": "1:1",
      "output_format": "jpeg"
    }
  }'
```

## 查询结果

创建成功返回任务 ID；轮询原任务直到 `succeeded` 或 `failed`，读取 `result.assets` 或 `error`。超时或结果不明确时不要重新提交付费生成。

```bash
curl "https://newrouters.com/v1/tasks/TASK_ID" -H "Authorization: Bearer $API_KEY"
```

## 平台参数

| 字段 | 默认值 | 契约 |
| --- | --- | --- |
| `prompt` | 无 | 必填，非空文本；官方上下文上限 100k tokens，不等于字符数 |
| `images` | `[]` | 最多 20 个图片 URL；上游接受 PNG/JPEG/JPG，单图 ≤20MB；调用方应提前校验格式和大小 |
| `resolution` | `1k` | `1k` / `2k` / `4k` |
| `aspect_ratio` | `auto` | `auto` / `1:1` / `4:3` / `3:4` / `16:9` / `9:16` / `3:2` / `2:3` / `21:9` |
| `output_format` | `jpeg` | `jpeg` / `png` / `webp`；此选项来自渠道图片协议 |

这些分辨率与比例是平台/渠道预设，不是腾讯原生参数列表。图片数量上限在平台校验，输入格式和文件大小由上游校验；渠道对完整 20 图边界尚未实测。单个任务固定生成一张图片，不提供 `n`。

## 官方能力与当前接入范围

腾讯 TokenHub 原生 API 支持文生图、多图参考、携带历史上下文的多轮编辑、外部搜索增强、种子、会话、输入图缩放和水印脚注。原生入口为 `/v1/wand/hunyuan-image/v35-generation`，以 `messages` 输入，返回最终图片帧和 `assembled_history`。

当前平台通过 Xinhankr 的 `/v1/images/generations` 接入：`images` 映射为 `image`，`aspect_ratio` 映射为 `ratio`，返回 `data[].url`。当前契约没有 `messages`、`session`、`seed`、`use_search_tool`、`resize_max_pixels`、`footnote` 或自定义 `size`，传入会校验失败。将上一轮图片作为新的 `images` 可以连续编辑，但不保留原生会话历史。

官方原生尺寸每边 256–8192 像素，总面积不超过 16777216；自动面积档仅有 1K/1.5K/2K，原生 4K 需显式 `size`。本站 `4k` 由渠道转换，尚未真实验收尺寸；不能把 `resolution` 当成原生 `generate_max_pixels`。

腾讯 2026-09-22 发布介绍写明 5 图/最高 2K，与 2026-10-12 更新的 TokenHub API 指南的 20 图/4K 不一致；本页 API 限制采用较新的 TokenHub 调用指南，渠道实际支持范围仍需验收。官方没有承诺透明背景、图层拆分或局部遮罩编辑，当前平台也未开放这些字段。

## 验证与错误处理

2026-10-15 已通过本地公开任务 API、现有测试 Key 和渠道账户完成一次真实 1K 文生图：17.6 秒，1024×1024 JPEG。图生图、2K/4K、多图上限和其他编码尚未真实验证，不将 Schema 支持视为实测通过。

官方原生结果链接有效期 12 小时，需及时下载保存；平台返回自己的存储资产。内容安全失败可能包含 `content_filter` 或审核拒绝信息，HTTP 成功不能单独证明生图成功。保留任务 ID 和错误信息，通过原任务查询结果。

<!-- official-reference:start -->
## 官方来源

核对日期：2026-10-15；TokenHub 指南页面更新时间：2026-10-12。

- [腾讯 TokenHub Hy 生图调用指南](https://cloud.tencent.com/document/product/1823/135745)
- [腾讯 HY Image 3.5 模型介绍](https://hunyuan.tencent.com/research/hy-image35-preview?langVersion=zh)
- [Xinhankr 图片协议](https://token.xinhankr.com/docs/openai/doc0018)

<!-- official-reference:end -->

## 多语言请求示例

### JavaScript

```javascript
const apiBaseUrl = "https://newrouters.com";
const apiKey = process.env.API_KEY;
if (!apiKey) throw new Error("Set API_KEY in your server environment");

const response = await fetch(apiBaseUrl + "/v1/tasks", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer " + apiKey
  },
  body: JSON.stringify({
  "model": "hy-image-v3.5-preview",
  "input": {
    "prompt": "Change the cup to blue while preserving its shape, lighting and background.",
    "images": [
      "https://your-domain.example/reference.jpg"
    ],
    "resolution": "1k",
    "aspect_ratio": "1:1",
    "output_format": "jpeg"
  }
})
});

const result = await response.json();
if (!response.ok) throw new Error(JSON.stringify(result));
console.log(result);
```

### Python

```python
import json
import os
from urllib.request import Request, urlopen

api_base_url = "https://newrouters.com"
api_key = os.environ["API_KEY"]
body = json.loads("{\"model\":\"hy-image-v3.5-preview\",\"input\":{\"prompt\":\"Change the cup to blue while preserving its shape, lighting and background.\",\"images\":[\"https://your-domain.example/reference.jpg\"],\"resolution\":\"1k\",\"aspect_ratio\":\"1:1\",\"output_format\":\"jpeg\"}}")

request = Request(
    api_base_url + "/v1/tasks",
    data=json.dumps(body).encode("utf-8"),
    headers={
    "Content-Type": "application/json",
    "Authorization": "Bearer " + api_key
    },
    method="POST",
)
with urlopen(request) as response:
    print(json.load(response))
```

## 响应字段节选（示意值）

### HTTP 202

```json
{
  "id": "TASK_ID",
  "status": "pending",
  "model": "hy-image-v3.5-preview",
  "result": null,
  "error": null
}
```

### HTTP 200

```json
{
  "id": "TASK_ID",
  "status": "succeeded",
  "model": "hy-image-v3.5-preview",
  "result": {
    "assets": [
      "https://example.com/output.png"
    ]
  },
  "error": null
}
```