Vidu Video

Vidu Video creates short video generation tasks. You can generate videos from a text prompt, or provide images as an image-to-video input, start/end frames, or reference images.

After creating a task, the API returns a task ID immediately. Poll the task until it reaches a terminal state. When the task is completed, read the final video URL from metadata.url or download it through the content endpoint.

Endpoints

Capability	Method	Path
Create video task	POST	/v1/videos
Retrieve video task	GET	/v1/videos/{task_id}
Download video content	GET	/v1/videos/{task_id}/content
Unified create endpoint	POST	/v1/video/generations
Unified retrieve endpoint	GET	/v1/video/generations/{task_id}

/v1/videos and /v1/video/generations accept the same request fields. New integrations should prefer /v1/videos.

Supported Models

Model	Description
viduq3-turbo	Speed-oriented model for fast generation and iteration
viduq3	Stronger visual consistency for multi-shot videos
viduq3-mix	Balanced visual quality and motion
viduq2	Recommended for reference-image and subject-consistency workflows

Available models may vary by account access and platform availability.

Supported Modes

Mode	How to call
Text to video	Use prompt without image inputs
Image to video	Use image, images, or input_reference with one image
Start/end frames	Use images with two image URLs
Reference image video	Use images with multiple reference images

Request Parameters

POST /v1/videos
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Parameter	Required	Description
model	Yes	Vidu model name, such as viduq3-turbo, viduq3, viduq3-mix, or viduq2
prompt	Yes	Video prompt describing the subject, motion, scene, camera language, and style
duration	No	Video duration in seconds. You can also use the string field seconds
seconds	No	Duration as a string, such as "5". Use either seconds or duration
size	No	Output spec. Use a resolution such as 720p or 1080p, or an aspect ratio such as 16:9, 9:16, or 1:1
image	No	Single image URL, equivalent to one item in images
images	No	Image URL array. One image is usually image-to-video input; two images can be start/end frames; multiple images can be references
input_reference	No	Single reference image URL, equivalent to a single image input
metadata	No	Vidu-specific extension parameters

Common metadata fields:

Field	Description
resolution	Output resolution, such as 720p or 1080p
aspect_ratio	Output aspect ratio, such as 16:9, 9:16, or 1:1
movement_amplitude	Motion level: auto, small, medium, or large
bgm	Whether to add background music
audio	Whether to generate a video with audio. Actual behavior depends on the selected model
audio_type	Audio type, such as all, speech_only, or sound_effect_only
payload	Custom passthrough string returned with the task result

Image URLs must be publicly reachable. Common supported image formats include jpg, jpeg, png, and webp.

Examples

Text-to-Video

curl -X POST https://cubicspaces.cloud/v1/videos \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "viduq3-turbo",
    "prompt": "A cinematic shot of a glass cube floating above a quiet lake at sunrise, soft reflections, slow camera push in",
    "duration": 5,
    "size": "16:9",
    "metadata": {
      "resolution": "720p",
      "movement_amplitude": "auto"
    }
  }'

Image-to-Video

curl -X POST https://cubicspaces.cloud/v1/videos \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "viduq3",
    "prompt": "Keep the product shape consistent. The camera slowly rotates around the product on a clean studio background.",
    "images": [
      "https://example.com/product.png"
    ],
    "duration": 5,
    "size": "1:1",
    "metadata": {
      "resolution": "720p",
      "movement_amplitude": "small"
    }
  }'

Start/End Frame

When you provide two images, the system treats them as start and end frames. This is useful for transition videos.

curl -X POST https://cubicspaces.cloud/v1/videos \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "viduq2",
    "prompt": "Create a smooth transition from image 1 to image 2, keep lighting natural and motion fluid.",
    "images": [
      "https://example.com/start.png",
      "https://example.com/end.png"
    ],
    "duration": 5,
    "size": "16:9"
  }'

Reference Image

When you provide multiple images, the system treats them as reference assets. This is useful when you need subject consistency.

curl -X POST https://cubicspaces.cloud/v1/videos \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "viduq2",
    "prompt": "Use the subject from the reference images. The character walks through a bright modern gallery, keeping identity and outfit consistent.",
    "images": [
      "https://example.com/ref-1.png",
      "https://example.com/ref-2.png",
      "https://example.com/ref-3.png"
    ],
    "duration": 5,
    "size": "9:16",
    "metadata": {
      "resolution": "720p"
    }
  }'

Response and Retrieval

A successful create request returns a video task object:

{
  "id": "task_xxx",
  "task_id": "task_xxx",
  "object": "video",
  "model": "viduq3-turbo",
  "status": "queued",
  "progress": 0,
  "created_at": 1770000000
}

Save id; use it to retrieve task status and download the generated video.

Retrieve the task:

curl https://cubicspaces.cloud/v1/videos/task_xxx \
  -H "Authorization: Bearer YOUR_API_KEY"

While the task is running, the response usually looks like:

{
  "id": "task_xxx",
  "object": "video",
  "model": "viduq3-turbo",
  "status": "in_progress",
  "progress": 30,
  "created_at": 1770000000
}

When the task is completed:

{
  "id": "task_xxx",
  "object": "video",
  "model": "viduq3-turbo",
  "status": "completed",
  "progress": 100,
  "created_at": 1770000000,
  "completed_at": 1770000600,
  "metadata": {
    "url": "https://example.com/generated-video.mp4"
  }
}

When the task fails, the response has status: "failed" and the reason is in error.message:

{
  "id": "task_xxx",
  "object": "video",
  "model": "viduq3-turbo",
  "status": "failed",
  "progress": 100,
  "created_at": 1770000000,
  "completed_at": 1770000030,
  "error": {
    "code": "task_failed",
    "message": "The video generation task failed."
  }
}

Status Values

Status	Description
queued	Submitted and waiting
in_progress	Generating
completed	Completed
failed	Failed. Check error.message

For long-running tasks, start polling after 1 to 5 minutes, then continue with shorter intervals if the task is still running.

Download Video Content

After the task is completed, you can download or play the content endpoint directly:

curl -L https://cubicspaces.cloud/v1/videos/task_xxx/content \
  -H "Authorization: Bearer YOUR_API_KEY" \
  --output vidu-result.mp4

If the task is not completed yet, the content endpoint returns an error. Check that status is completed first.

Notes

• Prompts should describe the subject, motion, camera, scene, and style. Avoid very short noun-only prompts.
• Image-to-video, start/end frame, and reference-image inputs require publicly reachable image URLs.
• Supported duration, aspect ratio, resolution, and audio behavior can vary by model. If you are unsure, start with duration: 5 and resolution: "720p".
• Result video URLs may expire. Production systems should download or transfer the video soon after completion.