图片模型 API

HY Image 3.5 Preview · API 接入

通过媒体任务接口使用腾讯 HY Image 3.5 Preview，包含参数、参考图限制、请求示例和原生能力边界。

POST/v1/tasksMODELhy-image-v3.5-preview

官方对应 hy-image-v3.5-preview核对 2026-10-15官方资料

代码示例与响应

请求与响应代码示例

POST/v1/tasks

服务端调用

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"
    }
  }'

服务端调用

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);

服务端调用

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))

平台地址已填入，运行前设置 API_KEY 环境变量。示例不会自动发起请求。

响应字段节选 · 示意值

202任务已受理

JSON

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

200成功结果

JSON

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

创建后如何查询结果

调用流程异步媒体任务

创建任务01
POST /v1/tasks
提交 model + input，保存返回的任务 id。
202 · pending
轮询状态02
GET /v1/tasks/{id}
pending / processing 时等待并继续查询。
等待 → 再查询
读取终态03
result.assets[] / error
按任务终态读取对应结果。
succeeded→ assetsfailed→ error

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

请求示例

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

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。超时或结果不明确时不要重新提交付费生成。

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 和错误信息，通过原任务查询结果。

官方来源

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