教程
如何使用 Creatify Boreal API：文本、图像和音频生成视频
creatify-boreal 是 hiapi 上的一个视频模型，返回已混合好语音和声音的成品片段。一个模型 id 覆盖三种起点：仅提示词、提示词加参考图像，或提示词加你自己的旁白音频。本指南展示请求、轮询循环，以及我实际运行一次真实生成后的结果。
你需要从 hiapi 仪表盘 获取 API 密钥。所有调用都通过统一任务端点 POST /v1/tasks 进行。
输入字段
这些字段已对照实时模型页面，并通过向 /v1/tasks 发送故意无效的值进行验证；无效值会返回 400 且不计费。
| 字段 | 必填 | 接受的值 |
|---|---|---|
prompt |
是 | 文本，最多 5000 个字符 |
image_url |
否 | JPG/PNG/WebP，10 MB；设定主体和构图 |
audio_url |
否 | MP3/WAV/M4A，15 MB；仅使用前 duration 秒 |
negative_prompt |
否 | 最多 2000 个字符 |
resolution |
否 | 720p、1080p、2k |
aspect_ratio |
否 | auto、16:9、9:16、1:1、4:3、3:4 |
duration |
否 | 整数秒，1 到 20 |
这三种模式并非独立的模型 id。文本生成视频时省略 image_url 和 audio_url；图像生成视频时添加 image_url；添加 audio_url（通常同时提供图像）让出镜者跟随你的旁白。
最小可用请求
curl -X POST 'https://api.hiapi.ai/v1/tasks' \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
"model": "creatify-boreal",
"input": {
"prompt": "竖屏自拍风格 UGC 视频：一位年轻女性在明亮的卧室里举起一支柔粉色唇膏，对着镜头说：\"好吧，这是唯一撑过我冬天的唇膏。\" 自然的房间环境音。",
"resolution": "720p",
"aspect_ratio": "9:16",
"duration": 4
}
}'
响应会给出任务 id：
{"code":200,"data":{"taskId":"tk-hiapi-01M5MJC8NG8E1E0XN9NEJRDBQH"},"message":"success"}
Python：提交与轮询
import os, time, requests
BASE = "https://api.hiapi.ai/v1/tasks"
HEADERS = {"Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}"}
def create(payload: dict) -> str:
r = requests.post(BASE, headers=HEADERS, json=payload, timeout=30)
r.raise_for_status()
return r.json()["data"]["taskId"]
def wait(task_id: str, every: int = 10, limit: int = 900) -> dict:
start = time.time()
while time.time() - start < limit:
try:
d = requests.get(f"{BASE}/{task_id}", headers=HEADERS, timeout=30).json()["data"]
except (requests.RequestException, ValueError):
time.sleep(every) # 瞬时网络错误：继续轮询同一个 id
continue
if d["status"] == "success":
return d
if d["status"] == "fail":
raise RuntimeError(d.get("error"))
time.sleep(every)
raise TimeoutError(task_id)
task_id = create({
"model": "creatify-boreal",
"input": {
"prompt": "竖屏自拍风格 UGC 视频：一位年轻女性举起一支柔粉色唇膏，对着镜头说：\"好吧，这是唯一撑过我冬天的唇膏。\" 自然的房间环境音。",
"resolution": "720p",
"aspect_ratio": "9:16",
"duration": 4,
},
})
result = wait(task_id)
print(result["output"][0]["url"])
状态依次经过 handling、archiving，然后到 success。视频 URL 位于 data.output[0].url。
图像与音频模式
图像生成视频额外添加一个字段：
{"model": "creatify-boreal",
"input": {"prompt": "这位女性在厨房里对着镜头微笑说话：\"我把咖啡换成了这款燕麦拿铁混合饮品。\" 自然的厨房环境音。",
"image_url": "https://your-cdn.example/presenter.jpg",
"resolution": "720p", "duration": 8}}
音频驱动模式添加指向旁白文件的 audio_url。模型页面将其描述为旁白保留在视频中，嘴唇跟随旁白动作，并说明仅使用音频的前 duration 秒，因此请将 duration 设置为你想要的片段长度。模型页面的音频示例将音频与参考图像搭配；我本人没有运行图像加音频的生成，因此该组合在本文中属于文档记载而非已验证。
真实运行的样子
我运行了上面的请求（纯文本、720p、9:16、4 秒）。
- 生成时间： 任务在
handling状态约 283 秒，然后在archiving状态约 10 秒。即使对 4 秒片段，也要按分钟而非秒来规划。每 10 秒轮询一次或使用回调，而不是短超时。 - 输出文件： 720x1280 的 MP4，H.264 视频 24 fps 加 AAC 音轨，时长 4.04 秒。尽管请求没有音频字段，音频仍然存在，这符合模型的原生声音设计。
- 临时 URL： 输出 URL 位于
temp.hiapi.ai，带有约 7 天后到期的expireAt。请下载文件并自行存储，而不是从页面链接它。 - 成本形态： 按秒计费，且取决于
resolution（参见 定价页面），因此迭代提示词最便宜的方式是 720p 加较短的duration，然后用 1080p 或 2k 重新渲染最终版本。
我遇到的坑
- 错误值会快速失败且免费。 发送
aspect_ratio: "7:5"、duration: 25或resolution: "4k"均返回 HTTP 400INVALID_REQUEST，消息中列出允许的值（'auto', '16:9', '9:16', '1:1', '4:3', '3:4'，最大 20，以及'720p', '1080p', '2k'）。利用这一点在提交前验证你自己的表单。 - 错误的媒体 URL 会在稍后轮询时失败。 我提交了
audio_url: "https://example.com/a.mp3"（不是真实的音频文件）。创建调用返回 HTTP 200 和任务 id，约 15 秒后任务以status: "fail"和error.code: "INVALID_REQUEST"结束。因此创建时返回 200 并不意味着你的媒体可用；始终检查最终状态并读取data.error。在这种情况下，失败是在 HTTP 200 的轮询响应内呈现，而不是作为 HTTP 错误。 - 失败是
status: "fail"，不是 HTTP 状态。 轮询请求本身返回 200，因此请检查data.status。
相关页面
- Creatify Boreal 模型页面：Playground、实时定价和示例片段
- hiapi 定价
- hiapi 文档
- 如何使用 OmniHuman 1.5 API：另一个出镜者风格视频模型
- Ray 3.2 图像生成视频 API
- Wan 3.0 视频 API 指南
常见问题
文本、图像和音频输入需要单独的模型 id 吗？
不需要。三者都使用 creatify-boreal；你在 input 中包含的字段决定模式。
片段最长可以多长？ 1 到 20 的整数秒。值 25 会被 HTTP 400 拒绝。
输出包含声音吗？ 包含。4 秒的测试片段即使没有提供音频输入，也带有 AAC 音轨。
有哪些可用分辨率？
720p、1080p 和 2k。计费因分辨率而异；请查看定价页面。
我应该等多久？ 我 4 秒 720p 的测试端到端约用了五分钟。请使用带充裕上限的轮询或回调。
