One continuous 5-second cinematic shot. A violinist performs in a sunlit stone cathedral, dust motes drifting through tall shafts of morning light. Camera: slow forward dolly at chest height, no cuts. Lighting: warm volumetric sunbeams against cool stone. Native audio: a rich solo violin melody echoing in the stone acoustic space, faint bow texture. No logos, no readable text, no products, no packaging, no prices, no CTA, no advertising, no watermark, no brand marks.
FLUX 3 Text to Video API
blackforestlabs/flux-3/text-to-videoFLUX 3 Text to Video 将文本提示词转化为 5–20 秒高保真视频,支持精确物理运动模拟、可选原生同步音频与 8 种画幅构图。它在长镜头中保持动作与运镜连贯,并使对白、音效与画面事件同步生成。
示例
REST API
快速开始
完成 API 认证,提交提示词与生成指令,再通过任务 ID 获取视频结果。
连接 Vidgo API
创建 API Key,仅保存在服务端,并发送 Authorization: Bearer VIDGO_API_KEY。
- 接口
- POST
https://api.vidgo.ai/api/generate/submit - 认证
- Authorization: Bearer VIDGO_API_KEY
提交一次生成任务
按请求示例填写当前端点的参数与设置,提交后保存 task_id,用于后续查询生成进度和结果。
REQUEST_BODY=$(cat <<'JSON'
{
"model": "blackforestlabs/flux-3/text-to-video",
"input": {
"prompt": "One continuous 5-second cinematic shot. A violinist performs in a sunlit stone cathedral, dust motes drifting through tall shafts of morning light. Camera: slow forward dolly at chest height, no cuts. Lighting: warm volumetric sunbeams against cool stone. Native audio: a rich solo violin melody echoing in the stone acoustic space, faint bow texture. No logos, no readable text, no products, no packaging, no prices, no CTA, no advertising, no watermark, no brand marks.",
"duration": 5,
"resolution": "720p",
"aspect_ratio": "16:9",
"sound": true
}
}
JSON
)
RESPONSE=$(curl --silent --show-error --fail-with-body \
--request POST \
--url "https://api.vidgo.ai/api/generate/submit" \
--header "Authorization: Bearer $VIDGO_API_KEY" \
--header "Content-Type: application/json" \
--data "$REQUEST_BODY")
CODE=$(printf '%s' "$RESPONSE" | jq -r '.code // empty')
if [ "$CODE" != "0" ] && [ "$CODE" != "200" ]; then
printf 'API error: %s
' "$RESPONSE" >&2
exit 1
fi
printf '%s
' "$RESPONSE"等待结果
用 task_id 查询,not_started/running 继续,finished/failed 停止。成功后读取 data.files[].file_url。
查询状态
GET https://api.vidgo.ai/api/generate/status/{task_id}以 2 秒为基准间隔轮询状态,长时间任务可适当拉长间隔。仅在 not_started 或 running 时继续,遇到 finished 或 failed 立即停止。也可以在同一请求中配置 callback_url 接收回调通知。
not_startedrunningfinishedfailed{
"code": 200,
"data": {
"task_id": "task-unified-...",
"status": "running",
"created_time": "2026-09-16T10:00:00Z"
}
}{
"code": 200,
"data": {
"task_id": "task-unified-...",
"status": "finished",
"files": [
{
"file_url": "https://storage.vidgo.ai/generated/video.mp4",
"file_type": "video"
}
],
"created_time": "2026-08-22T10:00:00Z",
"progress": 100,
"error_message": null
}
}完整可运行示例
展开后可查看包含 HTTP 与业务码检查、task_id 校验、轮询、终态处理和超时边界的完整脚本。
set -euo pipefail
: "${VIDGO_API_KEY:?Set VIDGO_API_KEY in your environment}"
REQUEST_BODY=$(cat <<'JSON'
{
"model": "blackforestlabs/flux-3/text-to-video",
"input": {
"prompt": "One continuous 5-second cinematic shot. A violinist performs in a sunlit stone cathedral, dust motes drifting through tall shafts of morning light. Camera: slow forward dolly at chest height, no cuts. Lighting: warm volumetric sunbeams against cool stone. Native audio: a rich solo violin melody echoing in the stone acoustic space, faint bow texture. No logos, no readable text, no products, no packaging, no prices, no CTA, no advertising, no watermark, no brand marks.",
"duration": 5,
"resolution": "720p",
"aspect_ratio": "16:9",
"sound": true
}
}
JSON
)
SUBMIT_RESPONSE=$(curl --silent --show-error --fail-with-body \
--request POST \
--url "https://api.vidgo.ai/api/generate/submit" \
--header "Authorization: Bearer $VIDGO_API_KEY" \
--header "Content-Type: application/json" \
--data "$REQUEST_BODY")
TASK_ID=$(printf '%s' "$SUBMIT_RESPONSE" | jq -r '.data.task_id // .task_id // empty')
BUSINESS_CODE=$(printf '%s' "$SUBMIT_RESPONSE" | jq -r '.code // empty')
if [ "$BUSINESS_CODE" != "0" ] && [ "$BUSINESS_CODE" != "200" ]; then
printf 'Submit failed:
%s
' "$SUBMIT_RESPONSE" >&2
exit 1
fi
if [ -z "$TASK_ID" ]; then
printf 'Submit response did not include task_id:
%s
' "$SUBMIT_RESPONSE" >&2
exit 1
fi
START_TIME=$(date +%s)
POLL_DELAY=2
while true; do
if [ $(( $(date +%s) - START_TIME )) -ge 600 ]; then
printf 'Timed out after 600 seconds
' >&2
exit 1
fi
STATUS_RESPONSE=$(curl --silent --show-error --fail-with-body \
--url "https://api.vidgo.ai/api/generate/status/$TASK_ID" \
--header "Authorization: Bearer $VIDGO_API_KEY")
STATUS=$(printf '%s' "$STATUS_RESPONSE" | jq -r '.data.status // .status // empty')
BUSINESS_CODE=$(printf '%s' "$STATUS_RESPONSE" | jq -r '.code // empty')
if [ "$BUSINESS_CODE" != "0" ] && [ "$BUSINESS_CODE" != "200" ]; then
printf 'Status request failed:
%s
' "$STATUS_RESPONSE" >&2
exit 1
fi
case "$STATUS" in
finished)
printf '%s' "$STATUS_RESPONSE" | jq -r '(.data.files // .files // [])[]?.file_url'
break
;;
failed)
printf '%s' "$STATUS_RESPONSE" | jq -r '.data.error_message // .error_message // "Generation failed"' >&2
exit 1
;;
not_started|running)
sleep "$POLL_DELAY"
if [ "$POLL_DELAY" -lt 10 ]; then POLL_DELAY=$((POLL_DELAY + 1)); fi
;;
*)
printf 'Unexpected task status: %s
' "$STATUS" >&2
exit 1
;;
esac
doneinput 参数
下表列出 input 对象的可用参数、类型与默认值;请求示例同时展示顶层必填字段 model。按当前任务准备提示词并配置输出规格。
| 字段 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
| prompt | string | 是 | — | minLength 为 1。描述场景、主体运动、摄像机行为及原生音频。 |
| duration | integer | 否 | 5 | 输出视频时长,取值范围为 5–20 秒。 |
| resolution | string | 否 | 720p | 输出分辨率,可选 720p 或 1080p。 |
| aspect_ratio | string | 否 | auto | 输出画幅比例:auto、21:9、2:1、16:9、4:3、1:1、3:4、9:16。 |
| sound | boolean | 否 | true | 是否生成原生同步音频。 |
响应字段
提交成功后返回任务 ID;状态查询提供任务进度、输出文件,以及任务失败时的错误详情。
| 字段 | 类型 | 说明 |
|---|---|---|
| code | integer | 业务结果码;成功响应使用 0 或 200。 |
| message | string | 可读说明或错误详情。 |
| data.task_id | string | 用于状态查询路径的任务 ID。 |
| data.status | string | not_started、running、finished 或 failed。 |
| data.created_time | string | 任务创建时间,date-time 格式。 |
| data.progress | integer | 任务进度,范围为 0–100;仅在响应包含此字段时提供。 |
| data.files[] | array | 成功任务的全部输出文件,按响应顺序返回。 |
| data.files[].file_url | string | 生成视频的公开 URL。 |
| data.files[].file_type | string | 文件类型,例如 video。 |
| data.error_message | string | null | 状态为 failed 时的失败详情。 |
任务生命周期
在 not_started 或 running 状态下继续查询;收到 finished 或 failed 后结束轮询,并分别处理输出文件或错误详情。
not_started任务已接受,等待开始。
running正在生成。继续使用同一 task_id 轮询。
finished生成成功。从 data.files[].file_url 读取视频地址。
failed生成失败。读取 data.error_message 并停止轮询。
轮询与错误
- 认证收到 401 时,检查 Authorization 中的 Bearer API Key,更新凭据后重试。
- 校验收到 400 时,依据响应说明核对必填参数、数值范围与可用积分,调整后重新提交。
- 网络与超时状态查询遇到网络错误或超时时,保留原 task_id 并重试查询,再根据返回的任务状态处理结果。
- 轮询间隔以 2 秒为基准间隔发起状态查询;如任务耗时较长,可逐步增加查询间隔。
- 终态仅在 not_started 或 running 时继续。遇到 finished 或 failed 立即停止。
- 回调选项可在请求顶层提供 callback_url 接收终态任务对象;投递失败时仍可轮询。
模型规格
| 规格 | 取值 | 说明 |
|---|---|---|
| 输入模式 | 纯文本提示词 | 通过自然语言描述场景、运镜与原生声音。 |
| 输出 | 带可选原生音频的视频 | 提交后返回异步任务 ID;sound 开启时含同步音频。 |
| 时长 | 5–20 秒 | 整数取值,默认 5 秒。 |
| 分辨率 | 720p / 1080p | 默认 720p。 |
| 画幅比例 | 8 种比例(含 auto) | auto、21:9、2:1、16:9、4:3、1:1、3:4、9:16,默认 auto。 |
| 计费依据 | 输出秒数 × 分辨率费率 | 720p 为 34 积分/秒,1080p 为 58 积分/秒。 |
相关模型
FLUX 3 Text to Video API 常见问题
FLUX 3 Text to Video API 是什么?
FLUX 3 Text to Video 是 Black Forest Labs 用于纯文本生成视频的模型。它根据文本提示词生成 5–20 秒高保真视频,具备精确物理运动模拟与可选原生同步多轨音频,并支持 720p / 1080p 输出。依托时空生成与视听联合建模,模型在遵循提示词中的运镜与声景设计的同时,保持长镜头中的物理自然度与画面连贯性。你可以通过 API 进行程序化调用,也可以在上方体验区直接在线试用。
FLUX 3 Text to Video 如何控制原生同步音频?
默认 sound 为 true,模型会随画面同步生成对白、动作音效、环境声与配乐。在 prompt 中写明声音线索(例如脚步、回响或配乐方向)可进一步指导声轨;若只要画面,将 sound 设为 false 即可输出无声音频关闭的视频。
FLUX 3 Text to Video 复杂提示词如何遵循 CASTLE 原则?
复杂镜头可按 CASTLE 六要素组织:核心摘要、场景环境、主体描述、动态叙事(含运镜与时序)、音频线索、风格与色彩。先写清整段弧线,再保持主体描述一致,并用具体可见动词描述动作与摄影机运动,有助于稳定呈现多节拍连贯结果。
FLUX 3 Text to Video 在 20 秒时长下如何保持物理稳定性?
模型针对重力、惯性、布料与刚体等物理规律进行了连贯动力学建模。配置接近 20 秒的任务时,在提示词中保持主体动势与运镜方向一致,并按时间顺序写清节拍变化,可在长镜头中维持自然、稳定的物理表现。
FLUX 3 Text to Video 的画幅比例该如何选择?
可选 auto、21:9、2:1、16:9、4:3、1:1、3:4、9:16 共 8 种。投放渠道明确时可直接指定固定画幅;选择 auto 时,模型会根据提示词中的构图与场景描述自动匹配适宜纵横比。完整取值见本页参数说明。
FLUX 3 Text to Video 选择 720p 还是 1080p 更合适?
720p 费率更低,适合创意探索与分镜打样;1080p 纹理与边缘更细腻,适合作为成片素材进入剪辑。两者均按输出秒数计费,时长越长费用越高,可在本页价格说明中对照具体积分。
FLUX 3 Text to Video 如何指导镜头连续性与运镜?
在动态叙事部分写明起始景别、移动方向与结束构图,例如“平视中景跟拍,末段缓慢推近”。单次 5–20 秒适合一段连贯运镜或动作发展;需要更长叙事串联时,可结合本页相关模型中的视频延长或关键帧端点继续编排。















