# VIDU Q2 Template to Video - Documentation

> For the complete documentation index, see [llms.txt](/llms.txt). Markdown is available with `Accept: text/markdown` and `.md` URL variants.

Source: /docs/api-reference/model-apis-vidu-q2-template2video

# VIDU Q2 Template to Video

POST

/

v3

/

async

/

vidu-q2-template2video

VIDU Q2 Template to Video

cURL

```
curl --request POST \
--url https://api.novita.ai/v3/async/vidu-q2-template2video \
--header 'Authorization: <authorization>' \
--header 'Content-Type: <content-type>' \
--data '
{
"bgm": true,
"area": "<string>",
"seed": 123,
"beast": "<string>",
"images": [
"<string>"
],
"prompt": "<string>",
"wm_url": "<string>",
"payload": "<string>",
"template": "<string>",
"meta_data": "<string>",
"watermark": true,
"wm_position": 123,
"aspect_ratio": "<string>"
}
'
```

```
import requestsurl = "https://api.novita.ai/v3/async/vidu-q2-template2video"payload = { "bgm": True, "area": "<string>", "seed": 123, "beast": "<string>", "images": ["<string>"], "prompt": "<string>", "wm_url": "<string>", "payload": "<string>", "template": "<string>", "meta_data": "<string>", "watermark": True, "wm_position": 123, "aspect_ratio": "<string>"}headers = { "Content-Type": "<content-type>", "Authorization": "<authorization>"}response = requests.post(url, json=payload, headers=headers)print(response.text)
```

```
const options = { method: 'POST', headers: {'Content-Type': '<content-type>', Authorization: '<authorization>'}, body: JSON.stringify({ bgm: true, area: '<string>', seed: 123, beast: '<string>', images: ['<string>'], prompt: '<string>', wm_url: '<string>', payload: '<string>', template: '<string>', meta_data: '<string>', watermark: true, wm_position: 123, aspect_ratio: '<string>' })};fetch('https://api.novita.ai/v3/async/vidu-q2-template2video', options) .then(res => res.json()) .then(res => console.log(res)) .catch(err => console.error(err));
```

```
<?php$curl = curl_init();curl_setopt_array($curl, [ CURLOPT_URL => "https://api.novita.ai/v3/async/vidu-q2-template2video", CURLOPT_RETURNTRANSFER => true, CURLOPT_ENCODING => "", CURLOPT_MAXREDIRS => 10, CURLOPT_TIMEOUT => 30, CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1, CURLOPT_CUSTOMREQUEST => "POST", CURLOPT_POSTFIELDS => json_encode([ 'bgm' => true, 'area' => '<string>', 'seed' => 123, 'beast' => '<string>', 'images' => [ '<string>' ], 'prompt' => '<string>', 'wm_url' => '<string>', 'payload' => '<string>', 'template' => '<string>', 'meta_data' => '<string>', 'watermark' => true, 'wm_position' => 123, 'aspect_ratio' => '<string>' ]), CURLOPT_HTTPHEADER => [ "Authorization: <authorization>", "Content-Type: <content-type>" ],]);$response = curl_exec($curl);$err = curl_error($curl);curl_close($curl);if ($err) { echo "cURL Error #:" . $err;} else { echo $response;}
```

```
package mainimport (	"fmt"	"strings"	"net/http"	"io")func main() {	url := "https://api.novita.ai/v3/async/vidu-q2-template2video"	payload := strings.NewReader("{\n \"bgm\": true,\n \"area\": \"<string>\",\n \"seed\": 123,\n \"beast\": \"<string>\",\n \"images\": [\n \"<string>\"\n ],\n \"prompt\": \"<string>\",\n \"wm_url\": \"<string>\",\n \"payload\": \"<string>\",\n \"template\": \"<string>\",\n \"meta_data\": \"<string>\",\n \"watermark\": true,\n \"wm_position\": 123,\n \"aspect_ratio\": \"<string>\"\n}")	req, _ := http.NewRequest("POST", url, payload)	req.Header.Add("Content-Type", "<content-type>")	req.Header.Add("Authorization", "<authorization>")	res, _ := http.DefaultClient.Do(req)	defer res.Body.Close()	body, _ := io.ReadAll(res.Body)	fmt.Println(string(body))}
```

```
HttpResponse<String> response = Unirest.post("https://api.novita.ai/v3/async/vidu-q2-template2video") .header("Content-Type", "<content-type>") .header("Authorization", "<authorization>") .body("{\n \"bgm\": true,\n \"area\": \"<string>\",\n \"seed\": 123,\n \"beast\": \"<string>\",\n \"images\": [\n \"<string>\"\n ],\n \"prompt\": \"<string>\",\n \"wm_url\": \"<string>\",\n \"payload\": \"<string>\",\n \"template\": \"<string>\",\n \"meta_data\": \"<string>\",\n \"watermark\": true,\n \"wm_position\": 123,\n \"aspect_ratio\": \"<string>\"\n}") .asString();
```

```
require 'uri'require 'net/http'url = URI("https://api.novita.ai/v3/async/vidu-q2-template2video")http = Net::HTTP.new(url.host, url.port)http.use_ssl = truerequest = Net::HTTP::Post.new(url)request["Content-Type"] = '<content-type>'request["Authorization"] = '<authorization>'request.body = "{\n \"bgm\": true,\n \"area\": \"<string>\",\n \"seed\": 123,\n \"beast\": \"<string>\",\n \"images\": [\n \"<string>\"\n ],\n \"prompt\": \"<string>\",\n \"wm_url\": \"<string>\",\n \"payload\": \"<string>\",\n \"template\": \"<string>\",\n \"meta_data\": \"<string>\",\n \"watermark\": true,\n \"wm_position\": 123,\n \"aspect_ratio\": \"<string>\"\n}"response = http.request(request)puts response.read_body
```

200

```
{
"task_id": "<string>",
"provider_request_id": "<string>"
}
```

VIDU Q2 template to video API, supports various effect scene templates, generates effect video content based on templates and input images.

This is an asynchronous API; only the task_id will be returned. You should use the task_id to request the [Task Result API](/docs/api-reference/model-apis-task-result) to retrieve the video generation results.

##

[​](#request-headers)

Request Headers

[​](#param-content-type)

Content-Type

string

required

Supports: `application/json`

[​](#param-authorization)

Authorization

string

required

Bearer authentication format, for example: Bearer {{API Key}}.

##

[​](#request-body)

Request Body

[​](#param-bgm)

bgm

boolean

default:false

Whether to add background music to the generated video. Default: false. When true, the system will automatically select appropriate music from the preset BGM library and add it; when not passed or false, no BGM is added. BGM duration is unlimited, the system automatically adapts to video duration

[​](#param-area)

area

string

default:"auto"

Exotic princess effect exclusive parameter. Only available when template is exotic_princess. Default: autoOptional values: `auto`, `denmark`, `uk`, `africa`, `china`, `mexico`, `switzerland`, `russia`, `italy`, `korea`, `thailand`, `india`, `japan`

[​](#param-seed)

seed

integer

default:0

Random seed. When not passed or passed as 0, a random number will be used instead; manually set to use the specified seed

[​](#param-beast)

beast

string

default:"auto"

Beast companion effect exclusive parameter. Only available when template is beast_companion. Default: autoOptional values: `auto`, `bear`, `tiger`, `elk`, `snake`, `lion`, `wolf`

[​](#param-images)

images

string[]

required

Input image list. The model will generate video based on the images passed in this parameter. Supports image Base64 encoding or image URL (ensure accessibility). Supports png, jpeg, jpg, webp formats. Image aspect ratio must be less than 1:4 or 4:1, size not exceeding 50MB. Base64 decoded byte length must be less than 10M, and encoding must include appropriate content type string, e.g.: data:image/png;base64,Array length: 1 - unlimited

[​](#param-prompt)

prompt

string

Text prompt, text description for generating video. Note: When template=subject_3 or pubg_winner_hit, prompt is not required

[​](#param-wm-url)

wm_url

string

Watermark content, image URL. When not passed, default watermark is used: content generated by AI

[​](#param-payload)

payload

string

Passthrough parameter, no processing, data transmission only. Maximum 1048576 charactersLength limit: 0 - 1048576

[​](#param-template)

template

string

required

Scene template parameter. Different scene templates correspond to different call parameters. Common templates: subject_3 (character costume change), pubg_winner_hit (PUBG effect), exotic_princess (exotic princess), beast_companion (beast companion), etc. Please refer to [https://platform.vidu.cn/docs/templates](https://platform.vidu.cn/docs/templates) for details

[​](#param-meta-data)

meta_data

string

Metadata identifier, JSON format string, passthrough field. You can customize the format or use the example format. When this parameter is empty, the metadata identifier generated by vidu is used by default. Example format:

```
{
"Label": "your_label",
"ContentProducer": "your_content_producer",
"ContentPropagator": "your_content_propagator",
"ProduceID": "your_product_id",
"PropagateID": "your_propagate_id",
"ReservedCode1": "your_reserved_code1",
"ReservedCode2": "your_reserved_code2"
}
```

[​](#param-watermark)

watermark

boolean

default:false

Whether to add watermark. true: add watermark; false: do not add watermark. Currently watermark content is fixed, content generated by AI, not added by default. You can query watermarked video content via watermarked_url parameter

[​](#param-wm-position)

wm_position

integer

default:3

Watermark position, indicates where the watermark appears in the image. 1: top-left; 2: top-right; 3: bottom-right; 4: bottom-left. Default is 3Optional values: `1`, `2`, `3`, `4`

[​](#param-aspect-ratio)

aspect_ratio

string

default:"16:9"

Video aspect ratio. Default 16:9, options: 16:9, 9:16. Different templates support different options, see template description for detailsOptional values: `16:9`, `9:16`

##

[​](#response)

Response

[​](#param-task-id)

task_id

string

required

Use the task_id to request the [Task Result API](/docs/api-reference/model-apis-task-result) to retrieve the generated outputs.

[​](#param-provider-request-id)

provider_request_id

string

Provider request ID (optional)

Last modified on July 3, 2026