教程

如何在 hiapi 上使用 wan2.7-image-standard API：文生图与参考图编辑

2026年11月3日

wan2.7-image-standard 是通义万相 Wan 2.7 Image 模型的标准档。它值得单独开一页的原因在于：一个模型 ID 同时支持文生图和基于参考图的图像编辑，最高支持 2K，按固定价格每张图 $0.0345 计费——比支持 4K 的 Pro 档更便宜。本指南提供一个可直接运行的请求、精确的输入 schema（已对照线上 API 验证）、参考图编辑路径，以及你在生产环境中必须处理的边界行为。

下文 schema 和错误部分的所有内容，均是在写作过程中探测线上 /v1/tasks 端点确认的——枚举列表、可接受的字段集合以及失败响应形态均引用自真实 API 响应，而非凭记忆。

你将构建什么、需要准备什么

你将提交一个提示词（可选附带参考图），轮询直到任务完成，然后下载图像。首先需要一样东西：从 hiapi 快速入门获取一个 API key，并将其导出为 HIAPI_API_KEY。不存在免 key 路径——每个请求都通过 Authorization: Bearer sk-<your-key> 进行认证。

wan2.7-image-standard 运行在 hiapi 的异步任务 API 上：你先 POST /v1/tasks 创建任务，然后轮询详情端点直到其报告终态。

文生图：最小请求

创建任务：

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "wan2.7-image-standard",
    "input": {
      "prompt": "雨后的蓝调时刻，一条安静无人的小巷里有一间小陶艺工作室，挂着温暖的纸灯笼，橱窗里摆着上釉的茶壶，湿润的石板路上倒映着灯光，一辆自行车靠在墙边，电影感 35mm 摄影，高细节",
      "aspect_ratio": "16:9",
      "resolution": "2K"
    }
  }'

响应中的任务 id 位于 data.taskId：

{ "code": 200, "data": { "taskId": "tk-hiapi-01M5D5..." }, "message": "success" }

然后轮询 GET /v1/tasks/<taskId> 直到 data.status 为 success，并从 data.output[0].url 读取图像 URL：

import os, time, requests

API = "https://api.hiapi.ai/v1/tasks"
HEADERS = {"Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}"}

def generate(prompt, aspect_ratio="16:9", resolution="2K", image_urls=None, timeout=600):
    payload = {"model": "wan2.7-image-standard",
               "input": {"prompt": prompt,
                         "aspect_ratio": aspect_ratio,
                         "resolution": resolution}}
    if image_urls:                      # 参考图编辑（见下一节）
        payload["input"]["image_urls"] = image_urls

    create = requests.post(API, headers=HEADERS, json=payload).json()
    if create.get("code") != 200:       # 同步校验错误（例如枚举值无效）
        raise RuntimeError(create)
    task_id = create["data"]["taskId"]

    deadline = time.time() + timeout
    while time.time() < deadline:
        data = requests.get(f"{API}/{task_id}", headers=HEADERS).json()["data"]
        if data["status"] == "success":
            return requests.get(data["output"][0]["url"]).content
        if data["status"] == "fail":    # 终态失败——不要继续轮询
            raise RuntimeError(data.get("error"))
        time.sleep(5)
    raise TimeoutError(task_id)

png = generate("...")   # 立即保存字节——参见下文过期说明

aspect_ratio 和 resolution 都是可选的（模型有默认值），但请显式设置——resolution 只接受 1K 或 2K，且两者计费相同，因此没有成本理由将其保留为默认值。

基于参考图的编辑：同一个模型 ID，加上 image_urls

这就是标准档与 Pro 档的区别所在。在 image_urls 中传入参考图（一个数组，根据模型规格最多 9 张参考图），模型会基于它们进行编辑或重新构图，同时仍然遵循你的文本提示词：

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "wan2.7-image-standard",
    "input": {
      "prompt": "将这款产品放在阳光充足的大理石厨房台面上，旁边放着新鲜香草，清晨柔和光线，生活方式产品摄影",
      "image_urls": ["https://your-storage.example.com/product.jpg"],
      "resolution": "2K"
    }
  }'

在 Python 中，就是传给上面辅助函数的 image_urls=[...] 参数——其他都不变。即使传入参考图，prompt 仍然必填（API 会拒绝没有 prompt 的请求：missing required field "prompt"）。

字段名很重要：是 image_urls。那些看似合理的替代名——reference_image_urls、image_input、input_urls——都会被 schema 以 additional properties '<name>' not allowed 拒绝。如果你是从其他模型的编辑端点移植代码，这是首先要修正的地方。

精确的输入 schema

schema 是严格的：任何不在以下列表中的字段都会返回 400 INVALID_REQUEST，并附带 additional properties '<name>' not allowed。以下是它接受的全部字段：

字段	类型	必填	说明
`prompt`	string	是	文生图和编辑均必填。可用英文或中文。
`aspect_ratio`	string enum	否	取值之一：`1:1`、`16:9`、`4:3`、`21:9`、`3:4`、`9:16`、`8:1`、`1:8`。其他任何值（例如 `3:2`）→ 400。
`resolution`	string enum	否	仅 `1K` 或 `2K`。此档不支持 4K。
`image_urls`	string[]	否	用于编辑的参考图（最多 9 张）。传入即切换到参考模式。
`seed`	integer	否	用于可复现的输出。

你可能会想到但这个模型不接受的字段：negative_prompt、n、size 和 prompt_optimizer 都会作为未知属性被拒绝。没有批量（n）参数——每张图提交一个任务。

生产注意事项与实测行为

提交时返回 200 并不意味着图像一定会生成。wan2.7-image-standard 会同步校验枚举值（错误的 resolution 或 aspect_ratio 会立即让 POST 以 400 INVALID_REQUEST 失败），但它不会在提交时校验参考 URL。格式错误或不可达的 image_urls 条目会被接受，返回 200 和一个 taskId，然后任务大约一秒后失败。我直接验证了这一点：用无效参考 URL 创建的任务返回的终态如下

{ "status": "fail", "error": { "code": "INVALID_REQUEST", "message": "invalid request parameters for this model" } }

实际后果是：始终轮询到终态，并依据 data.status == "fail" 分支处理（读取 data.error）。失败任务报告为 HTTP 200 且 data.status: "fail"——失败信息位于 data.error 中，而不是顶层 HTTP 错误。提交前请确保你的参考 URL 可公开访问。

立即下载输出。data.output[0].url 是一个带有 expireAt 时间戳的临时链接，不是永久 CDN 资源。任务成功的瞬间就获取字节内容并转移到你自己的存储；过期 URL 会 404。如果你已遇到此问题，请参阅为什么你的 hiapi 输出 URL 会 404 以及如何处理。

轮询 vs. 回调。上面的示例每五秒轮询一次，这对脚本和小批量来说没问题。对于生产吞吐量，请在创建请求中附加 callback，让 hiapi 在终态事件时通知你，而不是由你保持连接——具体机制见创建任务文档。

标准档 vs. Pro：该调用哪一档

hiapi 托管两个 Wan 2.7 Image 档位，它们是不同的模型 ID，而非参数：

wan2.7-image-standard（本指南）——文生图和参考图编辑，1K/2K，无论哪种分辨率都按固定价格 每张图 $0.0345 计费。
wan2.7-image/text-to-image——Pro 档：仅文生图，最高 4K，固定价格每张图 $0.08。参见 Wan 2.7 Image Pro 页面以及关于用它生成 4K 电商产品图的详解。

当你需要基于参考图的编辑，或者 2K 足够且希望支付不到 Pro 每张图价格一半时，选择标准档。只有当你特别需要原生 4K 输出时才使用 Pro——这是标准档唯一做不到的事。两者的当前价格见价格页面。

常见问题

wan2.7-image-standard 支持图像编辑，还是仅支持文生图？两者都支持，来自同一个模型 ID。添加 image_urls 数组即可切换到基于参考图的编辑；省略它则为纯文生图。

最大分辨率是多少？2K。resolution 字段只接受 1K 和 2K；线上 API 会拒绝其他任何值。如果你需要 4K，请使用 Pro 档（wan2.7-image/text-to-image）。

为什么我的任务返回了 200 然后失败了？参考 URL 在提交时不会被检查——只在执行时检查。不可达或格式错误的 image_urls 条目会创建任务（HTTP 200），然后以 INVALID_REQUEST 终态失败。请轮询 data.status 并验证你的 URL 是公开的。

我可以设置负面提示词吗？不可以。negative_prompt 不是此模型接受的字段（n、size 或 prompt_optimizer 也不是）。请通过正向的 prompt 和 seed 来引导。