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 turns text prompts into 5–20 second high-fidelity video with physically accurate motion, optional synchronized native audio, and eight framing options. It sustains action and camera continuity across the take while aligning dialogue, effects, and ambient sound with on-screen events.
Input
471/20000
Output
ReadyContinue with
Examples
REST API
Quick Start
Authenticate with the API, submit the prompt and settings, 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 parameters for this endpoint using the request example, then save the returned task_id to query progress and results.
Submit request
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"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/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 parameters
The table lists available input parameters, types, and defaults. Request examples also include the required top-level model field. Prepare the prompt and configure the output.
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
| prompt | string | Yes | — | minLength 1. Describes scene, subject action, camera movement, and native audio. |
| duration | integer | No | 5 | Output duration in seconds from 5 to 20. |
| 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 synchronized audio. |
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 fields, parameter ranges, and available credits, then adjust and resubmit.
- 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 | Text prompt | Natural language instructions for scene, camera, and sound. |
| Output | Video with optional native audio | Returns an asynchronous task ID; sound enabled includes synchronized audio. |
| Duration | 5–20 seconds | Integer range, default 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 | 34 credits/sec for 720p, 58 credits/sec for 1080p. |
Related Models
FLUX 3 Text to Video API frequently asked questions
What is the FLUX 3 Text to Video API?
FLUX 3 Text to Video is a Black Forest Labs model for generating video from text prompts. It creates 5–20 second high-fidelity clips with physically accurate motion and optional synchronized multi-track native audio at 720p or 1080p. Built on spatiotemporal generation with joint audiovisual modeling, it follows camera and sound design in the prompt while sustaining physical naturalness and shot continuity. You can call it programmatically or try it from the playground above.
How does FLUX 3 Text to Video control synchronized native audio?
With sound set to true by default, the model synthesizes dialogue, foley, ambience, and score cues in sync with the picture. Add audio directions in the prompt to guide the soundtrack; set sound to false when you want silent video only.
How should complex FLUX 3 Text to Video prompts follow the CASTLE principle?
Organize complex shots with the CASTLE six-part schema: core summary, scene, subject, dynamic narrative (camera and timing), audio cues, and style & color. Keep the subject description consistent, use concrete visible verbs for action and camera moves, and state the full arc first so multi-beat continuity stays stable.
How does FLUX 3 Text to Video keep physical stability across 20-second shots?
The model is trained for continuous dynamics including gravity, momentum, cloth, and rigid-body interactions. For near-20-second runs, keep subject trajectories and camera direction consistent in the prompt, and sequence beats in time order to maintain natural physics through the take.
Which aspect ratio should I choose for FLUX 3 Text to Video?
Choose among auto, 21:9, 2:1, 16:9, 4:3, 1:1, 3:4, and 9:16. Use a fixed ratio when the delivery channel is known; with auto, framing follows the composition described in the prompt. Full options are listed in the Parameters section on this page.
When should I use 720p versus 1080p with FLUX 3 Text to Video?
720p costs less per second and suits rapid concept iteration; 1080p delivers finer texture and edge detail for final edits. Both are billed by output seconds, so longer clips cost more—see the Pricing section for the exact credit rates.
How do I direct camera continuity in FLUX 3 Text to Video?
In the dynamic narrative, specify starting framing, move direction, and closing composition—for example, “medium tracking shot at eye level, slow push-in at the end.” A single 5–20 second run fits one continuous camera take or action arc; for longer chained storytelling, continue with the Extend Video or Keyframes endpoints listed under Related Models.