One continuous five-second shot at blue hour on a quiet covered train platform. A fictional adult woman in a mustard raincoat stands alone near a bench. A brief gust lifts the loose end of her red scarf; she turns once, catches it against her chest, then becomes still. The camera makes one slow, steady waist-height move from a medium-wide view to a medium view. Keep her face, coat, scarf, and body proportions consistent. Use natural weight shift, restrained cloth motion, and realistic light rain. Synchronized audio: soft rain on the canopy, one cloth snap, and distant rail ambience. No cuts, no extra people, no dialogue, no readable text, no logos, no products, no advertising, no watermark.
Seedance 2.5 Text-to-Video API
bytedance/seedance-2.5/text-to-videoSeedance 2.5 (Text-to-Video) generates audio-synchronized videos up to 30 seconds long from text prompts, with controls for subject action, camera movement, lighting, pacing, and sound. It turns detailed scene descriptions into continuous visual sequences while adding expressive motion, dialogue, ambience, music, and sound effects in a single generation.
Input
699/20000
Output
IdleYour generated video will appear here
Configure the required inputs, resolution, and duration, then run the task.
Continue with
Examples
REST API
Quick Start
Authenticate, submit a valid input object, then use task_id to retrieve the video.
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
Run the smallest valid payload for this workflow. A successful submission immediately returns task_id without waiting for the video.
Submit request
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 '{
"model": "seedance-2.5/text-to-video",
"input": {
"prompt": "A tracking shot follows a tram through a rain-lit street.",
"duration": 5,
"resolution": "720p",
"aspect_ratio": "auto",
"generate_audio": true
}
}')
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 about every 2 seconds, then back off gradually. Continue only for not_started or running and stop on finished or failed. You can instead add callback_url to the same top-level request contract.
not_startedrunningfinishedfailedSubmit response
{
"code": 200,
"data": {
"task_id": "task-unified-...",
"status": "running",
"created_time": "2026-08-22T10: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": "seedance-2.5/text-to-video",
"input": {
"prompt": "A tracking shot follows a tram through a rain-lit street.",
"duration": 5,
"resolution": "720p",
"aspect_ratio": "auto",
"generate_audio": 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
These are the fields accepted inside input. The request example shows the required top-level model field.
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
| prompt | string | Yes | — | 1–20,000 characters after trimming. |
| duration | integer | Yes | — | An integer from 4 through 30, inclusive. |
| resolution | string | Yes | — | Send 480p or 720p explicitly. |
| aspect_ratio | string | No | — | auto, 21:9, 16:9, 4:3, 1:1, 3:4, or 9:16. |
| generate_audio | boolean | No | — | Whether to request an audio track; the playground always sends true or false. |
Response Fields
Submission returns task identity immediately. Status responses add progress, every output file, or a failure message.
| 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 | 0–100 progress when reported by the provider. |
| 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
Treat not_started and running as non-terminal states. finished and failed are terminal alternatives; stop polling when either is returned.
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
- AuthenticationA 401 response means the Bearer API key is missing or invalid. Correct it before retrying.
- ValidationA 400 response identifies an invalid field, unsupported media key, or insufficient credit balance. Correct the request before resubmitting.
- Network and timeoutA transport failure is different from a failed task. Retry status checks with a bounded timeout before deciding that the task failed.
- Polling intervalStart around every 2 seconds and increase the interval gradually for a long-running task.
- 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 only | A prompt defines the scene, action, camera direction, and sound intent. |
| Output | Video task | The endpoint returns an asynchronous task ID. |
| Resolution | 480p / 720p | resolution is required and sent explicitly. |
| Duration | 4–30 seconds | Every integer value in the inclusive range is valid. |
| Aspect ratio | Auto + 6 fixed | auto, 21:9, 16:9, 4:3, 1:1, 3:4, or 9:16. |
| Billing basis | Output seconds | 480p uses 28 credits/s; 720p uses 63 credits/s. |
Seedance 2.5 Text-to-Video
Seedance 2.5 Text-to-Video turns a text prompt into a continuous scene with synchronized sound. Use the prompt to define the subject and setting, sequence actions over time, and direct camera movement, lighting, pacing, and audio so the generated video follows one coherent creative plan.
Why Choose This?
Start without source mediaBuild the subject, setting, action, and visual treatment directly from a written scene.
Sequence action across the shotDescribe a clear opening, progression, and final beat to guide how the scene develops over time.
Direct performance and camera separatelyDefine what the subject does, then control shot size, angle, movement, and pace as a second layer.
Compose for the delivery formatSelect adaptive, landscape, portrait, or square framing before describing composition and negative space.
Plan picture and sound togetherEnable generated audio when dialogue, ambience, action sounds, or music cues belong to the scene.
Parameters
| Parameter | Requirement | Description |
|---|---|---|
| prompt | Required | String. Defines the scene, action, camera, visual treatment, and sound intent; 1–20,000 characters after trimming. |
| duration | Required | Integer. Sets output length from 4 through 30 seconds, inclusive; the Playground preselects 5 seconds. |
| resolution | Required | String. Sets output resolution and must be sent explicitly; the Playground preselects 720p. 720p480p |
| aspect_ratio | Optional | String. Controls output framing; the Playground preselects and explicitly sends auto. auto16:99:161:121:94:33:4 |
| generate_audio | Optional | Boolean. Requests a generated audio track; the Playground preselects true and explicitly sends either value. truefalse |
How to Use
Define the sceneOpen with the subject, setting, and visual premise: a courier crossing a neon-lit station at night.
Stage the actionWrite concrete beats in order: she checks the platform, boards the train, then looks back as the doors close.
Direct the cameraAdd shot size, angle, and movement separately: medium tracking shot, eye level, slow push-in at the final beat.
Establish the look and soundFinish with lighting, palette, atmosphere, and audio intent that should remain consistent across the clip.
Configure the outputSet the duration, resolution, aspect ratio, and audio control after the creative direction is clear.
Generate and reviewRun the request, inspect the video and audio together, then refine the prompt when timing, framing, or scene relationships need another pass.
Pricing
Price depends only on output duration and resolution; the audio toggle does not change the rate.
| Usage | Rate | Details |
|---|---|---|
| 480p | 28 credits/output sec ($0.140/sec) | 4 seconds costs 112 credits ($0.560), 5 seconds costs 140 credits ($0.700), and 30 seconds costs 840 credits ($4.20). |
| 720p | 63 credits/output sec ($0.315/sec) | 4 seconds costs 252 credits ($1.26), 5 seconds costs 315 credits ($1.58), and 30 seconds costs 1,890 credits ($9.45). |
Best Use Cases
Campaign concept filmsTurn a written product scenario and camera plan into a concept clip for creative review before production.
Story and scene previsualizationConvert a scripted beat into a motion reference for reviewing pacing, staging, and shot direction.
Social campaign variationsDevelop a written campaign idea into vertical, square, or landscape video concepts for channel-specific review.
Music and atmosphere studiesTranslate a visual progression, lighting direction, and sound cues into a short mood film or music visual study.
Pro Tips
- Use this prompt spine: subject and setting, ordered action, camera direction, lighting and atmosphere, then intended sound.
- Replace a thin prompt such as 'a cyclist in the city' with a visible action: the cyclist turns into a rain-lit alley as the camera tracks beside the rear wheel.
- Use time ranges or words such as first, then, and finally when several beats need a clear sequence.
- Keep subject movement and camera movement in separate sentences so each instruction has a clear role.
- Give a short clip one coherent visual idea instead of asking it to resolve several unrelated scenes.
Notes
- Generation is asynchronous; retain task_id and stop tracking when the task reaches finished or failed.
Related Models
Seedance 2.5 Text To Video API — Frequently asked questions
What is the Seedance 2.5 Text-to-Video API?
Seedance 2.5 is developed by ByteDance Seed. The Text-to-Video API turns a text prompt into an asynchronously generated video. It can also generate a synchronized audio track when requested.
How do I call the Seedance 2.5 Text-to-Video API?
Send POST /api/generate/submit with a Bearer API key, set model to seedance-2.5/text-to-video, and place every generation field inside input. A successful submission returns task_id immediately; the API tab and linked documentation include runnable examples.
Open the complete API documentationHow much does the Seedance 2.5 Text-to-Video API cost?
480p costs 28 credits/output second and 720p costs 63. For example, 5 seconds costs 140 credits ($0.700) at 480p or 315 credits ($1.58) at 720p.
What inputs does the Seedance 2.5 Text-to-Video API accept?
The input object accepts a 1–20,000 character prompt, a whole-second duration from 4 to 30, 480p or 720p resolution, optional aspect_ratio, and generate_audio.
How do I get the generated video?
Poll GET /api/generate/status/{task_id} with task_id. On finished, read data.files[].file_url; on failed, stop and read the error. You can also provide callback_url for the terminal result.
Which Seedance 2.5 endpoint should I choose?
Choose Text-to-Video when the scene starts from language alone. Use Image-to-Video for a required start frame and optional end frame, or Reference-to-Video when separate assets need appearance, motion, camera, or sound roles.