Create Reference to Video Task (Subject Call)

POST https://www.kkiai.com/ent/v2/reference2video

Official Documentation: https://platform.vidu.cn/docs/reference-to-video

Request Parameters

Authorization

Add the Authorization parameter to the Header. Its value is the Token concatenated after Bearer.

Example: Authorization: Bearer ********************

Header Parameters

Parameter Name	Type	Required	Description	Example
Authorization	string	Optional		Bearer {{YOUR_API_KEY}}
Content-Type	string	Optional		application/json

Body Parameters (application/json)

Parameter Name	Type	Required	Description
model	string	Required	Model name. Optional values: viduq3-mix, viduq3, viduq2-pro, viduq2, viduq1, vidu2.0. viduq3-mix: Strong visual texture, supports intelligent shot transitions, supports synchronized audio and video output, excellent dynamic effects, strongest balance. viduq3: Supports intelligent shot transitions, supports synchronized audio and video output, better consistency across multiple camera angles. viduq2-pro: Supports reference video, supports video editing, video replacement. viduq2: Good dynamic effects, rich generated details. viduq1: Clear image, smooth transitions, stable camera movement. vidu2.0: Fast generation speed.
auto_subjects	string	Optional	Whether to use intelligent subject library capability. Default is false. Optional values: true, false. true: Use intelligent subject library capability. false: Do not use intelligent subject library capability.
subjects	array[object]	Required	Image subject information. Supports 1-7 subjects. Total of 1-7 subject images.
└ name	string	Required	User-specified subject name (name). Can be used during generation via [@name] format, for example: [@Image1].
└ images	array[string]	Optional	Temporary subject images, maximum 3 images. Note 1: Supports Base64 encoded images or image URLs (ensure accessibility). Note 2: Images support png, jpeg, jpg, webp formats. Note 3: Image pixels cannot be smaller than 128*128, and aspect ratio must be less than 1:4 or 4:1. Note 4: Please note that the HTTP POST body should not exceed 20MB, and encoding must include appropriate content type string, for example: data:image/png;base64,{base64_encode}
└ videos	array[string]	Optional	Temporary subject video, maximum 1 video of 5 seconds. Note 1: Only the reference-to-video viduq2-pro model supports using video subjects. Note 2: Maximum support for uploading 1 video of 5 seconds. Note 3: Videos support mp4, avi, mov formats. Note 4: Video pixels cannot be smaller than 128*128, and aspect ratio must be less than 1:4 or 4:1. Note 5: Please note that the byte length after base64 decoding must be less than 20M, and encoding must include appropriate content type string, for example: data:video/mp4;base64,{base64_encode}
└ voice_id	string	Optional	Voice ID used to determine the voice tone in the video. When empty, the system will automatically recommend. Optional enumeration values refer to the list: New voice list: https://shengshu.feishu.cn/sheets/EgFvs6DShhiEBStmjzccr5gonOg
└ server_id	string	Optional	Subject ID obtained through the Create Subject API. Note: When server_id is not passed, it is a temporary subject and the system will not save it.
prompt	string	Required	Text prompt. Text description for generating the video. Note: Character length cannot exceed 2000 characters.
audio	string	Optional	Whether to use synchronized audio and video output capability. Default is false. Optional values: true, false. true: Use synchronized audio and video output capability. false: Do not use synchronized audio and video output capability. Note: The viduq3 model defaults to true.
duration	number	Optional	Video duration parameter. Default value depends on the model. viduq3: Default 5 seconds, optional: 3 - 16. viduq2-pro, viduq2: Default 5 seconds, optional: 1 - 10. viduq1: Default 5 seconds, optional: 5. vidu2.0: Default 4 seconds, optional: 4.
seed	string	Optional	Random seed. When not passed or passed as 0, a random number will be used instead. Manual setting will use the set seed.
aspect_ratio	string	Optional	Aspect ratio parameter. q2 and q3 models support any ratio or auto. Default 16:9. Optional values: 1:1, 9:16, 16:9, 3:4, 4:3. auto: Automatically recommend based on input image or video.
resolution	string	Optional	Resolution parameter. Default value depends on model and video duration: viduq3 (3-16 seconds): Default 720p, optional: 540p, 720p, 1080p. viduq2-pro, viduq2 (1-10 seconds): Default 720p, optional: 540p, 720p, 1080p. viduq1 (5 seconds): Default 1080p, optional: 1080p. vidu2.0 (4 seconds): Default 360p, optional: 360p, 720p.
movement_amplitude	string	Optional	Movement amplitude. Default auto. Optional values: auto, small, medium, large. Note: This parameter does not take effect when using q2 and q3 series models.
payload	string	Optional	Pass-through parameter. No processing, data transmission only. Note: Maximum 1048576 characters.
watermark	string	Optional	Whether to add watermark. true: Add watermark; false: Do not add watermark. Note 1: Currently the watermark content is fixed, generated by AI, default not added. Note 2: You can query and obtain watermarked video content through the watermarked_url parameter. See the query task interface for details.
wm_position	string	Optional	Watermark position, indicating where the watermark appears in the image. Optional values: 1: Top left. 2: Top right. 3: Bottom right. 4: Bottom left. Default: 3.
wm_url	string	Optional	Watermark content, image URL here. When not passed, use default watermark: content generated by AI.
meta_data	string	Optional	Metadata identifier, JSON format string, pass-through field. You can customize the format or use the example format as follows: { "Label": "your_label","ContentProducer": "yourcontentproducer","ContentPropagator": "your_content_propagator","ProduceID": "yourproductid", "PropagateID": "your_propagate_id","ReservedCode1": "yourreservedcode1", "ReservedCode2": "your_reserved_code2" } When this parameter is empty, the metadata identifier generated by vidu is used by default.
callback_url	string	Optional	Callback protocol. You need to actively set callback_url when creating a task. The request method is POST. When the video generation task status changes, Vidu will send a callback request containing the latest task status to this address. The callback request content structure is consistent with the return body of the query task API. The "status" returned in the callback includes the following states: processing Task is processing. success Task completed (if sending fails, callback three times). failed Task failed (if sending fails, callback three times). Vidu uses a callback signature algorithm for authentication. See: Callback Signature Algorithm for details.

Request Example

{
    "model": "viduq2",
    "subjects": [
        {
            "id": "cat",
            "images": [
                "https://imageproxy.zhongzhuan.chat/api/proxy/image/5d53c7fd4263170634f67ec89db55bec.png"
            ]
        }
    ],
    "prompt": "A cute @cat is running on the grass under bright sunshine, creating a warm and cozy scene."
}

cURL Example

curl --location --request POST 'https://www.kkiai.com/ent/v2/reference2video' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "model": "viduq2",
    "subjects": [
        {
            "id": "cat",
            "images": [
                "https://imageproxy.zhongzhuan.chat/api/proxy/image/5d53c7fd4263170634f67ec89db55bec.png"
            ]
        }
    ],
    "prompt": "A cute @cat is running on the grass under bright sunshine, creating a warm and cozy scene."
}'

Response

🟢 200 Success

Response Body

Parameter Name	Type	Required	Description
task_id	string	Required
type	string	Required
state	string	Required
model	string	Required
style	string	Required
prompt	string	Required
images	array[string]	Required
duration	integer	Required
seed	integer	Required
aspect_ratio	string	Required
resolution	string	Required
movement_amplitude	string	Required
created_at	string	Required
credits	integer	Required
payload	string	Required
cus_priority	integer	Required
off_peak	boolean	Required
watermark	boolean	Required
is_rec	boolean	Required
wm_position	string	Required
wm_url	string	Required
meta_data	string	Required
client_request_id	string	Required

Response Example

{
    "task_id": "911084878697623552",
    "type": "character2video",
    "state": "created",
    "model": "viduq2",
    "style": "general",
    "prompt": "一只可爱的@cat在草地上奔跑，阳光明媚，画面温馨",
    "images": [
        "https://picx.zhimg.com/v2-4911df093b40ee5511938a1ac2a5cdc4_r.jpg"
    ],
    "duration": 5,
    "seed": 1830691647,
    "aspect_ratio": "16:9",
    "resolution": "720p",
    "movement_amplitude": "auto",
    "created_at": "2026-01-20T06:37:57.371761937Z",
    "credits": 45,
    "payload": "",
    "cus_priority": 0,
    "off_peak": false,
    "watermark": false,
    "is_rec": false,
    "wm_position": "unspecified",
    "wm_url": "",
    "meta_data": "",
    "client_request_id": ""
}