Vidu Q4 Image To Video API Documentation
Playground
Try it on WaveSpeedAI!Vidu Q4 Image-to-Video animates a single reference image into high-quality AI video with prompt-guided motion, optional audio, 3-16 second duration, and output resolutions from 540P to 4K for product animation, social content, marketing creatives, cinematic visuals, and production workflows. Ready-to-use REST inference API, best performance, no coldstarts, affordable pricing.
Features
Vidu Q4 Image-to-Video animates a single image into a video of 3 to 16 seconds, up to 4K, with synchronized audio. Describe the motion you want, or leave the prompt out and let the model decide.
Why Choose This?
- Your image as the first frame — The subject, composition and style of the image carry through the clip.
- Sound included — Dialogue, effects and ambience are generated together with the picture, and can be switched off for a silent video.
- Natural camera work — The model can cut between camera positions inside one clip.
- Five resolutions — 540p, 720p, 1080p, 2K and 4K.
- Flexible length — Any whole number of seconds from 3 to 16.
Parameters
| Parameter | Required | Description |
|---|---|---|
| image | Yes | The image to animate: a public URL to a PNG, JPEG or WebP file. |
| prompt | No | What should happen: the action, camera movement and mood. |
| resolution | No | 540p, 720p, 1080p, 2k or 4k. Default: 720p. |
| duration | No | Length in whole seconds, from 3 to 16. Default: 5. |
| generate_audio | No | Generate sound with the video. Default: true. |
| enable_prompt_expansion | No | Let the model rewrite your prompt before generating. Default: false. |
| seed | No | Fix the seed to compare variations. Omit it, or use -1, for a random seed. |
The output keeps the framing of the input image; there is no separate aspect-ratio setting.
How to Use
- Choose an image — Use a sharp image with one clear subject.
- Write a prompt (optional) — Describe the movement and the camera, for example “the astronaut waves and the camera tilts up”.
- Pick resolution and duration — Start at 540p or 720p while you explore, then render the final clip at a higher resolution.
- Run — Submit the request and download the video when it finishes.
Pricing
Pricing is based on the selected resolution and video duration. You pay for each second of video at the rate of the selected resolution, so the price grows with the duration.
| Resolution | Price per second (duration 5 s) | 5-second video (duration 5 s) | 10-second video (duration 10 s) |
|---|---|---|---|
| 540p | $0.045 | $0.225 | $0.45 |
| 720p | $0.095 | $0.475 | $0.95 |
| 1080p | $0.12 | $0.60 | $1.20 |
| 2K | $0.19 | $0.95 | $1.90 |
| 4K | $0.39 | $1.95 | $3.90 |
The duration can be any whole number of seconds from 3 to 16. For example, the shortest clip (duration 3 s) at 720p costs $0.285, and the longest clip (duration 16 s) at 720p costs $1.52. The default settings (720p, 5 seconds) cost $0.475 per run. Audio generation and the other settings do not change the price.
Best Use Cases
- Product animation — Turn a product photo into a short promotional clip.
- Social content — Add motion to stills for posts, reels and campaigns.
- Character animation — Bring portraits, illustrations and character art to life.
- Campaign variations — Produce several video takes from the same key visual.
- Concept testing — Try out motion and camera ideas from a single frame.
Pro Tips
- Describe movement and camera direction; the image already shows what is in the frame.
- Keep the action small enough to finish within the chosen duration.
- Turn on
enable_prompt_expansionfor short prompts, and leave it off when you want the model to follow your wording closely. - Set
generate_audiotofalseif you plan to add your own soundtrack. - A fixed
seedmakes variations easier to compare, but identical output is not guaranteed.
Related Models
- Vidu Q4 Reference-to-Video - Keep characters, products and style consistent from up to 15 reference images, with optional voice references.
Authentication
For authentication details, please refer to the Authentication Guide.
API Endpoints
Submit Task & Query Result
set -euo pipefail
export WAVESPEED_API_KEY="your-api-key"
REQUEST_BODY=$(cat <<'JSON'
{
"prompt": "A cinematic ocean wave at sunrise, highly detailed",
"image": "https://interactive-examples.mdn.mozilla.net/media/cc0-images/painted-hand-298-332.jpg",
"resolution": "720p",
"duration": 5,
"enable_prompt_expansion": false,
"generate_audio": true
}
JSON
)
# 1. Submit the prediction once. Never retry this request automatically:
# a retry after an unclear failure can create a second, billed task.
CHECK='The task may already exist. Check History or the predictions list before submitting again.'
if ! SUBMIT_RESPONSE=$(curl --silent --show-error --fail-with-body \
--connect-timeout 10 --max-time 60 \
-X POST "https://api.wavespeed.ai/api/v3/vidu/q4/image-to-video" \
-H "Authorization: Bearer ${WAVESPEED_API_KEY}" \
-H "Content-Type: application/json" \
-d "${REQUEST_BODY}"); then
printf 'Submit failed. %s\n' "${CHECK}" >&2
exit 1
fi
TASK=$(printf '%s' "${SUBMIT_RESPONSE}" | jq 'if type == "object" and has("data") then .data else . end')
PREDICTION_ID=$(printf '%s' "${TASK}" | jq -r '.id // empty')
if [ -z "${PREDICTION_ID}" ]; then
printf 'Submission response did not contain a prediction id. %s\n' "${CHECK}" >&2
exit 1
fi
RESULT_URL="https://api.wavespeed.ai/api/v3/predictions/${PREDICTION_ID}/result"
# 2. Poll until the prediction reaches a final status.
BODY_FILE=$(mktemp)
trap 'rm -f "${BODY_FILE}"' EXIT
while true; do
# Transient errors (429, 5xx) are retried, honoring Retry-After.
HTTP_CODE=$(curl --silent --show-error --fail-with-body \
--connect-timeout 10 --max-time 60 --retry 5 --retry-delay 2 \
--output "${BODY_FILE}" --write-out '%{http_code}' \
"${RESULT_URL}" \
-H "Authorization: Bearer ${WAVESPEED_API_KEY}" || true)
case "${HTTP_CODE}" in
2??) ;;
000|429|5??) # dropped connection or temporary error: keep polling
printf 'Task %s: HTTP %s, polling again in 10s\n' "${PREDICTION_ID}" "${HTTP_CODE}" >&2
sleep 10; continue ;;
*) printf 'Task %s: HTTP %s\n' "${PREDICTION_ID}" "${HTTP_CODE}" >&2
cat "${BODY_FILE}" >&2; exit 1 ;;
esac
RESULT=$(jq 'if type == "object" and has("data") then .data else . end' "${BODY_FILE}")
STATUS=$(printf '%s' "${RESULT}" | jq -r '.status // empty')
case "${STATUS}" in
completed) printf '%s\n' "${RESULT}" | jq '.outputs'; break ;;
failed|cancelled|timeout|deleted)
printf 'Task %s ended with status %s\n' "${PREDICTION_ID}" "${STATUS}" >&2
printf '%s\n' "${RESULT}" | jq . >&2; exit 1 ;;
*) sleep 2 ;;
esac
doneRetry temporary errors only while polling, never the submit request. Errors, retries and timeouts
Parameters
Task Submission Parameters
Request Parameters
| Parameter | Type | Required | Default | Range | Description |
|---|---|---|---|---|---|
| prompt | string | Yes | - | The positive prompt for the generation. | |
| image | string | Yes | - | The URL of the image to generate an image from. | |
| resolution | string | No | 720p | 540p, 720p, 1080p, 2k, 4k | The resolution of the generated media. |
| duration | integer | No | 5 | 3 ~ 16 | The duration of the generated media in seconds. |
| enable_prompt_expansion | boolean | No | false | - | Whether to enable AI prompt rewriting. |
| generate_audio | boolean | No | true | - | Whether to generate audio. |
| seed | integer | No | - | - | The random seed to use for the generation. -1 means a random seed will be used. |
Every model also accepts the global request options enable_sync_mode and enable_base64_output; see their pages for details.
Response Parameters
| Parameter | Type | Description |
|---|---|---|
| code | integer | HTTP status code (e.g., 200 for success) |
| message | string | Status message (e.g., “success”) |
| data.id | string | Unique identifier for the prediction, Task Id |
| data.model | string | Model ID used for the prediction |
| data.outputs | array | Output values, usually URL strings; some models return text strings or structured result objects (empty when status is not completed) |
| data.urls | object | Object containing related API endpoints |
| data.status | string | Task status. completed is successful; failed, cancelled, timeout, and deleted are failure terminal statuses. |
| data.created_at | string | ISO timestamp of when the request was created (e.g., “2023-04-01T12:34:56.789Z”) |
| data.error | string | Error message (empty if no error occurred) |
| data.timings | object | Object containing timing details |
| data.timings.inference | integer | Inference time in milliseconds |
Result Request Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| id | string | Yes | - | Task ID |
Result Response Parameters
| Parameter | Type | Description |
|---|---|---|
| code | integer | HTTP status code (e.g., 200 for success) |
| message | string | Status message (e.g., “success”) |
| data | object | The prediction data object containing all details |
| data.id | string | Unique identifier for the prediction |
| data.model | string | Model ID used for the prediction |
| data.outputs | array<string | object> | Array of generated outputs (empty when status is not completed). Items are usually URL strings, but may be text strings or structured result objects, depending on the model. |
| data.urls | object | Object containing related API endpoints |
| data.status | string | Status: completed is successful; failed, cancelled, timeout, and deleted are failure terminal statuses |
| data.created_at | string | ISO timestamp of when the request was created |
| data.error | string | Error message (empty if no error occurred) |
| data.timings | object | Object containing timing details |
| data.timings.inference | integer | Inference time in milliseconds |