教程
如何使用 hiapi API 通过 flux-3 进行 AI 视频编辑
这里的“编辑”有特定含义：flux-3（FLUX.3 Video，出自 Black Forest Labs）会扩展一段已有片段——延续其运动、镜头运动和声音，生成新的画面——或者基于一组有序的关键帧图像构建一个镜头。它不会对现有素材进行裁剪、剪切、遮罩、调色或其他就地处理。如果你来这里是想找剪辑器，下面的 FAQ 是在你写任何代码之前判断 flux-3 是否真正适合你的最快方法。
它真正擅长的是：拿一段你已有的视频，生成一段延续，保持相同的主体、镜头语言和音频——适用于延长一段过早结束的镜头，或者将多个生成的片段串联成一段更长的镜头。另一种模式接收一组静态图像作为有序关键帧，并生成它们之间的运动，这就像基于分镜脚本的编辑，尽管不涉及任何已有视频。
1. 你需要什么
一个来自仪表盘的 hiapi API 密钥（sk-...）。flux-3 与所有其他 hiapi 模型一样，通过统一的 task API 调用，因此这里没有任何模型专属的设置——如果你之前调用过任何其他 hiapi 视频模型，你要准备的东西已经齐了。
2. 最小可运行示例
创建一个任务，然后轮询它（或使用回调——见生产模式）直到它达到终止状态。
# 1. 创建任务——延续模式（start_video）
curl -s -X POST https://api.hiapi.ai/v1/tasks \
-H "Authorization: Bearer sk-<your-key>" \
-H "Content-Type: application/json" \
-d '{
"model": "flux-3",
"input": {
"prompt": "继续平移，镜头继续向右漂移，保持相同光照",
"start_video": "https://your-cdn.example.com/source-clip.mp4",
"duration": 5,
"resolution": "720p",
"aspect_ratio": "16:9",
"generate_audio": true
}
}'
# -> {"data": {"id": "task_...", "status": "pending"}}
# 2. 轮询直到终止
curl -s https://api.hiapi.ai/v1/tasks/task_... \
-H "Authorization: Bearer sk-<your-key>"
# -> {"data": {"id": "task_...", "status": "succeeded",
# "output": [{"url": "https://...mp4", "expireAt": "..."}]}}
start_video 是一个指向 MP4 的公开 HTTPS URL（源素材上限为 50MB 和 15 秒）——这就是 flux-3 继续的片段。duration 是 5 到 20 秒的整数，控制新生成片段的长度，而不是合成后输出的长度。resolution 是 720p 或 1080p；aspect_ratio 接受 auto、21:9、2:1、16:9、4:3、1:1、3:4 或 9:16。generate_audio 是布尔值——当为 true 时，模型生成的环境声音会直接烘焙进输出 MP4，而不是作为单独的音频文件。在迭代提示词时设置 draft: true；草稿任务更便宜，但会强制 resolution 只能是 720p（同时带 draft: true 和 resolution: "1080p" 的请求会被拒绝）。
关键帧分镜（不是编辑现有素材）
另一种输入模式用 image_urls 替代 start_video——一个包含 1 到 10 个图像 URL 的有序数组，flux-3 会将其视为分镜，生成按顺序连接它们的运动：
{
"model": "flux-3",
"input": {
"prompt": "平滑地推轨依次穿过每个场景",
"image_urls": [
"https://your-cdn.example.com/keyframe-1.jpg",
"https://your-cdn.example.com/keyframe-2.jpg",
"https://your-cdn.example.com/keyframe-3.jpg"
],
"duration": 8,
"resolution": "720p"
}
}
image_urls 和 start_video 是同一模型上的两种不同任务形态——不要在一个请求中同时发送它们。当你从静态图像从零开始构建一个镜头时使用 image_urls；当你已有生成（或源）素材想要向前延续时使用 start_video。
3. 生产模式
规模化时用回调代替轮询。 在同一个请求体中传入 callback 对象，而不是在循环中轮询：
{
"model": "flux-3",
"input": { "...": "..." },
"callback": { "url": "https://your-service.example.com/hooks/hiapi", "when": "final" }
}
when: "final" 只触发一次，在任务达到任意终止状态时触发——succeeded 或 failed 都是终止状态，因此请按 taskId 对你的 webhook 处理器去重，而不是假定回调只意味着成功。轮询 GET /v1/tasks/:id 更适合本地调试、低频一次性任务，或者作为回调未到达时的对账回退。
幂等性。 如果不小心，超时或连接断开后的重试可能会创建重复的（可计费的）任务——跟踪创建调用返回的任务 id，并在考虑提交新任务之前，把重试变成对该 id 的 GET。
输出 URL 会过期。 每个输出条目上的 expireAt 字段不是装饰——无论你是从回调还是轮询得知任务成功，都要在任务成功后立即下载视频并持久化到你自己的存储中。
认证失败。 错误或缺失的密钥会返回 HTTP 401，内容为 {"error": {"code": "permission_denied", ...}}。请显式检查该状态/代码，而不是假定任何非 2xx 都意味着生成本身失败——“我的密钥错了”和“模型拒绝了我的输入”需要不同的修复方法。
提交前验证媒体 URL。 start_video 和 image_urls 会检查类型和格式，但不会检查该 URL 处的文件是否实际存在或可解码——一个语法有效但已损坏的 URL 仍然能创建一个任务，运行几秒后才失败，而不是在提交时就被拒绝。在将 URL 接入批处理任务之前，请确认它们确实能解析。
4. 相关页面
- flux-3 模型页面——完整参数参考、演练场，以及全部三种模式（文本生成视频、关键帧分镜和延续）的当前每秒、每分辨率定价。
- 创建任务文档——完整的
/v1/tasks请求/响应参考，包括回调选项。 - 认证文档——
Authorization: Bearer sk-...请求头和密钥作用域如何工作。 - AI 视频中的首尾帧控制——一个相关方案，适用于在两帧静态图像之间插值的模型，如果 flux-3 的多关键帧分镜模式对你的镜头来说不够精细的话。
- hiapi 定价——当前费率（延续的定价高于标准生成，草稿模式比两者都便宜——请查看实时页面，而不是硬编码的数字）。
5. 常见问题
flux-3 能裁剪、剪切、遮罩或调色现有视频吗？ 不能。flux-3 的“视频生视频”模式是延续——它生成新画面，延续源片段的主体、镜头运动和声音。它不会修改已经存在的帧。目前没有任何 hiapi 模型能在视频上进行时间线式裁剪/剪切编辑或遮罩区域编辑。
延续和关键帧分镜有什么区别？
延续（start_video）需要现有视频文件并扩展它。关键帧分镜（image_urls）只需要静态图像并生成它们之间的运动——不需要源视频。它们是同一 flux-3 模型 id 上互斥的输入。
我可以在一个请求中同时使用 start_video 和 image_urls 吗？
不能——每个任务选择一种模式。同时发送两者不是受支持的输入形态。
draft: true 在延续模式下可用吗？
可用，而且这是在提交全分辨率运行之前迭代延续提示词的更便宜的方式——但与标准模式一样，草稿延续也限制为 720p。
为什么我的任务几乎瞬间就失败了，而不是花通常的生成时间？
最常见的原因是 start_video 或 image_urls 条目在请求时实际上没有解析为有效文件——API 会接受语法格式正确的 URL，而不会同步获取它们，因此坏链接会表现为快速的 failed 状态，而不是前置的验证错误。
延续模式下源片段可以多长？
最多 15 秒和 50MB，格式为 MP4。更长或更大的源文件不能作为 start_video 输入被接受。
