API reference/Video generation
Video Generation API
Submit an async video job to /v1/videos, poll its status, then download the MP4. Billing is the per-second price times the duration.
On this pageexpand_more
Quick exampleslink
/v1/videos is an asynchronous job API. The platform reserves the job cost when it accepts the request and returns a job ID; poll that job until completion, then download the finished MP4.
curl https://api.wokey.ai/v1/videos \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Idempotency-Key: video-demo-0001" \
-H "Content-Type: application/json" \
-d '{
"model": "jimeng-seedance-2.0-mini",
"prompt": "A paper boat drifting through a neon-lit rainy street, cinematic tracking shot",
"duration_seconds": 5,
"ratio": "16:9",
"video_resolution": "720p"
}'The request returns 202 and a job ID; download the MP4 from content_url when complete.
Create-job parameterslink
| Parameter | Required | Description |
|---|---|---|
| model | Required | Video model ID, such as jimeng-seedance-2.0-mini. Use the live Video Studio catalog for currently available model, resolution, and duration combinations. |
| prompt | Required | Non-empty video prompt. |
| duration_seconds | Required | Integer duration in seconds. Each model and pricing SKU has its own allowed range. duration is also accepted. |
| ratio | Required | Aspect ratio: 1:1, 3:4, 4:3, 9:16, 16:9, or 21:9. |
| video_resolution | Required | Model-dependent output resolution, currently one of 480p, 720p, 1080p, or 4k. resolution is also accepted. |
| mode | Optional | Defaults to text_to_video. Model-dependent alternatives are image_to_video, first_last_frames, and multimodal_reference. Use multipart/form-data when sending media inputs. |
| image / first_frame / last_frame / video / audio | Conditional | Multipart fields for media modes. image_to_video requires one image; first_last_frames requires one frame in each field; multimodal_reference accepts up to 9 images, 3 videos, and 3 audio files. |
| Idempotency-Key | Recommended | Request header containing 8-160 safe characters. Reuse the same key after a network timeout to avoid duplicate jobs and reservations. |
Job lifecyclelink
Do not keep the create request open while waiting for the video. Persist the job ID and poll at a reasonable interval until status becomes completed, failed, or cancelled.
/v1/videosCreate jobReturns HTTP 202 and object: "video". The initial status is in_progress.
/v1/videos/{id}Get statusReturns job parameters, status, price, error details, and content_url. While queued upstream it also returns queue.position, queue.length, and the suggested next query time next_poll_at.
/v1/videos/{id}/contentDownload videoReturns video/mp4 after completion. Download promptly; files are not retained forever.
/v1/videos?limit=20List jobsLists video jobs for the current account, with limit and before pagination.
/v1/videos/{id}Cancel or deleteCancels a queued job or deletes retained content from a completed job. A job cannot be force-canceled after upstream generation starts.
price_usd is the reserved or settled amount for this job. After completion, content_url points to a download route that requires the same API-key authentication. A null queue means no validated upstream position is currently available; it does not mean the job failed.
Billinglink
Video is priced by model, resolution, and duration: total price = current per-second rate × duration_seconds. The amount is reserved when the job is created and settled on success; a failed job or a job canceled before submission releases the reservation. Current rates and active SKUs are shown live on the API Access page and in Video Studio.
Noteslink
- Video jobs can take several minutes. Persist the job ID and use polling backoff in production.
- Reuse the original Idempotency-Key when retrying a create request. The same key cannot be reused with different parameters.
- Download finished videos promptly. After content is deleted, content_url is no longer available.