Video generation API
How to make video through /videos: start a task, poll it, download the file. Request fields, reference files, drafts and how video is billed.
Video
Video models run as tasks. POST /videos starts one and returns its id straight away; poll GET /videos/{id} every few seconds until status is completed or failed (usually 1 to 5 minutes), then download it: the finished task carries a url (a link to the file, valid for a week and renewed on every read; if we could not store the file, url is the path /v1/videos/{id}/content instead), and GET /videos/{id}/content always fetches the file. The id of any response (chatcmpl-…, img_…, video_…) and the request_id in any error are what to quote to support.
| Field | Type | |
|---|---|---|
model | string | Required. A video model id. |
prompt | string | Required (except with draft_id). 3 to 20,000 characters. |
seconds | integer | "auto" | Length (duration is accepted as the same field). Seedance 2.5: 4 to 30; Seedance 2.0: 4 to 15. "auto" lets the model pick; the longest length is reserved and you pay for what it makes. Default 5; with reference_videos the default is "auto". |
resolution | string | 480p, 720p (default), 1080p or 4k; only resolutions the model offers (see the model reference). |
ratio | string | 16:9 (default), 9:16, 1:1, 4:3, 3:4, 21:9 or adaptive. With reference_videos the default follows the input video. |
image | string | First frame: an image link or data URL (first_frame is accepted as the same field). |
last_frame | string | Last frame, used together with image. |
audio | boolean | Generate sound with the video. Default true. |
seed | integer | -1 for a random seed (the default), or a whole number from 1 to 4294967295 to repeat a result on the same model. The answer shows the seed you sent, or -1 when it was random. |
camera_fixed | boolean | true keeps the camera still. |
bitrate_mode | string | standard (default) or high. high may fail when the model is busy; it is then refunded. |
return_last_frame | boolean | true: the final frame is kept as an image at GET /videos/{id}/last_frame. |
reference_images | string[] | Image links or data URLs: up to 30 on Seedance 2.5, 9 on Seedance 2.0 (jpeg, png, webp, bmp, tiff, gif; up to 30 MB; each side 300 to 6000 px). |
reference_videos | string[] | Public MP4/MOV links: up to 10 on Seedance 2.5, 3 on Seedance 2.0; 2 to 15 s each, 480p or 720p, up to 50 MB. Their length is billed too. |
reference_audios | string[] | Public WAV/MP3 links: up to 10 on Seedance 2.5, 3 on Seedance 2.0; 2 to 15 s each, up to 15 MB. |
task_type | string | With reference_videos: auto, reference, edit or extend (Seedance 2.5). edit and extend follow the input video; leave out seconds and ratio. |
draft | boolean | Seedance 2.5: true makes a 480p preview at the 480p price. resolution must be 480p. |
draft_id | string | Makes a finished draft final at 1080p. Send only model and draft_id: the prompt, references, length, ratio, audio and seed come from the draft. Drafts last 7 days. |
References are numbered per kind in the order you send them: the first entry of reference_images is image 1, the second image 2, and the same for videos and audios. Name them that way in the prompt, as the playground does with [Image 1], [Video 1] and [Audio 1], for example "The woman in [Image 1] walks through the street of [Video 1]". Sending more files than the model takes is refused, not cut.
status is queued, in_progress, completed or failed. A completed task has usage.video_tokens and usage.cost_usd; a failed one is not charged and has error.code and error.message: generation_failed (the model could not make the video), invalid_reference (one of the reference files was refused; the message says which) or timeout.
// GET https://api.apistore.cloud/v1/videos/video_...
{
"id": "video_0123456789abcdef0123456789abcdef",
"object": "video",
"model": "MODEL_NAME",
"status": "completed",
"created_at": 1793984023,
"completed_at": 1793984214,
"prompt": "A red paper boat drifting across a calm lake at sunrise",
"resolution": "720p",
"ratio": "16:9",
"seconds": 5,
"draft": false,
"seed": 49873,
"url": "https://.../video_0123456789abcdef0123456789abcdef.mp4",
"last_frame": null,
"error": null,
"usage": { "video_tokens": 108000, "cost_usd": 1.0978 }
}Drafts (Seedance 2.5): make a cheap 480p preview first, then turn the one you like into the final 1080p video with the same seed and settings.
# 1. the draft: 480p, at the 480p price
curl https://api.apistore.cloud/v1/videos -H "Authorization: Bearer sk-..." -H "Content-Type: application/json" \
-d '{"model": "MODEL_NAME", "prompt": "A red paper boat on a lake", "seconds": 5, "resolution": "480p", "draft": true}'
# 2. when it is completed, the final video at 1080p
curl https://api.apistore.cloud/v1/videos -H "Authorization: Bearer sk-..." -H "Content-Type: application/json" \
-d '{"model": "MODEL_NAME", "draft_id": "video_..."}'The estimated cost is held from your balance when the task starts: (input video seconds + output seconds) of video tokens at the price for that resolution. When it finishes you pay for the tokens actually made (about 108K for 5 seconds at 720p) and the rest is released; a failed task costs nothing. In Settings you can switch video billing from the token price list to "by usd": the supplier's own charge for the job at list price, less your discount. Each billing record says which applied.
Model guides
What each video model family is good at, its limits, and how to write prompts that it follows.
Seedance 2.5
The long-form model: up to 30 seconds in one task, many reference files, and editing or extending an existing video. It writes and speaks 11 languages, Vietnamese and English among them.
| At a glance | |
|---|---|
| Length | 4 to 30 seconds, or "auto" to let the model pick |
| Resolution | 480p, 720p, 1080p |
| Ratio | 21:9, 16:9, 4:3, 1:1, 3:4, 9:16 or adaptive (follows the input) |
| Modes | Text to video; first frame or first and last frame; references; edit a video; extend a video |
| References | Up to 30 images, 10 videos and 10 audios. Audio on its own is accepted |
| Sound | Speech, music and effects are generated with the picture (audio: true) |
| Drafts | Yes: a 480p preview first, then the final video from the one you like |
Writing prompts
- Start with one sentence. Say who, where, what happens, the style and the camera in a single line. Then add the detail below it.
- Bind every reference. Name each file by its number and say what it is for: "[Image 1] is the lead actress, [Image 2] is the cafe, follow the camera of [Video 1]". Do not rely on text written inside a picture to say who someone is.
- Use a timeline for long videos. Split the story into whole-second ranges with no gaps ("0-5 s", "5-12 s") or into numbered shots, and give each one its picture, camera, action, speech and sound. Too little per range and the model improvises; too much and it cuts too often.
- Keep subjects few. One to five subjects hold best. Several views of the same subject are fine as references up to five subjects; beyond that send one view each.
- Editing (task_type: edit). Say what changes and where, from what to what, with the seconds when only part changes: "In [Video 1], from second 4 to 6 she waves instead of nodding; everything else stays". The result keeps the length and ratio of the input, so leave out seconds and ratio. Videos under 20 seconds edit best.
- Extending (task_type: extend). Say the direction and what happens next: "Extend [Video 1] forward: she opens the door and walks into the rain". The ratio follows the input video.
- First and last frame. Send them as image and last_frame, with the same proportions, so the video starts and ends exactly there. A reference image named as "the first frame" in the prompt is followed less strictly.
- Storyboards and keyframes. A storyboard sheet (15 panels or fewer, plain line art, no text) guides the plot but is not followed panel by panel. For strict frames, send separate images and open with "Use Images 1 to 5 in order as keyframes".
- Camera. Ordinary film terms work as written: push in, pan, tracking shot, orbit, handheld, low angle, long take. Explain rare terms in a few words, and say when a transition happens as well as how.
- What to leave out. Write what you want rather than what you do not. The two exceptions that work well: "No subtitles" and "No background music, only ambient sound".
- Speech. Write lines as: name, mood in brackets, then the words. Keep one language per line. For words that must be spelled exactly on screen, send them as an image.
[Image 1] is the fisherman, [Image 2] is his boat. Documentary style, natural light. 0-6 s: wide shot at water level, the boat drifts through morning mist. Slow push in. 6-14 s: medium shot, he pulls the net in, hand over hand. Water drips from the rope. 14-20 s: close-up on his face as he looks at the catch and smiles. Ambient sound only: water, wood, gulls. No subtitles, no background music.
Seedance 2.0
Three models that take the same request and differ in quality, speed and price: Seedance 2.0 for the best picture, Seedance 2.0 fast for a balance of speed and cost, Seedance 2.0 mini for the lowest price.
| At a glance | |
|---|---|
| Length | 4 to 15 seconds, or "auto" |
| Resolution | Seedance 2.0: 480p, 720p, 1080p, 4K. Fast and mini: 480p, 720p |
| Ratio | 21:9, 16:9, 4:3, 1:1, 3:4, 9:16 |
| Modes | Text to video; first frame or first and last frame; references; edit or extend a video through the prompt |
| References | Up to 9 images, 3 videos and 3 audios. Audio needs an image or a video with it |
| Sound | Speech, music and effects are generated with the picture (audio: true) |
| Drafts | No |
| 4K files | H.265 with 10-bit colour. Some players cannot open it; VLC, and current Chrome, Edge and Safari can |
| Faces | Reference images and videos showing a real person's face are refused |
Writing prompts
- The formula. Subject, action, place, light and colour, camera, style, quality, then what to avoid. Settle who does what first, then where, then how it is filmed.
- Define each subject once. Give two or three fixed features (clothes, hair, build) and a label, then use the same label every time: "The girl in the red coat from [Image 1]".
- Write shots, not seconds. Number the shots: "Shot 1: ... Shot 2: ...", each with its camera, action, place and sound. Exact timings such as "0-3 s" are not held reliably on this model.
- One camera move per shot. Push in, or pan, or track. Combining several moves in one shot makes the result unstable.
- Describe movement physically. Name the body part, how far, how fast. Slow and continuous movement works best. Show a feeling through the body ("lowers her head, eyes reddening") rather than naming it.
- Use few references. Four or five are enough: one or two for the character, one for the place, one video for the camera, one audio for the mood. More than four people as references reduces stability, and several views of one person are not recommended.
- Faces that hold. Send a close-up of the head and a full-body picture, and say which is for the face and which for the clothes. Put the most important files first.
- Editing. Name the video directly and say what changes: "Strictly edit [Video 1]: replace the cat with the lion from [Image 1], keep everything else". Do not write "reference [Video 1]" here, or it is treated as a reference only.
- Extending. "Extend [Video 1] forward" or "backward", then what happens. Two or three clips can be joined with a transition between them, 15 seconds in all. Add "end with [Video 1]" to keep the original footage in the result.
- Speech and text. Put spoken lines in braces and keep one language throughout: She says {We are late}. For text on screen give the words, when, where and how they appear. Use common characters.
- What to avoid. Subtitles and logos can still appear. "Keep it subtitle-free" and "Do not generate a logo or watermark" reduce them; so does removing text from your reference files.
[Image 1] is the girl in the red coat, [Image 2] is the night market. Follow the camera of [Video 1].
Shot 1: wide shot, she walks in between the stalls. Slow push in.
Shot 2: medium shot, she stops at a lantern stall and lifts one lantern. Fixed camera.
Shot 3: close-up, warm light on her face. She says {This one}.
Cinematic, warm tones, rich detail. Keep it subtitle-free. Do not generate a logo or watermark.