跳转到内容
HiAPI Docs
HiAPI
在线试用 获取 API Key
中文
English 中文

Wan 2.7 Image Pro API

POST /v1/tasks

所有模型都通过 统一异步接口 POST /v1/tasks 调用，区别只在 input 字段（见下方 input 参数）。

模型概览

模型名称 wan2.7-image/text-to-image
类型 图像生成（文生图）
接口 POST /v1/tasks
价格 见 HiAPI 定价

通义万相 Wan 2.7 专业版文生图模型：最高 4K（约 4096²）超清输出，提示词遵循度高，中英文提示词均可，官方主打图内长文字渲染，适合中文海报、电商图与含文字的设计物料。

生产建议

生产环境建议
  • 生产环境建议在请求体顶层传 callback.url，让 HiAPI 在任务进入终态时主动通知你的服务，减少无效轮询。
  • GET /v1/tasks/:id 更适合本地调试、低频任务，或作为回调失败后的补偿查询。
  • callback.when 当前建议固定为 final；success 和 fail 都可能触发终态通知，你的服务端需要按 taskId 做幂等处理。

适用场景

中文场景海报 / 电商图

中文 prompt 原生优化，人像、商品、美食等写实题材表现稳定，店招、招牌等中文元素还原准确，适合国内电商与营销素材。

prompt
4K 印刷级输出

4K 档总像素约 4096²，且与 1K/2K 同价；印刷物料、大屏展示等追求极致清晰度的场景可直接选 4K，不增加成本。

resolution
含文字的设计稿

图内长文字渲染是官方主打方向：海报标题、标签、店招等文字可直接写进提示词，建议把文字内容用引号标注清楚。

prompt
超宽条幅 Banner

8:1 / 1:8 超宽档位在同类文生图模型中少见，适合网页顶通、电商会场条幅、竖版长图等极端画幅。

aspect_ratio

请求参数

model string 必填

固定填 wan2.7-image/text-to-image。

示例 wan2.7-image/text-to-image
input object 必填

业务参数对象；Wan 2.7 Image Pro 的模型专属配置都放在这里。

prompt string 必填

图像生成的文本提示词，中英文均可；1-5000 字符，超出会自动截断。

aspect_ratio enum 可选

输出图像的宽高比；8:1 / 1:8 超宽条幅是本模型的特色档位。

默认 1:1 可选值: 1:116:94:321:93:49:168:11:8
resolution enum 可选

输出分辨率档位：1K 约 1024²、2K 约 2048²（默认）、4K 约 4096² 总像素量级；三档同价。

默认 2K 可选值: 1K2K4K
thinking_mode boolean 可选

开启后模型增强推理以提升出图质量，会增加生成耗时；HiAPI 默认关闭。

默认 false
seed integer 可选

随机种子，取值 0-2147483647；相同 seed 生成结果相似，但不保证完全一致。

callback object 可选

可选回调配置；设置后任务进入终态时 HiAPI 会主动通知你的服务，减少轮询。

url string 必填

传入 callback 时必填；接收任务终态通知的 HTTPS 地址。

示例 https://your-domain.com/hiapi/callback
when enum 可选

回调触发时机；当前建议固定为 final。

默认 final 可选值: final

用例示例

中文店招海报（2K）

中文提示词 + 图内文字的典型场景：把要出现在画面里的文字直接写进提示词。

请求体
{
  "model": "wan2.7-image/text-to-image",
  "input": {
    "prompt": "现代咖啡馆店面，黄金时段暖光，木质吊牌写着 WAN CAFE，橱窗暖黄灯光，行人路过，照片级写实，高细节",
    "aspect_ratio": "3:4",
    "resolution": "2K"
  }
}
4K 写实美食图

4K 与 1K/2K 同价，商品图、美食图等需要放大细节的素材可以直接上 4K。

请求体
{
  "model": "wan2.7-image/text-to-image",
  "input": {
    "prompt": "俯拍平铺美食，黑色石锅韩式拌饭，五彩新鲜蔬菜，芝麻点缀，柔和自然光，超细节",
    "aspect_ratio": "1:1",
    "resolution": "4K"
  }
}
8:1 超宽会场条幅

特色超宽档位：电商会场、网页顶通条幅一次出图，不需要后期拼接。

请求体
{
  "model": "wan2.7-image/text-to-image",
  "input": {
    "prompt": "电商大促顶通条幅，横向延展的红金渐变背景，中央写着\"年中狂欢 全场五折\"艺术字，两侧散落礼盒与彩带，扁平插画风",
    "aspect_ratio": "8:1",
    "resolution": "2K"
  }
}

获取结果

  1. 提交成功后立即返回 taskId（不等待生成完成）。
  2. 生产环境优先等待 callback.url 收到终态通知；本地调试时可轮询 GET /v1/tasks/:id。
  3. status=success 后，从返回的 output[].url 下载生成的图片。
  4. 如果 status=fail，按返回的错误信息修正请求，不要盲目重试同一个无效请求。

常见问题

价格怎么算？不同分辨率价格一样吗？

按张计费，且 1K/2K/4K 三档分辨率同价——选 4K 不会比 1K 更贵，需要高清输出时可以放心用 4K。实时价格以定价页为准。 查看实时价格

thinking_mode 是什么？什么时候开？

开启后模型会先做增强推理再出图，通常能提升构图与细节质量，但生成耗时明显增加。HiAPI 默认关闭；海报定稿等对画质要求高、不赶时间的任务可以开启，批量快速出图建议保持关闭。

生成的图片链接能保存多久？

上游图片 URL 与任务数据仅保留 24 小时，过期后无法再取回。请在任务成功后及时下载，或使用 HiAPI 产物存储转存到自己的空间。

支持中文提示词吗？怎么写效果好？

支持，中英文提示词均可，且对中文场景（店招、海报、中文文字元素）有原生优化。提示词 1-5000 字符，超出会自动截断；把主体、环境、光线、风格写清楚的结构化描述效果更好，需要图内文字时用引号标注文字内容。

下一步