Create Image-to-Video Task

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

Official documentation: https://platform.vidu.cn/docs/image-to-video

Request Parameters

Authorization

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

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

Header Parameters

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

Body Parameters (application/json)

Parameter	Type	Required	Description
model	string	Required	Model name. Optional values: viduq2, viduq1, viduq3-turbo, viduq3-pro. viduq3-turbo: Compared to viduq3-pro, generates videos faster. viduq3-pro: Efficiently generates high-quality audio and video content, making videos more dynamic, vivid, and three-dimensional with better results. viduq2: Latest model. viduq1: Clear picture quality, smooth transitions, stable camera movement.
images	array[string]	Required	First frame image. The model will use the image passed in this parameter as the first frame to generate the video. Note 1: Supports Base64 encoded images or image URLs (ensure accessibility). Note 2: Only supports 1 image input. Note 3: Supports png, jpeg, jpg, webp formats. Note 4: Image aspect ratio must be less than 1:4 or 4:1. Note 5: Image size must not exceed 50 MB. Note 6: Please note that the HTTP POST body must not exceed 20MB, and the encoding must include an appropriate content type string, for example: data:image/png;base64,{base64_encode}
prompt	string	Required	Text prompt. Text description for video generation. Note: Character length must not exceed 2000 characters.
audio	string	Optional	Whether to use audio and video direct output capability. Default is false. Enum values: false: No audio and video direct output, output silent video. true: Audio and video direct output enabled, output video with dialogue and background music. Note 1: The voice_id parameter only takes effect when this parameter is true. Note 2: When model is q3-pro or q3-turbo, this parameter defaults to true. Note 3: Off-peak mode is not supported when this parameter is true.
voice_id	string	Optional	Voice ID. Used to determine the voice tone in the video. When empty, the system will automatically recommend. Optional enum values refer to the list: New voice list: https://shengshu.feishu.cn/sheets/EgFvs6DShhiEBStmjzccr5gonOg
is_rec	string	Optional	Whether to use recommended prompts. true: Yes, the system automatically recommends prompts and uses the recommended prompt content to generate videos. Number of recommended prompts = 1. false: No, generate videos based on the input prompt. Note: Enabling recommended prompts will consume an additional 10 credits per task.
duration	number	Optional	Video duration parameter. Default value depends on the model: viduq3-pro, viduq3-turbo default is 5, optional: 1-16. viduq2: default 5 seconds, optional: 1-10. viduq1: default 5 seconds, optional: 5.
seed	string	Optional	Random seed. When not passed or passed as 0, a random number will be used. When manually set, the specified seed will be used.
resolution	string	Optional	Resolution parameter. Default value depends on the model and video duration: viduq3-pro, viduq3-turbo 1-16 seconds: default 720p, optional: 540p, 720p, 1080p. viduq2 (1-10 seconds): default 720p, optional: 540p, 720p, 1080p. viduq1 (5 seconds): default 1080p, optional: 1080p.
movement_amplitude	string	Optional	Motion amplitude. Default is auto. Optional values: auto, small, medium, large. Note: This parameter does not take effect when using the q2 model.
payload	string	Optional	Pass-through parameter. No processing is performed, only data transmission. Note: Maximum 1048576 characters.
off_peak	string	Optional	Off-peak mode. Default is false. Optional values: true: Generate video in off-peak mode. false: Generate video immediately. Note 1: Off-peak mode consumes fewer credits. Please check product pricing for details. Note 2: Tasks submitted in off-peak mode will be generated within 48 hours. Tasks that cannot be completed will be automatically cancelled and credits will be refunded. Note 3: You can also manually cancel off-peak tasks.
watermark	string	Optional	Whether to add watermark. true: Add watermark. false: Do not add watermark. Note 1: Currently the watermark content is fixed and generated by AI. Default is not added. Note 2: You can query and obtain watermarked video content through the watermarked_url parameter. See the query task API for details.
wm_position	string	Optional	Watermark position. Indicates where the watermark appears in the image. Optional values: 1: Top left. 2: Top right. 3: Bottom right. 4: Bottom left. Default is 3.
wm_url	string	Optional	Watermark content. This is an image URL. When not passed, the default watermark is used: 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-pro",
    "images": [
        "https://imageproxy.zhongzhuan.chat/api/proxy/image/6fb238cc01649cb7580fbb2dd58f3d6d.png"
    ],
    "prompt": "The camera slowly pushes in to reveal the details of the scene, while the background gradually blurs.",
    "duration": 2,
    "resolution": "1080p",
    "aspect_ratio": "16:9",
    "seed": 12345,
    "movement_amplitude": "standard",
    "bgm": false,
    "audio": false,
    "off_peak": false,
    "watermark": false,
    // "payload": "custom-tracking-id-123",
    // "client_request_id": "unique-request-id-456"
}

cURL Example

curl --location --request POST 'https://www.kkiai.com/ent/v2/img2video' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "model": "viduq2-pro",
    "images": [
        "https://imageproxy.zhongzhuan.chat/api/proxy/image/6fb238cc01649cb7580fbb2dd58f3d6d.png"
    ],
    "prompt": "The camera slowly pushes in to reveal the details of the scene, while the background gradually blurs.",
    "duration": 2,
    "resolution": "1080p",
    "aspect_ratio": "16:9",
    "seed": 12345,
    "movement_amplitude": "standard",
    "bgm": false,
    "audio": false,
    "off_peak": false,
    "watermark": false,
    // "payload": "custom-tracking-id-123",
    // "client_request_id": "unique-request-id-456"
}'

Response

🟢 200 Success

Response Body

Parameter	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
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": "911045603801182208",
    "type": "img2video",
    "state": "created",
    "model": "viduq1",
    "style": "general",
    "prompt": "镜头缓慢推进，展现画面中的细节，背景逐渐虚化",
    "images": [
        "https://storage.xuanxu.net/images/1997560136907759618/1768223244152.png"
    ],
    "duration": 5,
    "seed": 12345,
    "aspect_ratio": "",
    "resolution": "1080p",
    "movement_amplitude": "auto",
    "created_at": "2026-01-20T04:01:53.504648743Z",
    "credits": 80,
    "payload": "custom-tracking-id-123",
    "cus_priority": 0,
    "off_peak": false,
    "watermark": false,
    "is_rec": false,
    "wm_position": "unspecified",
    "wm_url": "",
    "meta_data": "",
    "client_request_id": ""
}