教程
如何通过 hiapi API 使用 grok-imagine-1.5/image-to-video：curl、Python 与一个可直接运行的请求
简明摘要
- 这是什么： 一份可复制的指南，介绍如何通过 hiapi 的统一任务 API 使用
grok-imagine-1.5/image-to-video将静态图像动画化为短视频。 - 流程： 通过
POST /v1/tasks创建任务，轮询GET /v1/tasks/<taskId>（或注册回调），然后在过期前从data.output[0].url下载 MP4。 - 输入 schema（已对照线上 API 验证）： 仅接受一个
image_urls条目，可选prompt，duration为 1–15 秒，resolution为480p/720p，aspect_ratio为auto、1:1、16:9、9:16、3:2、2:3之一。不接受其他字段。
你将构建什么、需要准备什么
目标：发送一张源图像加一段运动提示词，获取由 Grok Imagine 1.5 生成的短视频 MP4 片段。
前置条件：
- 一个 hiapi API 密钥——在 仪表板 中创建。密钥形如
sk-...，放在Authorization: Bearer请求头中。 - 一个可公开访问的源图像 URL（JPEG/PNG）。 API 会在服务端获取图像，因此
localhost链接或需要认证的文件无法使用。 - 任意 HTTP 客户端。以下示例使用
curl和 Python 的requests。
模型 id 是裸字符串 grok-imagine-1.5/image-to-video，无后缀。
最小可运行示例：curl
创建任务：
curl -X POST "https://api.hiapi.ai/v1/tasks" \
-H "Authorization: Bearer sk-YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "grok-imagine-1.5/image-to-video",
"input": {
"image_urls": ["https://example.com/product-shot.jpg"],
"prompt": "slow cinematic push-in, soft studio light drifting across the subject",
"duration": 6,
"resolution": "720p",
"aspect_ratio": "16:9"
}
}'
提交成功会返回 200 和一个 taskId：
{
"code": 200,
"data": { "taskId": "tk-hiapi-01KWVVSTX0TJ32AD45F6ZQ08W5", "status": "queued" },
"message": "success"
}
轮询直到任务到达终态（status 会依次经过 queued → handling → success 或 fail）：
curl "https://api.hiapi.ai/v1/tasks/tk-hiapi-01KWVVSTX0TJ32AD45F6ZQ08W5" \
-H "Authorization: Bearer sk-YOUR_KEY"
已完成任务（真实响应，已截断）：
{
"code": 200,
"data": {
"taskId": "tk-hiapi-01KWVVSTX0TJ32AD45F6ZQ08W5",
"model": "grok-imagine-1.5/image-to-video",
"status": "success",
"storage": "temp",
"output": [
{
"type": "video",
"url": "https://temp.hiapi.ai/.../01KWVVSTX0TJ32AD45F6ZQ08W5-0.mp4",
"expireAt": 1783951451
}
]
},
"message": "success"
}
⚠️ storage: "temp" 和 expireAt 意味着下载 URL 是临时的。任务成功后立即下载 MP4 并存储到你自己的基础设施上——不要热链。
最小可运行示例：Python
完整脚本——创建、轮询、下载：
import time
import requests
API_KEY = "sk-YOUR_KEY"
BASE = "https://api.hiapi.ai/v1/tasks"
HEADERS = {"Authorization": f"Bearer {API_KEY}"}
# 1. Create the task
resp = requests.post(BASE, headers=HEADERS, json={
"model": "grok-imagine-1.5/image-to-video",
"input": {
"image_urls": ["https://example.com/product-shot.jpg"],
"prompt": "slow cinematic push-in, soft studio light drifting across the subject",
"duration": 6,
"resolution": "720p",
"aspect_ratio": "16:9",
},
})
resp.raise_for_status()
task_id = resp.json()["data"]["taskId"]
print("task:", task_id)
# 2. Poll for the result (image-to-video usually lands well within a few minutes)
deadline = time.time() + 600
while time.time() < deadline:
task = requests.get(f"{BASE}/{task_id}", headers=HEADERS).json()["data"]
status = task["status"]
if status == "success":
break
if status == "fail":
raise RuntimeError(f"generation failed: {task.get('error')}")
time.sleep(5)
else:
raise TimeoutError(f"task {task_id} still not finished after 10 min")
# 3. Download immediately — the output URL expires
video_url = task["output"][0]["url"]
mp4 = requests.get(video_url, timeout=120)
mp4.raise_for_status()
with open("clip.mp4", "wb") as f:
f.write(mp4.content)
print("saved clip.mp4,", len(mp4.content), "bytes")
输入参考（schema 实际接受的内容）
这些约束直接来自线上验证器，并非猜测——发送其他内容会返回 400 INVALID_REQUEST，并附带精确消息：
| 字段 | 类型 | 规则 |
|---|---|---|
image_urls |
字符串数组 | 必填，恰好 1 个 URL（maxItems: 1） |
prompt |
字符串 | 可选——描述运动、镜头运动和情绪 |
duration |
整数 | 1–15 秒 |
resolution |
字符串 | 480p 或 720p |
aspect_ratio |
字符串 | auto、1:1、16:9、9:16、3:2、2:3 |
说明：
- 该模型没有
seed、negative_prompt、fps、motion_strength或camera_fixed字段。 schema 会拒绝未知属性（additional properties ... not allowed），因此请完全通过prompt控制运动和镜头行为。 - 每个任务只能有一张参考图像。传入两张会返回
image_urls: maxItems: got 2, want 1。 aspect_ratio: "auto"会遵循源图像自身的比例——这通常是产品图想要的效果。- 较旧的 grok-imagine/image-to-video 每段最多接受 30 秒； 1.5 上限为 15 秒。两者每秒价格相同：480p 为 $0.015，720p 为 $0.0282。
生产环境注意事项
使用回调代替轮询。 对于脚本之外的任何场景，在创建任务时注册 webhook，跳过轮询循环：
{
"model": "grok-imagine-1.5/image-to-video",
"input": { "image_urls": ["https://example.com/shot.jpg"], "duration": 6 },
"callback": { "url": "https://yourapp.com/hooks/hiapi", "when": "final" }
}
callback.url 必须是公开的 http(s) 端点，且 when 仅支持 "final"——任务到达 success 或 fail 时你会收到一次 POST。轮询适用于 CLI 和批处理任务；当你需要批量生成大量片段且不想部署一群轮询器时，回调更胜一筹。保留一个兜底轮询（例如每隔几分钟检查没有收到回调的任务），以免 webhook 丢失导致任务搁浅。
幂等性。 任务创建在服务端不会去重，因此网络超时后的简单重试可能导致重复提交和重复计费。创建调用返回后立即持久化 taskId，重试时先检查你自己的存储；如果你在提交和持久化之间崩溃，列出最近任务（GET /v1/tasks），在重新提交前按模型 + 创建时间匹配。
错误处理。 你实际会遇到的失败模式：
401搭配{"error": {"code": "permission_denied", "type": "hiapi_error", ...}}——密钥错误，或密钥无权访问该模型。响应中包含用于支持的request_id。400搭配error_code: "INVALID_REQUEST"——schema 违规；message会指明具体字段和规则（例如duration: maximum: got 99, want 15）。修正请求体，不要盲目重试。402余额不足——视频模型在提交时会预检查你的配额。充值后重新提交。- 任务本身
status: "fail"——生成端失败；检查data.error并退避重试。源图像不可访问是常见原因。
立即存储输出。 值得重复：output[0].url 位于临时存储上，带有 expireAt 时间戳。看到 success 的那一刻，立即将 MP4 流式传输到你自己的存储桶。如果你的管道在成功之后、下载之前崩溃，按 id 重新获取任务——URL 在 expireAt 之前保持有效，并非永久有效。
相关阅读
- grok-imagine-1.5/image-to-video 模型页面——定价、参数和浏览器内 playground
- 如何使用 grok-imagine/image-to-video——前代模型，相同任务流程，30 秒上限
- Grok Imagine 文生视频指南——从提示词而非图像开始
- hiapi API 参考——完整任务 API 契约
常见问题
grok-imagine-1.5 视频可以多长？
1 到 15 秒，由整数 duration 字段设置。请求更长会返回 400（duration: maximum: got X, want 15）。如果需要最长 30 秒，请使用较旧的 grok-imagine/image-to-video。
它支持哪些分辨率和宽高比？
resolution 为 480p 或 720p；aspect_ratio 为 auto、1:1、16:9、9:16、3:2 或 2:3。720p 下的 9:16 是 Shorts/Reels 风格竖屏片段的首选组合。
我可以传入多张参考图像吗？
不可以——该模型的 image_urls 恰好只接受一个 URL。对于多参考工作流，请串联任务或先将参考图合成为单张输入图像。
有 seed 或负面提示词吗？
没有。输入 schema 会直接拒绝 seed、negative_prompt、fps 及类似字段。运动风格、镜头运动和情绪全部通过 prompt 字符串控制。
费用是多少？
按生成视频的秒数计费：480p 为 $0.015/秒，720p 为 $0.0282/秒。6 秒片段在 480p 下为 $0.09，在 720p 下为 $0.1692。如果不传 duration，默认 8 秒。更多示例见 Grok Imagine 1.5 定价明细。
为什么我的请求返回 401 permission_denied？
要么 API 密钥错误/已撤销，要么它无权访问该模型。在 仪表板 中验证密钥，并确保发送 Authorization: Bearer sk-...——缺少 Bearer 前缀会产生相同错误。
如何在不轮询的情况下知道视频已就绪？
创建任务时附加 "callback": {"url": "https://your-endpoint", "when": "final"}。任务到达终态后，hiapi 会向你的端点发送 POST。作为兜底，轮询 GET /v1/tasks/<taskId>。
为什么我的视频 URL 几天后停止工作？
输出位于临时存储上——每个输出条目都带有 expireAt 时间戳。在 success 后立即下载文件，并从你自己的存储中提供。
