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 turns one start image and a text prompt into 5–20 seconds of high-fidelity video, with realistic physical motion, camera control, and optional synchronized native audio. It faithfully preserves the source subject, clothing detail, and lighting composition while smoothly expanding action, camera moves, and soundscape from your prompt.
Input
152/20000
Upload the required image.
Output
IdleYour generated video will appear here
Add your prompt and required media, review the settings, then click Run.
Continue with
Examples
REST API
Quick Start
Authenticate with the API, submit the start image and instructions, then retrieve the video using the task ID.
01
Connect to the Vidgo API
Create an API key, keep it only on your server, and send Authorization: Bearer VIDGO_API_KEY.
- Endpoint
- POST
https://api.vidgo.ai/api/generate/submit - Authentication
- Authorization: Bearer VIDGO_API_KEY
02
Submit one generation task
Fill in the inputs and settings for this endpoint using the request example, then save the returned task_id to query generation progress and results.
Submit request
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"03
Wait for the result
Query with task_id, continue for not_started/running, and stop for finished/failed. On success, read data.files[].file_url.
Track status
GET https://api.vidgo.ai/api/generate/status/{task_id}Poll status with a 2-second base interval, and increase the interval for longer tasks. Continue only while status is not_started or running, and stop once finished or failed. You can also specify callback_url in the request payload to receive webhook notifications.
not_startedrunningfinishedfailedSubmit response
{
"code": 200,
"data": {
"task_id": "task-unified-...",
"status": "running",
"created_time": "2026-09-16T10:00:00Z"
}
}Finished response
{
"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
}
}Complete runnable example
Expand for a complete script with HTTP and business-code checks, task_id validation, polling, terminal-state handling, and a timeout boundary.
Complete runnable example
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 parameters
The table lists available input parameters, types, and defaults. Request examples also include the required top-level model field. Prepare the start image and configure the output.
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
| prompt | string | Yes | — | Minimum length 1. Directs subject action, camera movement, visual change, and sound after the start frame. |
| image_urls | string[] | Yes | — | Array containing exactly one publicly accessible image URL as the opening frame. |
| duration | integer | No | 5 | Output video duration from 5–20 seconds. |
| resolution | string | No | 720p | Output resolution: 720p or 1080p. |
| aspect_ratio | string | No | auto | Framing ratio: auto, 21:9, 2:1, 16:9, 4:3, 1:1, 3:4, or 9:16. |
| sound | boolean | No | true | Whether to generate native audio: true or false. |
Response Fields
A successful submission returns a task ID. Status queries provide progress, output files, and error details when a task fails.
| Field | Type | Description |
|---|---|---|
| code | integer | Application result code; successful responses use 0 or 200. |
| message | string | Human-readable message or error detail when present. |
| data.task_id | string | Task ID used in the status endpoint path. |
| data.status | string | not_started, running, finished, or failed. |
| data.created_time | string | Task creation time in date-time format. |
| data.progress | integer | Task progress from 0 to 100, when included in the response. |
| data.files[] | array | All output files from a successful task, in response order. |
| data.files[].file_url | string | Public URL for a generated video. |
| data.files[].file_type | string | File type, such as video. |
| data.error_message | string | null | Failure detail when status is failed. |
Task Lifecycle
Continue querying while the status is not_started or running. End polling at finished or failed, then process the output files or error details respectively.
not_startedThe task was accepted and is waiting to begin.
runningGeneration is in progress. Continue polling the same task_id.
finishedGeneration succeeded. Read every video URL from data.files[].file_url.
failedGeneration stopped with an error. Read data.error_message and stop polling.
Polling and Errors
- AuthenticationFor a 401 response, check the Bearer API key in Authorization, update the credentials, and retry.
- ValidationFor a 400 response, use the response details to check required inputs, parameter values, and available credits, then make the indicated adjustments before submitting again.
- Network and timeoutIf a status query encounters a network error or timeout, retain the original task_id and retry the query, then handle the result according to the returned task status.
- Polling intervalPoll status with a 2-second base interval, and gradually increase the interval for longer tasks.
- Terminal statesContinue only for not_started or running. Stop immediately on finished or failed.
- Callback optionProvide callback_url at the request top level to receive the final flat task object; polling remains available if delivery fails.
Endpoint limits
| Specification | Value | Details |
|---|---|---|
| Input mode | Prompt + 1 image | Exactly one start image URL and a motion prompt. |
| Output | Video with optional native audio | The endpoint returns an asynchronous task ID. |
| Duration | 5–20 seconds | Integer range; default is 5 seconds. |
| Resolution | 720p / 1080p | Default is 720p. |
| Aspect ratio | 8 options (including auto) | auto, 21:9, 2:1, 16:9, 4:3, 1:1, 3:4, 9:16; default auto. |
| Billing basis | Output seconds × resolution rate | 720p: 34 credits/sec; 1080p: 58 credits/sec. |
Related Endpoints
FLUX 3 Image to Video API frequently asked questions
What is the FLUX 3 Image to Video API?
FLUX 3 Image to Video is a Black Forest Labs image-to-video model. It takes one start image and a text prompt to generate 5–20 seconds of high-fidelity continuous action video, with optional synchronized native audio that automatically matches ambient effects and dynamic soundscapes. Anchored on the still’s subject, lighting, and composition, it smoothly injects realistic physical motion while faithfully preserving the opening frame’s framing, clothing detail, and illumination. You can call it programmatically or try it from the playground above.
How does FLUX 3 Image to Video keep facial and clothing consistency from a still?
The model anchors facial structure, wardrobe texture, and spatial lighting from the start image. Use a clear, detailed source still, emphasize appearance traits to carry forward in the prompt, then separately describe actions such as a head turn or raised hand to guide motion without rewriting identity.
How should I describe action momentum in a FLUX 3 Image to Video prompt?
Continue from what is already visible in the frame and state start, finish, and pacing—for example, “slowly turns, then holds a gaze toward camera as a breeze moves the collar.” Add camera push-ins or orbits so physical inertia and framing change share one timeline.
Does FLUX 3 Image to Video automatically generate matching ambient audio?
Yes. When sound is true, the model infers ambient effects and dynamic soundscapes from the start-frame setting and action cues in the prompt. You can also append specific sound notes at the end of the prompt, such as outdoor breeze or room tone.
How should a still’s framing match FLUX 3 Image to Video aspect_ratio?
Set aspect_ratio to auto to follow the start image’s width-to-height ratio. Choosing a fixed ratio such as 16:9 or 9:16 adapts the composition while keeping the subject centered for your target publishing format.
How does the sound field control native audio in FLUX 3 Image to Video?
sound defaults to true and includes synchronized native audio in the result; set it to false for picture-only output. With audio enabled, add dialogue, ambient, or action-sound cues in the prompt so the soundtrack aligns with visible motion.
When should I pair FLUX 3 Image to Video with end-frame control?
This endpoint focuses on evolving action and camera from a single opening still. If you need to anchor both the start and closing compositions, use FLUX 3 First Last Frame to Video with two ordered frames for dual-anchor transition generation.