The subject turns their head slightly toward the camera with a calm expression while a warm breeze gently moves their collar. Preserve the same face, clothing, window light, and background. Camera: locked medium close-up. Native audio: soft outdoor breeze and quiet room tone. No logos, no readable text, no products, no packaging, no prices, no CTA, no advertising, no watermark, no brand marks.
FLUX 3 Image to Video API
blackforestlabs/flux-3/image-to-videoFLUX 3 Image to Video 将 1 张首帧图片与文本提示词转化为 5–20 秒高保真视频,支持逼真物理运动注入、运镜控制与可选原生同步音频。它忠实继承原图主体、服饰细节与光影构图,再按提示词平滑展开动作、镜头与声场。
请上传所需图片。
生成的视频会显示在这里
填写提示词并添加所需素材,确认设置后点击“运行”。
示例
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/image-to-video",
"input": {
"prompt": "The subject turns their head slightly toward the camera with a calm expression while a warm breeze gently moves their collar. Preserve the same face, clothing, window light, and background. Camera: locked medium close-up. Native audio: soft outdoor breeze and quiet room tone. 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": "auto",
"sound": true,
"image_urls": [
"https://cdn.vidgo.ai/apis/models/blackforestlabs/flux-3/image-to-video/v1/01/input-start-frame.webp"
]
}
}
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/image-to-video",
"input": {
"prompt": "The subject turns their head slightly toward the camera with a calm expression while a warm breeze gently moves their collar. Preserve the same face, clothing, window light, and background. Camera: locked medium close-up. Native audio: soft outdoor breeze and quiet room tone. 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": "auto",
"sound": true,
"image_urls": [
"https://cdn.vidgo.ai/apis/models/blackforestlabs/flux-3/image-to-video/v1/01/input-start-frame.webp"
]
}
}
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 | 是 | — | 长度至少 1。指导在首帧基础上的主体动作、运镜、变化与声音。 |
| image_urls | string[] | 是 | — | 包含恰好 1 个可公开访问图片 URL 的数组,作为开场首帧。 |
| 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 | 是否生成原生音频,可选 true 或 false。 |
响应字段
提交成功后返回任务 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 接收终态任务对象;投递失败时仍可轮询。
模型规格
| 规格 | 取值 | 说明 |
|---|---|---|
| 输入模式 | 提示词 + 1 张图 | 提供恰好 1 个首帧图片 URL 与动作提示词。 |
| 输出 | 带可选原生音频的视频 | 提交后返回异步任务 ID。 |
| 时长 | 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 Image to Video
FLUX 3 Image to Video 以单张静帧为视觉起点,结合文本提示词生成连贯动态短片与可选原生音频。模型延续首图中的主体身份、材质质感与环境光照,并支持 5–20 秒时长、8 种画幅比例以及 720p / 1080p 输出。
为什么选择此端点?
静帧驱动的物理运动以首帧主体、光影与构图为基准,平滑注入逼真物理运动,让产品主视觉、人像或场景静帧自然动起来。
原生音画同步生成自动推理并匹配环境音效与动态声场,也可通过 sound 字段开启或关闭原生音频。
主体与构图忠实延续深度解析面部轮廓、服饰纹理与空间布光,在动作演进中持续保持身份与画面结构稳定。
提示词指导动作与运镜用自然语言描述转头、衣物摆动、镜头推进或环绕,让已有画面围绕具体动量展开。
5–20 秒高保真连贯输出单次生成 5 至 20 秒连贯动作,为微表情、产品展示与叙事镜头提供充裕时长。
多画幅与双档清晰度提供含 auto 在内的 8 种画幅比例,以及 720p 与 1080p 分辨率,适配多渠道发布规格。
参数
| 参数 | 要求 | 说明 |
|---|---|---|
| prompt | 必填 | 字符串,长度至少 1。指导在首帧基础上的主体动作、运镜、变化与声音。 |
| image_urls | 必填 | 包含恰好 1 个可公开访问图片 URL 的字符串数组,作为视频开场首帧与视觉基准。 |
| duration | 可选 | 整数。设置输出时长,取值范围为 5–20 秒;体验区默认预选 5 秒。 默认 5 |
| resolution | 可选 | 字符串。设置输出分辨率,可选 720p 或 1080p;体验区默认预选 720p。 默认 720p1080p |
| aspect_ratio | 可选 | 字符串。控制画面比例,支持 auto 及常见横纵比例;体验区默认预选 auto。 默认 auto21:92:116:94:31:13:49:16 |
| sound | 可选 | 布尔值。控制是否生成原生音频;体验区默认预选 true。 默认 truefalse |
如何使用
提供首帧图片 URL准备一张主体与构图清晰、可公开访问的图片地址,填入 image_urls 作为开场基准。
描述动作、运镜与声音在 prompt 中写清从首帧开始的主体动作、镜头运动以及希望呈现的环境声或动作音。
设定视频时长在 5–20 秒之间选择整数时长,默认 5 秒,按主要动作与节奏安排片段长度。
选择分辨率与画幅选择 720p 或 1080p,并指定画幅比例,或保持 auto 以匹配首帧构图。
确认音频开关保持 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 短视频,丰富多平台内容形式。
专业建议
- 选择主体轮廓、光线与构图清晰的首帧,为镜头提供明确的视觉起点。
- 从首帧已有内容继续描述动作,例如“人物抬起手中的杯子,镜头缓慢推进”,明确画面开始后的变化。
- 用一句话点明需要延续的面部、服装或场景特征,再单独写出镜头运动,区分保持内容与动态变化。
- 描述动作动量时写清起止与节奏,例如“缓慢转头后停顿注视镜头”,帮助模型建立连贯物理惯性。
- 围绕可见动作与场景撰写声音线索,例如“Audio: soft outdoor breeze and natural ambient sound”。
使用说明
- FLUX 3 Image to Video 使用 1 张首帧图片与文本提示词生成视频,主要输入为 prompt 和 image_urls;还可设置时长、分辨率、画幅比例与 sound。
- sound 为 true 时,结果包含原生同步音频;也可在提示词中补充环境声或动作音线索。
- API 素材链接使用可公开访问的 HTTP(S) 地址,供服务读取输入文件。
- 通过 API 提交后保存 task_id,用于查询任务进度和获取生成结果。
相关端点
FLUX 3 Image to Video API 常见问题
FLUX 3 Image to Video API 是什么?
FLUX 3 Image to Video 是 Black Forest Labs 的图生视频模型。它以 1 张首帧图片与文本提示词为输入,生成 5–20 秒高保真连贯动作视频,并可输出原生同步音频,自动匹配环境音效与动态声场。模型以静帧主体、光影与构图为基准平滑注入逼真物理运动,忠实继承首图构图、服饰细节与光照。你可以通过 API 进行程序化调用,也可以在上方体验区直接在线试用。
FLUX 3 Image to Video 如何保持静帧角色面部与服装一致性?
模型以首帧图片中的面容结构、服饰纹理与空间布光为视觉锚点。建议使用主体清晰、细节充分的素材,并在提示词中强调需要延续的外观特征,再单独描述转头、抬手等动作,为主体运动提供明确方向。
编写 FLUX 3 Image to Video 提示词时如何描述动作动量?
从首帧已可见的内容继续写动作,标明起止与节奏,例如“缓慢转头后停顿注视镜头,衣领随微风轻动”。再补充镜头推进或环绕等运镜,让物理惯性与画面变化按同一条时间线展开。
FLUX 3 Image to Video 是否会自动生成匹配的环境音?
会。当 sound 为 true 时,模型会根据首帧场景氛围与提示词中的动作线索,自动推理并生成匹配的环境音效与动态声场。也可在提示词末尾补充具体声音描述,例如户外微风或室内环境底噪。
静帧画幅与 FLUX 3 Image to Video 的 aspect_ratio 如何匹配?
将 aspect_ratio 设为 auto 时,系统会依据首帧宽高比输出匹配画幅;若指定 16:9、9:16 等固定比例,模型会在保持主体视觉中心的前提下完成构图适配,便于直接对接目标发布渠道。
FLUX 3 Image to Video 的 sound 字段如何控制原生音频?
sound 默认为 true,生成结果会附带原生同步音频;设为 false 时仅输出画面。开启音频时,可在 prompt 中补充对白、环境声或动作音线索,让声场与可见动作对齐。
需要精确控制结束画面时应如何搭配 FLUX 3 Image to Video?
本端点聚焦从单张首帧向前演进动作与运镜。若需要同时锚定起始与收束构图,可改用 FLUX 3 First Last Frame to Video,传入有序的首尾两帧完成双锚点过渡生成。



