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
FLUX 3 Text to Video 仅凭文本提示词即可生成具备电影质感的动态视频与同步原生音频。依托精确的物理运动模拟,模型支持 5–20 秒连续动态、8 种画幅比例及 720p / 1080p 输出,适合专业叙事与高质量视频制作。
为什么选择此端点?
精确物理运动模拟自然呈现流体波动、布料摆动、复杂肢体动作与光线在不同材质上的反射变化,让运动符合真实世界规律。
原生同步多轨音频随画面同步生成对白、动作音效、环境声与配乐,并通过 sound 参数独立开启或关闭音频生成。
5–20 秒长时长连贯生成单次任务支持 5 至 20 秒连续视频,在较长时段内稳定保持镜头动量与物理一致性。
8 种画幅智能适配支持从 21:9 宽银幕到 9:16 竖屏的 8 档比例,并提供 auto 智能画幅自适应,契合多平台发布。
深度运镜与时间线遵循准确理解推拉、摇移、环绕等运镜指令及分阶段时序变化,让复杂镜头调度按提示词展开。
720p 与 1080p 清晰度档位提供 720p 与 1080p 两种高清分辨率,兼顾快速创意验证与高质量成片交付。
参数
| 参数 | 要求 | 说明 |
|---|---|---|
| prompt | 必填 | 字符串,minLength 为 1。指导场景、主体动作、镜头运动与原生音频。 |
| duration | 可选 | 整数。设置输出时长,取值范围为 5–20 秒;体验区默认预选 5 秒。 默认 5 |
| resolution | 可选 | 字符串。设置输出分辨率;体验区默认预选 720p。 默认 720p1080p |
| aspect_ratio | 可选 | 字符串。控制画面比例;体验区默认预选 auto。 默认 auto21:92:116:94:31:13:49:16 |
| sound | 可选 | 布尔值。控制是否随视频生成原生同步音频;体验区默认预选 true。 默认 truefalse |
如何使用
编写场景提示词在 prompt 中写清主体动作、环境光影、运镜方式以及希望呈现的原生声音,构建完整镜头意图。
设置视频时长根据叙事节奏在 5 到 20 秒之间指定输出时长,默认 5 秒。
选择输出分辨率按成片清晰度需求选择 720p 或 1080p,默认 720p。
设定画面比例选择 16:9、9:16、21:9 或 auto 等 8 种画幅之一,匹配投放平台版式。
确认音频开关保持 sound 为 true 生成带同步音效的短片,或设为 false 输出无声纯视频。
确认费用并运行查看运行按钮显示的当前配置费用,完成提示词与参数设置后点击“运行”。
预览并下载视频任务完成后,在输出面板预览画面与声音,点击“下载视频”保存结果。
价格
按输出视频秒数与分辨率阶梯计费,原生同步音频包含在生成结果中。1 积分 = $0.005。
| 用量 | 费率 | 说明 |
|---|---|---|
| 720p | 34 积分/秒($0.17/秒) | 默认 5 秒 720p 为 170 积分($0.85)。 |
| 1080p | 58 积分/秒($0.29/秒) | 5 秒 1080p 为 290 积分($1.45)。 |
适用场景
电影级镜头概念预演用详尽的运镜与光影描述直接生成动态视效样片,快速验证导演构想与分镜节奏。
数字广告与品牌视频结合产品特性与环境声景生成富有视觉张力的宣传短片,提升跨平台创意产出效率。
短视频与社交叙事使用 9:16 比例与情节描述,生成带同步对白和音效的高品质竖屏内容。
自然风光与环境动态展现流动水面、飞扬风沙等自然景观,并伴随真实风声、雨声等环境音。
视听氛围镜头围绕雨夜街道、室内暖光等场景描述画面与声音,制作片头或过渡氛围片段。
专业建议
- 按 CASTLE 结构组织复杂提示:核心摘要、场景、主体、动态叙事、音频、风格与色彩,让各部分职责清晰。
- 如需特定音效,在提示词中加入明确声音描述,例如“Native audio: 缓慢脚步声与沉稳大提琴低音”。
- 描述运镜时指定具体摄影机运动,例如“平稳缓慢向前推镜”,帮助建立稳定空间透视。
- 单一核心动作建议选择 5–8 秒;需要展开多节拍情节时可选择 10–20 秒。
- 选择 auto 画幅时,模型会结合提示词中的构图描述自动匹配适宜纵横比。
使用说明
- FLUX 3 Text to Video 以纯文本 prompt 驱动生成,可配置 duration、resolution、aspect_ratio 与 sound。
- sound 为 true 时,输出包含与画面事件同步的对白、音效、环境声或配乐。
- 通过 API 提交后保存返回的 task_id,用于查询任务进度并获取最终文件链接。
- 生成结果为标准视频文件,可在主流播放器与剪辑软件中直接使用。
相关模型
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 秒适合一段连贯运镜或动作发展;需要更长叙事串联时,可结合本页相关模型中的视频延长或关键帧端点继续编排。



