> ## Documentation Index
> Fetch the complete documentation index at: https://apidoc.cometapi.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Create a Vidu video
> Create a Vidu Q3 text-to-video or image-to-video task through CometAPI with POST /v1/videos, then poll the task and download the completed MP4 file.
Use this endpoint to create a Vidu Q3 text-to-video or image-to-video task. The API returns a task ID immediately, so store the returned `id` and poll the task until it reaches a terminal status.
`POST /v1/videos` uses `multipart/form-data`. Send scalar controls as form fields and reference images as `input_reference` file fields.
## Choose an input mode
| Goal | Required fields | Optional fields |
| -------------- | --------------------------------------------- | ----------------- |
| Text-to-video | `model`, `prompt` | `seconds`, `size` |
| Image-to-video | `model`, `prompt`, one `input_reference` file | `seconds`, `size` |
To confirm a Vidu model ID that is available to your API key, use [List available models](/guides/how-to-list-available-models).
## Use reference images
For image-to-video, upload one reference image through the `input_reference` multipart field. The file can be up to 20 MB.
The image guides the composition and appearance of the generated video. Use the prompt to describe motion, camera behavior, and details that the video should preserve.
## Set duration and size
| Model ID | `seconds` | Default |
| -------------- | ---------------- | ----------------------- |
| `viduq3-turbo` | integer `1`-`16` | `5` seconds, `1280x720` |
| `viduq3` | integer `1`-`16` | `5` seconds, `1280x720` |
Set `size` to one of the WxH values below.
| Resolution tier | Aspect ratio | `size` (`WxH`) |
| --------------- | ------------ | -------------- |
| `540p` | `16:9` | `960x528` |
| `720p` | `16:9` | `1280x720` |
| `1080p` | `16:9` | `1920x1080` |
## Task flow
Send the multipart form request and store the returned `id`.
Call [Retrieve a Vidu video](./retrieve) until `status` is `completed`, `failed`, or `error`.
When the task is `completed`, call [Retrieve Vidu video content](./retrieve-content) to download the MP4 file.
## OpenAPI
````yaml api/openapi/video/vidu/post-create.openapi.json POST /v1/videos
openapi: 3.1.0
info:
title: Vidu Video Create API
version: 1.0.0
description: >-
Create an asynchronous Vidu Q3 text-to-video or image-to-video task through
CometAPI. Save the returned id, poll GET /v1/videos/{task_id}, and download
the completed MP4 file.
servers:
- url: https://api.cometapi.com
security:
- bearerAuth: []
paths:
/v1/videos:
post:
summary: Create a Vidu Q3 video task
description: >-
Create a Vidu Q3 text-to-video or image-to-video task. Send fields as
multipart/form-data and upload reference images through input_reference.
operationId: vidu_create_video
requestBody:
required: true
content:
multipart/form-data:
schema:
$ref: '#/components/schemas/ViduCreateRequest'
encoding:
input_reference:
contentType: image/*
examples:
text_to_video:
summary: Text-to-video
value:
model: viduq3-turbo
prompt: >-
An astronaut walks through soft blue fog with a slow
cinematic camera move.
seconds: '1'
image_to_video:
summary: Image-to-video with an uploaded reference image
value:
model: viduq3-turbo
prompt: Animate the uploaded image.
seconds: '5'
size: 1280x720
input_reference: '@reference.png'
responses:
'200':
description: >-
Task created. Store the returned id and poll GET
/v1/videos/{task_id}.
content:
application/json:
schema:
$ref: '#/components/schemas/ViduVideoTask'
example:
id: task_example
task_id: task_example
object: video
model: viduq3-turbo
status: queued
progress: 0
created_at: 1779938152
'400':
description: >-
The request is missing a required field or contains a value that the
selected model cannot use.
'401':
description: The API key is missing or invalid.
security:
- bearerAuth: []
x-codeSamples:
- lang: Shell
label: Text-to-video
source: |-
curl https://api.cometapi.com/v1/videos \
-H "Authorization: Bearer $COMETAPI_KEY" \
-F model=viduq3-turbo \
-F 'prompt=An astronaut walks through soft blue fog with a slow cinematic camera move.' \
-F seconds=1
- lang: Python
label: Text-to-video
source: |
import os
import requests
fields = [
("model", (None, "viduq3-turbo")),
("prompt", (None, "An astronaut walks through soft blue fog with a slow cinematic camera move.")),
("seconds", (None, "1")),
]
response = requests.post(
"https://api.cometapi.com/v1/videos",
headers={"Authorization": "Bearer " + os.environ["COMETAPI_KEY"]},
files=fields,
timeout=120,
)
response.raise_for_status()
print(response.json())
- lang: JavaScript
label: Text-to-video
source: >
const form = new FormData();
form.append("model", "viduq3-turbo");
form.append("prompt", "An astronaut walks through soft blue fog with
a slow cinematic camera move.");
form.append("seconds", "1");
const response = await fetch("https://api.cometapi.com/v1/videos", {
method: "POST",
headers: { Authorization: `Bearer ${process.env.COMETAPI_KEY}` },
body: form,
});
const result = await response.json();
console.log(result);
- lang: Shell
label: Image-to-video
source: |-
curl https://api.cometapi.com/v1/videos \
-H "Authorization: Bearer $COMETAPI_KEY" \
-F 'model=viduq3-turbo' \
-F 'prompt=Animate the uploaded image.' \
-F 'seconds=5' \
-F 'size=1280x720' \
-F 'input_reference=@reference.png;type=image/png'
- lang: Python
label: Image-to-video
source: |
import os
import requests
with open("reference.png", "rb") as reference:
response = requests.post(
"https://api.cometapi.com/v1/videos",
headers={
"Authorization": "Bearer "
+ os.environ["COMETAPI_KEY"]
},
data={
"model": "viduq3-turbo",
"prompt": "Animate the uploaded image.",
"seconds": "5",
"size": "1280x720",
},
files={
"input_reference": (
"reference.png",
reference,
"image/png",
)
},
timeout=120,
)
response.raise_for_status()
print(response.json())
- lang: JavaScript
label: Image-to-video
source: |
import { readFile } from "node:fs/promises";
const reference = await readFile("reference.png");
const form = new FormData();
form.append("model", "viduq3-turbo");
form.append("prompt", "Animate the uploaded image.");
form.append("seconds", "5");
form.append("size", "1280x720");
form.append(
"input_reference",
new Blob([reference], { type: "image/png" }),
"reference.png",
);
const response = await fetch("https://api.cometapi.com/v1/videos", {
method: "POST",
headers: { Authorization: `Bearer ${process.env.COMETAPI_KEY}` },
body: form,
});
const result = await response.json();
console.log(result);
components:
schemas:
ViduCreateRequest:
type: object
required:
- model
- prompt
properties:
model:
type: string
description: >-
Vidu Q3 model ID for this route. Choose an available model from the
Models page.
example: viduq3-turbo
prompt:
type: string
description: >-
Text prompt that describes the video to generate. For
image-to-video, describe the motion and camera behavior that should
animate the reference image.
example: >-
An astronaut walks through soft blue fog with a slow cinematic
camera move.
seconds:
type: string
description: >-
Requested clip duration in seconds. Use an integer from 1 through
16. Default is 5.
example: '1'
size:
type: string
description: >-
Supported WxH size values: 960x528, 1280x720, 1920x1080. Default is
1280x720.
input_reference:
type: string
format: binary
description: >-
One reference image file for image-to-video. Omit this field for
text-to-video. The file can be up to 20 MB. The image guides the
composition and appearance of the generated video.
additionalProperties: false
ViduVideoTask:
type: object
required:
- id
- object
- model
- status
- progress
- created_at
properties:
id:
type: string
description: Task ID. Use this value with retrieve and content endpoints.
example: task_example
task_id:
type: string
description: Compatibility alias for id when present.
example: task_example
object:
type: string
description: Object type. Video tasks return video.
example: video
model:
type: string
description: Model ID used for the task.
example: viduq3-turbo
status:
type: string
description: >-
Task lifecycle status. Poll until the value is completed, failed, or
error.
enum:
- queued
- in_progress
- completed
- failed
- error
example: queued
progress:
type: integer
minimum: 0
maximum: 100
description: Task progress as a coarse percentage.
example: 0
created_at:
type: integer
description: Task creation time as a Unix timestamp in seconds.
example: 1779938152
completed_at:
type: integer
description: >-
Task completion time as a Unix timestamp in seconds. This field
appears on completed tasks.
example: 1779938219
video_url:
type: string
description: Temporary video delivery URL. This field appears on completed tasks.
example:
error:
type: object
description: Failure details. This field appears when the task fails.
additionalProperties: true
additionalProperties: true
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: Bearer authentication. Use your CometAPI API key.
````