使用指南
使用 wan2.7-video/text-to-video@pro 制作短视频：端到端 hiapi API 工作流
短视频的成败取决于迭代速度：你需要大量候选片段，竖屏格式，带声音，而且要快。本指南正是围绕这一点展开，使用 hiapi 上的 wan2.7-video/text-to-video@pro——阿里巴巴通义万相 2.7 文生视频模型，最高输出 1080P、原生音频、片段最长 15 秒。下文中的每个请求结构、参数边界和错误信息，都是撰写本文时针对线上 API 实际运行验证过的，文中嵌入的两段演示片段也由所示代码原样生成。
模型能给你什么
wan2.7-video/text-to-video@pro 通过 hiapi 的统一异步任务端点（/v1/tasks）提供服务。关键特性，已对照线上 schema 验证：
- 输出：H.264 MP4，最高 1080P，带原生 AAC 音轨——模型会根据你的提示词生成环境声和音效，无需单独的音频步骤。
- 时长：每段 2–15 秒（整数秒）。
- 宽高比：
16:9、9:16、1:1、4:3、3:4——真正竖屏 9:16，适配 Shorts/Reels/TikTok 类格式，无需裁剪。 - 计费：按输出视频秒数计费，撰写时起价 $0.167/秒——5 秒 1080P 片段约 $0.84。批量生成前请务必在定价页面确认。
视频没有同步模式：你需要创建任务、轮询直到完成，然后下载结果。
最小可运行示例（curl）
创建任务：
curl -X POST "https://api.hiapi.ai/v1/tasks" \
-H "Authorization: Bearer sk-YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "wan2.7-video/text-to-video@pro",
"input": {
"prompt": "微距棚拍：一滴宝蓝色墨水落入清水中，慢动作绽放，墨丝舒展成云朵形状，背景为明亮的白色无缝背景，清晰的高调布光，轻柔的环境嗡鸣",
"ratio": "16:9",
"resolution": "1080P",
"duration": 4
}
}'
响应：
{"code": 200, "data": {"taskId": "tk-hiapi-01KWGGS29FDZ8NRJW49YRQZ65R"}, "message": "success"}
轮询结果：
curl "https://api.hiapi.ai/v1/tasks/tk-hiapi-01KWGGS29FDZ8NRJW49YRQZ65R" \
-H "Authorization: Bearer sk-YOUR_KEY"
渲染期间，data.status 为 handling；完成后会变为 success，data.output[0].url 中即包含 MP4。该请求原样生成了此片段：
⚠️ 输出 URL 是带 expireAt 时间戳的临时链接。任务成功后请立即将文件下载到你自己的存储——不要直接热链或存入数据库。
完整输入 schema（已对照线上 API 验证）
API 会严格校验 input 并拒绝未知字段，以下是完整可接受的字段列表——直接针对端点探测所得，而非从任何地方复制：
| 字段 | 类型 | 约束 | 是否必填 |
|---|---|---|---|
prompt |
string | 场景描述；同时驱动生成的音频 | ✅ |
ratio |
string | 16:9、9:16、1:1、4:3、3:4 之一 |
可选 |
resolution |
string | 720P 或 1080P |
可选 |
duration |
integer | 2–15（秒） | 可选 |
negative_prompt |
string | 需要抑制的内容（如 水印、文字叠加） | 可选 |
seed |
integer | 重试间可复现 | 可选 |
watermark |
boolean | 切换服务商水印 | 可选 |
两个能帮你避免 400 的坑：
- 字段名是
ratio，不是aspect_ratio——hiapi 上的图像模型使用aspect_ratio，此视频模型不用。发送aspect_ratio会返回additional properties 'aspect_ratio' not allowed。 duration在服务端校验：duration: minimum: got 1, want 2和maximum: got 999, want 15就是超出 2–15 范围时得到的确切错误。
端到端 Python：输入提示词，输出可发布 MP4
这是完整工作流——创建、轮询、下载——无需 SDK，只用 requests：
import time
import requests
API = "https://api.hiapi.ai/v1/tasks"
HEADERS = {"Authorization": "Bearer sk-YOUR_KEY", "Content-Type": "application/json"}
def make_short(prompt: str, out_path: str, duration: int = 5,
ratio: str = "9:16", seed: int | None = None) -> str:
payload = {
"model": "wan2.7-video/text-to-video@pro",
"input": {
"prompt": prompt,
"ratio": ratio, # 9:16 = 竖屏短视频
"resolution": "1080P",
"duration": duration, # 2..15 秒
"negative_prompt": "文字叠加, 水印, 扭曲的手",
},
}
if seed is not None:
payload["input"]["seed"] = seed
task_id = requests.post(API, headers=HEADERS, json=payload).json()["data"]["taskId"]
while True:
task = requests.get(f"{API}/{task_id}", headers=HEADERS).json()["data"]
if task["status"] == "success":
break
if task["status"] == "fail":
raise RuntimeError(f"task failed: {task.get('error')}")
time.sleep(10)
video_url = task["output"][0]["url"] # 临时链接——请立即下载
with open(out_path, "wb") as f:
f.write(requests.get(video_url, timeout=120).content)
return out_path
make_short(
"黄金时刻手持竖屏夜市镜头：一位街头小吃摊主 "
"在火焰翻腾的炒锅中颠炒滋滋作响的面条，蒸汽和橙色火星向 "
"镜头旋转飘来，霓虹招牌在虚化背景中透出柔和的粉色和青色，浅 "
"景深，充满动感的手持纪实感，伴有滋滋声和噼啪声",
"night-market.mp4",
duration=5,
seed=20260702,
)
以下是该调用实际生成的片段——竖屏 1080×1920，5 秒，滋滋声由提示词文本生成：
在我的运行中，4 秒 16:9 片段大约 3 分钟完成，5 秒 9:16 片段稍长一些——每段预留几分钟，每约 10 秒轮询一次，不要猛打端点。
短视频提示词技巧：运动和音频都由提示词决定
schema 中没有镜头控制或运动参数——所有关于运动、节奏和声音的内容都通过提示词语言来引导。在我的测试中有效的做法：
- 明确点名镜头行为：如 "handheld"（手持）、"slow push-in"（缓慢推近）、"macro"（微距）、"shallow depth of field"（浅景深）。夜市片段的纪实晃动完全来自 "handheld" 一词。
- 描述你想要的音频：模型会根据提示词生成声音。"sizzling and crackling sounds"（滋滋声和噼啪声）和 "gentle ambient hum"（轻柔的环境嗡鸣）都出现在了输出音轨中。
- 把钩子前置：对于短视频，第一秒决定一切。把最有动感的元素（火焰颠锅、墨滴入水）放在提示词描述的开头。
- 防御性地使用
negative_prompt："text overlay, watermark, distorted hands"（文字叠加、水印、扭曲的手）能在不影响主提示词的情况下清理最常见的瑕疵。 - 迭代时固定
seed：固定 seed，一次只改一个提示词短语，观察该短语实际起什么作用。
需要首帧控制？使用图生视频变体
如果你的工作流从设计好的关键帧开始——产品图、品牌风格的首帧——文生视频不接受图像输入。配套模型 wan2.7-video/image-to-video@pro 可以：它接受 {"url": "...", "type": "image"} 对象组成的 media 数组，并搭配相同的 prompt / resolution / duration 字段，为你提供的帧做动画，而不是凭空生成一帧。同样是基于任务的流程，同样按秒计费。一条实用流水线：用图像模型生成静帧，审核通过后再对已批准的帧做动画——这样你只为已经签核的帧花费视频生成费用。
常见错误及其实际含义
invalid input: prompt: missing required field "prompt"——prompt是唯一必填字段。invalid input: ratio: value must be one of '16:9', '9:16', '1:1', '4:3', '3:4'——你传入了模型不支持的宽高比（或拼错了）。invalid input: <root>: additional properties '...' not allowed——未知字段；schema 很严格，请检查上表。status: "fail"且带TASK_FAILED——任务在创建后失败；创建新任务（复用你的seed以保持可复现）。- 下载的文件很小或无法播放——你很可能抓取了已过期的输出 URL。重新检查
expireAt，并在success后立即下载。
总结
一次 POST、一个轮询循环、一次下载——这就是从文本提示词到可发布带声竖屏 MP4 的全部距离。如果你要构建短视频流水线，从控制台获取 API key，以上面的 Python 函数起步，并浏览模型目录的其余部分——相同的 /v1/tasks 模式（如我们的 seedance-2.0-fast 指南所示）适用于平台上所有视频模型，因此之后换模型只需改一行。
