Hy-Image-3.5-preview

hy-image-v3.5-preview 以 Chat/Messages 协议提交生图请求，同步返回结果，支持多模态输入（文本 + 参考图）、多轮编辑，最高支持 4096x4096（4K）输出。

前置条件

@cloudbase/js-sdk 3.11.0 或更高版本
已开通云开发环境，具备生图资源（如小程序成长计划赠送额度）
仅支持通过云开发 SDK 调用，与旧版 hunyuan-image 通道不同，无需配置 generateImageSubUrlConfig

使用示例

基本文生图

import cloudbase from "@cloudbase/js-sdk";

const app = cloudbase.init({ env: "your-env-id" });
const ai = app.ai();

const imageModel = ai.createImageModel("cloudbase");

const res = await imageModel.generateImage({
  model: "hy-image-v3.5-preview",
  messages: [
    {
      role: "user",
      content: [{ type: "text", text: "一只在沙滩上奔跑的金毛犬，傍晚的暖色光" }],
    },
  ],
});

// 最终交付图片，URL 12 小时内有效
const image = res.choices[0].delta.image;
console.log(image.url, image.width, image.height);

4K 输出

const res = await imageModel.generateImage({
  model: "hy-image-v3.5-preview",
  size: "4096x4096", // 宽高 [256, 8192]，面积不超过 4096x4096
  messages: [
    { role: "user", content: [{ type: "text", text: "一张海报级构图的城市夜景" }] },
  ],
});

参考生图

content 中混排文本与图片即可，图片支持公网 URL 或 Base64（data:image/...;base64,...）：

const res = await imageModel.generateImage({
  model: "hy-image-v3.5-preview",
  session: "demo-session-001", // 多轮请求保持同一 session，提升效果与速度
  messages: [
    {
      role: "user",
      content: [
        { type: "text", text: "参考这张图的风格，画一只猫" },
        { type: "image_url", image_url: { url: "https://your-domain.com/dog.png" } },
      ],
    },
  ],
});

多轮编辑

下一轮请求的 messages = 上一轮的 messages + 上一轮响应的 assembled_history + 本轮新的 user 消息。assembled_history 由服务端拼好，直接透传即可：

// 第一轮
const firstMessages = [
  {
    role: "user",
    content: [
      { type: "text", text: "参考这张图的风格，画一只猫" },
      { type: "image_url", image_url: { url: "https://your-domain.com/dog.png" } },
    ],
  },
];
const firstRes = await imageModel.generateImage({
  model: "hy-image-v3.5-preview",
  session: "demo-session-001",
  messages: firstMessages,
});

// 第二轮：回灌 assembled_history 继续编辑
const secondRes = await imageModel.generateImage({
  model: "hy-image-v3.5-preview",
  session: "demo-session-001",
  messages: [
    ...firstMessages,
    ...firstRes.assembled_history,
    { role: "user", content: [{ type: "text", text: "把猫换成布偶猫品种，背景换成壁炉旁" }] },
  ],
});

输入参数

参数	类型	必选	说明
`model`	string	是	固定为 `hy-image-v3.5-preview`，传入其他值 SDK 会直接报错
`messages`	`Array<object>`	是	多轮会话内容，从旧到新排列，服务端取最后一条 `role=user` 的消息作为本轮生图指令
`size`	string	否	生成尺寸，格式 `${宽}x${高}`。宽高 ∈ [256, 8192]，面积不超过 4096x4096。传入即强制按该尺寸出图
`seed`	integer	否	生成种子，范围 [0, 2^63-1]，为 0 或不传时随机。固定 seed + prompt + size 可复现结果
`generate_max_pixels`	integer	否	目标面积档位，仅在未传 `size` 时生效。可选 `1048576`（1K）、`2359296`（1.5K，默认）、`4194304`（2K）
`resize_max_pixels`	integer	否	输入参考图面积上限，默认 `1048576`，超过时等比缩放后再送入模型
`session`	string	否	会话 ID，多轮编辑时保持同值，请求会落到同一推理实例
`footnote`	string	否	自定义水印内容，最长 16 字符，生成在图片右下角
`use_search_tool`	`{ value: boolean }`	否	外部搜索增强开关，默认关闭

messages 元素

参数	类型	必选	说明
`role`	string	是	`user` / `assistant` / `tool`，`tool` 仅在回灌上一轮生图结果时出现
`content`	`Array<object>`	否	该轮内容，见下表。`assistant` 仅触发工具调用时可省略
`reasoning`	string	否	仅 `assistant` 回灌时使用，透传上一轮响应中的思维链原文
`tool_calls`	`Array<object>`	否	仅 `assistant` 回灌时使用，标准 OpenAI tool_call 结构
`tool_call_id`	string	否	仅 `role=tool` 回灌时使用，须与 `tool_calls[i].id` 一致

content 元素

参数	类型	必选	说明
`type`	string	是	`text` 或 `image_url`
`text`	string	否	`type=text` 时的文本内容
`image_url`	`{ url: string }`	否	`type=image_url` 时的图片，支持公网 URL 或 Base64。单图 ≤ 20MB，最多 20 张

尺寸与面积组合

组合	结果
只传 `size`	强制按指定宽高出图，4K 场景用这种方式
`size` + `generate_max_pixels`	兼顾 `size` 的比例与面积档位，取模型效果最佳的宽高
只传 `generate_max_pixels`	默认 1:1 比例，面积归档到 1K / 1.5K / 2K
都不传	模型基于 prompt 语义自主决定（默认 1.5K 档）

⚠️ generate_max_pixels 最高档位为 2K，需要 4K 输出必须通过 size 指定。

返回值

interface CloudbaseGenerateImageOutput {
  id: string; // 请求 traceID
  object: string; // 固定 "image.chat.completion.chunk"
  created: number; // Unix 秒级时间戳
  model: string; // 上游内部版本标识，不建议用于业务分支
  round: number; // 所属 LLM 轮次，从 0 起算
  choices: Array<{
    index: number;
    delta: {
      type?: string;
      image?: {
        url: string; // 最终交付图片 URL，12 小时有效
        width: number;
        height: number;
        source: string;
        tool_call_id: string;
      };
    };
    finish_reason?: string | null; // 成功时通常为 null，判断成功以 delta.image 为准
  }>;
  usage?: { total_tokens: number };
  tokenhub_usage?: { total_tokens: number };
  request_id?: string;
  assembled_history?: Array<object>; // 下一轮回灌消息序列，多轮编辑时透传
  error?: { type: string; code: string; message: string; request_id?: string };
}

读取最终图片取 choices[0].delta.image.url；assembled_history 中的 role=tool 图片 URL 是中间产物，仅用于下一轮回灌。

⚠️ 所有图片 URL 均为临时地址，有效期 12 小时，请及时下载转存到云存储。

错误码

HTTP 状态码	说明	处理建议
400	请求格式有误	检查字段类型与取值（如 size 约束、messages 结构）
401	鉴权不通过	检查环境与鉴权方式
422	内容安全审核未通过	调整 prompt 或业务策略
429	请求并发超过限额	退避重试，控制并发
500	服务端内部错误	可重试，持续失败请联系技术支持并提供 `request_id`

超时提示

图片生成耗时较长（4K 输出更久），在云函数中调用时建议将超时时间设置为 900 秒。

图片生成概述 — 模型能力总览
JS SDK 调用 — JS SDK 生图环境要求与初始化
文生图（旧版模型） — HY-Image-3.0 调用说明

前置条件​

使用示例​

基本文生图​

4K 输出​

参考生图​

多轮编辑​

输入参数​

messages 元素​

content 元素​

尺寸与面积组合​

返回值​

错误码​

相关文档​