博客

教程

如何通过 HiAPI API 调用 flux-3-video：curl、Python 与实际可用的请求示例

一份实用集成指南，涵盖文生视频、视频续写和原生音频参数

2026年11月3日

flux-3-video 通过 API 提供的能力

在动笔写第一行代码之前，先了解 flux-3-video 模型通过 HiAPI API 到底能做什么，会很有帮助。该端点系列涵盖两种调用模式，它们共用同一套请求结构，此外还有一项可选的音频能力，你可以根据用例选择启用或忽略。

两种调用模式

文生视频——你发送一段文本提示词，收到一段新生成的视频片段。当您只有一个创意，希望由模型来生成运动、构图和节奏时，就使用这种模式。
视频续写——你发送一段已有视频片段（或其引用）以及指令，模型将其向前延展。当你已有素材，希望在不出现可见接缝的情况下获得更多内容时，就使用这种模式。

原生音频

该模型还可以在生成视频的同时产出原生音频，由同一份请求载荷中的可选参数控制。由于这些参数是可选的，纯视频工作流完全无需考虑它们——你只需省略音频字段，请求的行为就与没有它们时完全一致。

本指南后续内容所依赖的核心心智模型是：这并不是两个彼此独立的 API，也不是两套分开的教程。它们是同一个请求的两种形态；一旦理解了共用的骨架，在两者之间切换就只是替换几个输入而已。其余一切——凭证、请求头、模型标识符、响应处理——都保持不变。

这种设计是有意为之。这意味着你的鉴权代码、错误处理、重试逻辑和响应解析只需编写一次，即可在两种模式中复用；之后添加音频也不会迫使你重写。

鉴权、端点与请求结构剖析

对 flux-3-video 的每次调用都遵循同一套骨架。掌握一次，两种调用模式便成为同一主题的变体。

凭证

HiAPI 使用 API key 对请求进行鉴权。你通过请求头传入它，通常以 bearer token 的形式。请勿将密钥写入源代码——从环境变量或密钥管理器中读取，确保它永远不会进入版本控制系统：

export HIAPI_API_KEY="your-key-here"

端点与模型标识符

调用发往 HiAPI API 的基础 URL，负载通过标识符 flux-3-video 显式指定模型。将模型名写在请求体中而不是硬编码进 URL，意味着同一份客户端代码日后只需改一行即可指向其他模型。

共用的负载结构

无论哪种模式，负载都是一个 JSON 对象，概念上包含三个部分：

model 字段——始终为 flux-3-video。
定义模式的输入——在文生视频中是一段提示词；在续写中是源视频片段加一段提示词。这是两种模式之间唯一发生实质变化的部分。
可选修饰项——音频参数以及其他调节项。省略它们即得到默认行为。

一个请求的伪结构如下：

{
  "model": "flux-3-video",
  "input": {
    "prompt": "..."
  }
}

整体思路就是这样：一个模型标识符、一个承载模式专属字段的嵌套 input 对象，以及仅在需要时才添加的可选键。接下来的章节会逐一说明各模式的具体细节。

文生视频：你的第一个可用 curl 请求

下面是一个最小但完整的请求，从提示词生成一段视频。它假定 HIAPI_API_KEY 已在你的 shell 中导出。

curl -X POST "$HIAPI_BASE_URL/v1/generate" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "flux-3-video",
    "input": {
      "prompt": "A slow dolly shot through a rain-soaked neon alley at night, reflections on wet asphalt, cinematic"
    }
  }'

各字段的作用

Authorization——携带你的 bearer token。缺少它，请求会在任何生成开始之前被拒绝。
Content-Type: application/json——请求体是 JSON，所以请声明这一点；遗漏它是导致令人困惑的 4xx 响应的常见原因。
model——将 flux-3-video 标识为目标模型。
input.prompt——文生视频模式下唯一必需的创意输入。请像写镜头描述那样撰写：主体、运动、构图、光线、氛围。

值得投入的提示词撰写要点

由于提示词是该模式下唯一的创意控制杆，其质量直接决定结果。两个习惯会有帮助：

描述运动，而不仅是内容。“A dolly shot through…”（一个推轨镜头穿过……）给了模型可动画化的摄像机行为；静态描述则让它无从发挥。
保持具体。具体的光线与材质线索（“wet asphalt”“neon reflections”）往往比抽象形容词产出更连贯的画面。

运行此请求并检查响应后，你就验证了密钥、请求头和基础负载——这是后续一切的基础。

视频续写：延展已有片段

续写复用了上一节的骨架，但 input 对象的形态发生了变化。提示词不再单独存在，而是与模型要延展的源片段配对。

curl -X POST "$HIAPI_BASE_URL/v1/generate" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "flux-3-video",
    "input": {
      "prompt": "Continue the camera push forward as the alley opens into a crowded market",
      "video": "<reference-to-existing-clip>"
    }
  }'

相对于文生视频的变化

出现了一个视频输入。你提供模型应基于其构建的已有片段。这是两种模式之间的决定性差异。
提示词变为导向性的，而非生成性的。在文生视频中你描述整个场景；这里你描述接下来会发生什么。请把它写成续写指令：摄像机往哪里去、什么进入画面、场景如何演变。
其余一切完全相同。相同的端点、相同的请求头、相同的模型标识符、相同的 input 包装。你的客户端代码直到构建负载时才需要分支。

保持接缝处的一致性

模型需要匹配源片段的观感以避免可见的剪切。简短而具体、保留既有风格的指令，往往比重新构想场景的长篇描述效果更好。如果第一次续写发生漂移，应让提示词更贴近源片的实际内容，而不是在其他地方添加更多细节。

关于片段引用的说明

源片段的确切输入约定由 HiAPI 上该模型的输入 schema 定义。请遵循该 schema，而不是猜测字段格式——它是续写输入接受何种内容的权威来源。

添加原生音频参数

原生音频正是可选修饰项模式发挥价值之处。音频参数与其余字段一样位于同一个 input 对象中，且由于它们是可选的，前两节的请求在没有它们时依然有效。

它们的位置

音频设置属于 input 内部，与 prompt 以及（续写模式下的）video 并列。概念上：

{
  "model": "flux-3-video",
  "input": {
    "prompt": "...",
    "audio": {
      "enabled": true
    }
  }
}

保障纯视频工作流安全

这里重要的纪律很简单：把音频块视为纯粹附加的。

不要显式把音频字段设为“关闭”值——省略它们即可。缺失该块比显式禁用更干净，也更不容易与未来的 schema 变更冲突。
增量构建负载。从最小请求体开始，仅在用户确实要求音频的代码路径中才添加 audio 键。这样可让你的默认路径与纯视频示例完全一致。
在把音频接入生产环境之前，查阅 schema 以确认确切的标志名和可接受值。参数命名由 HiAPI 上该模型的输入 schema 定义；上方的块名仅展示位置，并不保证字段拼写。

何时启用

当交付物是一段成品、自包含的视频片段时启用音频——社交媒体内容、演示、短叙事作品。当你将在下游另外铺设自有配乐或旁白时，则保持关闭；生成你终将丢弃的音频是在流水线中浪费算力。

由于音频与其他一切搭载在同一份负载中，因此没有单独的调用、没有第二份凭证，除了读取响应所返回的内容外，也无需维护额外的响应处理分支。

用 Python 写同样的请求

将 curl 调用转写为 Python 是机械性的工作，因为请求结构完全相同。下面的示例仅使用标准库，因此可在任何环境中运行；如果你更偏好 requests 或 httpx，其结构也可直接对应。

import json
import os
import urllib.request

API_KEY = os.environ["HIAPI_API_KEY"]
BASE_URL = os.environ["HIAPI_BASE_URL"]

def generate_video(prompt, video=None, audio=False):
    input_block = {"prompt": prompt}

    # Continuation mode: attach the source clip.
    if video is not None:
        input_block["video"] = video

    # Audio is strictly additive and omitted by default.
    if audio:
        input_block["audio"] = {"enabled": True}

    payload = {"model": "flux-3-video", "input": input_block}

    request = urllib.request.Request(
        f"{BASE_URL}/v1/generate",
        data=json.dumps(payload).encode("utf-8"),
        headers={
            "Authorization": f"Bearer {API_KEY}",
            "Content-Type": "application/json",
        },
        method="POST",
    )

    with urllib.request.urlopen(request) as response:
        return json.loads(response.read().decode("utf-8"))


if __name__ == "__main__":
    # Text-to-video
    result = generate_video(
        "A slow dolly shot through a rain-soaked neon alley at night"
    )
    print(result)

    # Video continuation with native audio
    result = generate_video(
        "Continue the camera push forward as the alley opens into a market",
        video="<reference-to-existing-clip>",
        audio=True,
    )
    print(result)

为何如此组织

一个函数，两种模式。video 参数是可选的；当它为 None 时，该函数生成文生视频请求。当它被设置时，同一函数生成续写请求。没有单独的客户端，也没有重复的请求头。
音频需显式启用。audio 标志默认为 False，因此除非明确要求，音频块永远不会被添加——这正是前文描述的模式。
密钥来自环境。API key 从 HIAPI_API_KEY 读取，绝不硬编码。

改造时，只需将 print 调用替换为你的流水线所需的操作——将响应写入清单、入队后续任务或通知某个队列。请求逻辑本身无需改变。

故障排查与生产环境检查清单

当调用失败时，请按顺序逐项排查以下列表——它能覆盖绝大多数问题。

诊断清单

401 或鉴权错误——HIAPI_API_KEY 是否确实已在运行代码的 shell 或进程中导出？在一个终端中设置的密钥不会传递给 cron 作业。
415 或意外的解析错误——Content-Type: application/json 是否存在？遗漏它是最典型的静默失败。
续写调用返回 4xx——你的负载是否以模型输入 schema 所期望的形式包含了源片段？格式错误的片段引用会在生成开始前就失败。
输出中缺少音频——audio 块是否真的进入了负载？调试时请记录序列化后的请求体；构建了字典却忘记附加该键的情况很容易发生。
input 为空或被截断——打印你实际发送的精确 JSON。几乎每一个“诡异”的失败在亲眼看到线上传输的请求体后都会迎刃而解。

上线之前

绝不硬编码密钥。始终使用环境变量或密钥管理器。
同时记录请求体和响应体，至少要在预发布环境中如此。缺少精确的负载去复现失败只能是猜测。
把可选字段当作可选的。增量构建负载——先最小请求体，再添加 video，最后仅在需要时添加 audio。这能让你的默认路径与文档示例保持一致。
在你自己的代码中保持模式选择显式可见。用一个带可选 video 参数的函数没问题；把布尔值埋在三层深处则不行。
每当你添加字段时，重新查阅 HiAPI 上该模型的输入 schema。它是参数名与可接受格式的权威参考，且会比任何教程都更为及时。

核心要点值得重申：文生视频、续写和原生音频是同一请求形态的三种变体。把骨架掌握一次，每一项新能力都只是一次附加式改动，而非重写。祝你构建愉快。

查看全部文章 →