如何通过 HiAPI API 调用 flux-3-max/text-to-video：curl 与 Python 指南

flux-3-max/text-to-video 的功能与适用场景

flux-3-max/text-to-video 是 HiAPI 上的文本转视频端点：您发送一段描述场景的提示词，模型返回一段生成的视频片段。当您拥有文字构想而非现成素材时——例如产品预告、社交媒体短视频、分镜预览或批量生成的空镜头——并且希望将生成过程作为托管任务而非自行运行时，它就是合适的工具。

它适用于视频只是更大流程中一环的工作流。脚本生成器产出提示词，flux-3-max/text-to-video 将其转化为视频片段，您的应用负责存储或交付结果。由于调用是异步的，它也适合无法为渲染时长保持请求打开的后端服务。

当您需要对现有视频进行帧精确编辑，或者您的提示词实际上只是一张静态图片时，请不要使用它——对于后者，文本转图像端点更便宜也更快速。如果输出必须对提供的素材做出反应，则应使用图像转视频变体。请将 flux-3-max/text-to-video 视为从提示词到视频片段生成的入口，并围绕提交任务而非同步响应来设计您的集成。

请求结构：端点、认证与负载

对 flux-3-max/text-to-video 的每次请求都包含三部分：端点路径、认证头，以及一个指明模型及其输入的 JSON 请求体。

认证

HiAPI 使用 bearer 令牌。将您的 API 密钥放入 Authorization 头中：

Authorization: Bearer $HIAPI_API_KEY
Content-Type: application/json

请将密钥保留在服务端。不要将其嵌入客户端代码或提交到版本库；开发时从环境变量加载，生产环境从密钥管理器加载。

模型标识符

在请求体中，model 字段用于选择端点。请使用精确标识符 flux-3-max/text-to-video；此处拼写错误是请求被拒绝的最常见原因。

负载结构

最小的请求体包含模型名称和提示词：

{
  "model": "flux-3-max/text-to-video",
  "prompt": "日出时分，薄雾笼罩的松林上空缓缓航拍，电影级光影"
}

可选字段——时长和原生音频开关——将在下一节介绍。由于生成是异步的，此 POST 请求的即时响应是一个带有标识符的任务对象，您需要轮询该标识符，而不是直接获得完成的视频。请将代码设计为首先读取该标识符，其他信息次之。

控制时长与原生音频

两个请求级控制项决定了您获得的结果：视频片段的时长，以及模型是否在生成视频的同时生成音频。

时长

在负载中通过 duration 字段设置片段长度。选择能满足叙事的最短时长——短片渲染更快、更易于审核，而且您可以随时再请求一个。提交前请根据 flux-3-max/text-to-video 的文档范围校验该值；超出范围的时长会在提交时被拒绝，在本地捕获该问题可节省一次往返。

原生音频

原生音频开关决定模型是否随视频片段生成音轨。当视频将带声音观看时开启，当视频将被静音、加字幕或在后期单独配乐时关闭。生成您将丢弃的音频只会增加任务时间而毫无益处。

有意识地选择

避免让默认值替您做决定。对于快速分镜审核，一个简短无声的片段通常就足够了。对于最终的社交媒体素材，带原生音频的较长片段可能才是目标。请将该选择编码到应用配置中，而非在调用处硬编码，这样您就可以按功能更改而无需修改请求代码。只发送您实际想要覆盖的字段，其余字段让端点应用其默认值。

可用的 curl 请求

确认凭据和负载最快的方式是使用一次 curl 调用提交任务。

curl -X POST "$HIAPI_BASE_URL/v1/videos/generations" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "flux-3-max/text-to-video",
    "prompt": "一只纸船漂过被雨水浸湿的街道，温暖的街灯，浅景深",
    "duration": 5,
    "native_audio": false
  }'

请先在 shell 中设置 HIAPI_BASE_URL 和 HIAPI_API_KEY。此处的时长和音频值仅为示例——请使用该模型文档范围内的值。

读取即时响应

响应是一个任务对象，而非视频。它包含一个 job_id（或等效标识符）以及诸如 queued 或 processing 的状态。请保存该标识符；它是您后续每次调用的句柄。如果响应看起来是一个错误对象，请在重试前检查状态码和消息——格式错误的负载每次都会以相同方式失败。

成功提交仅表示任务已被接受，仅此而已。不要试图在首次响应中寻找视频 URL；在任务完成之前它不会出现在那里。

处理异步任务生命周期

视频生成需要数秒到数分钟，因此 HiAPI 将其建模为任务。您的客户端提交一次，然后检查状态，直到任务达到终止状态。

状态

任务从 queued 到 processing 再到终止状态——completed 或 failed。只有终止状态才是最终状态；中间的任何状态都意味着继续等待。

轮询而不轰炸

使用您保存的任务标识符轮询状态端点。两条规则可保持轮询健康：

• 在轮询之间等待。 从较短的间隔开始并逐步退避，或使用明显长于典型排队时间的固定间隔。轰炸状态端点毫无收益。
• 设置上限。 限制总等待时间和总尝试次数。如果届时任务尚未完成，请将其上报给您的应用，而不是无限循环。

在 Web 处理程序中，不要让请求线程阻塞在轮询循环上。提交、存储任务标识符、立即返回，并让后台工作线程或客户端轮询完成生命周期。在批处理场景中，使用带 sleep 的简单循环即可。

读取结果

当任务报告为 completed 时，响应会携带输出引用——您的应用可以下载或流式传输的视频 URL 或素材句柄。失败时，请读取 error 字段；它通常会指明原因（无效参数、内容拒绝、内部错误）。请将任务标识符和失败消息一起记录，以便支持请求或重试有据可依。切勿将缺失输出字段视为成功——请显式检查状态。

Python 中的相同请求

curl 流程可直接映射到 Python。一个最小客户端需要提交、轮询循环，以及足够的错误处理来区分错误请求和缓慢任务。

import os, time
import requests

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

HEADERS = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}

def submit(prompt, duration=5, native_audio=False):
    body = {
        "model": "flux-3-max/text-to-video",
        "prompt": prompt,
        "duration": duration,
        "native_audio": native_audio,
    }
    resp = requests.post(f"{BASE}/v1/videos/generations",
                         headers=HEADERS, json=body, timeout=30)
    resp.raise_for_status()
    return resp.json()["job_id"]

def wait(job_id, interval=5, max_attempts=60):
    for attempt in range(max_attempts):
        time.sleep(interval)
        r = requests.get(f"{BASE}/v1/videos/generations/{job_id}",
                         headers=HEADERS, timeout=30)
        r.raise_for_status()
        data = r.json()
        status = data.get("status")
        if status == "completed":
            return data
        if status == "failed":
            raise RuntimeError(data.get("error", "job failed"))
    raise TimeoutError(f"job {job_id} did not finish in time")

实现说明

raise_for_status() 将传输和 HTTP 错误（认证、负载格式错误）与任务级失败区分开来，后者出现在成功响应内部。failed 检查会显式读取 error 字段，而非假定状态为 completed。尝试次数上限将无界等待转变为可预测的异常。

在生产环境中，请为轮询包装针对瞬态网络错误的 Retry 策略，并复用单个 requests.Session。如果您运行大量任务，请将 wait 移至工作线程而非请求路径中。

排查常见失败

大多数集成问题可归入几个类别。每一类都有具体的检查方法。

认证错误

401 或 403 意味着密钥缺失、过期或格式错误。请确认 Authorization 头存在、使用 Bearer 方案，并且环境变量在运行时中确实已被填充——而不仅仅是您的 shell 中。

负载格式错误

400 通常意味着请求体不符合 schema。请验证 JSON 可解析、model 精确为 flux-3-max/text-to-video，且请求发送了 Content-Type: application/json。请使用 JSON 库序列化，而非手工构建字符串。

参数值无效

时长超出文档范围、未知字段名或音频开关类型错误，都会在提交时导致拒绝。发送前请根据模型文档参数在本地校验。

过早轮询

提交后立即且反复轮询并不会让任务更快完成。请使用退避或固定间隔，并让任务对象告诉您它何时已越过 queued 状态。

未处理的任务失败

达到 failed 的任务不一定是您的请求有 bug——它可能是内容拒绝或内部错误。请阅读错误消息，记录任务标识符，并决定是使用修改后的提示词重试还是上报。

将提交响应视为结果

如果您的代码期望在提交后立即获得视频 URL，它将会出错。首次响应是一个任务；只有终止状态才携带输出。一旦这六项检查到位，大多数集成问题都能得到解决。