Kling - Video Generation API documentation

Text-to-video

Supported models: kling/kling-v3-turbo-video-generation, kling/kling-v3-video-generation, and kling/kling-v3-omni-video-generation.

# The URL below is for the China (Beijing) region. Replace {WorkspaceId} with your actual workspace ID.
curl --location 'https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis' \
    -H 'X-DashScope-Async: enable' \
    -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
    -H 'Content-Type: application/json' \
    -d '{
    "model": "kling/kling-v3-turbo-video-generation",
    "input": {
        "prompt": "A kitten runs under the moonlight"
    },
    "parameters": {
        "mode": "std",
        "aspect_ratio": "16:9",
        "duration": 5,
        "audio": false,
        "watermark": true
    }
}'

Python SDK

from http import HTTPStatus
from dashscope import VideoSynthesis
import dashscope
import os

# If you have not configured environment variables, replace the following line with your API Key: api_key="sk-xxx"
# Get API Key: https://help.aliyun.com/en/model-studio/get-api-key
api_key = os.getenv("DASHSCOPE_API_KEY")

def sample_async_call():
    # Submit video generation task asynchronously
    rsp = VideoSynthesis.async_call(api_key=api_key,
                                model='kling/kling-v3-turbo-video-generation',
                                prompt='A kitten runs under the moonlight',
                                mode='std',
                                aspect_ratio='16:9',
                                duration=5,
                                audio=False,
                                watermark=True)
    print(rsp)
    if rsp.status_code == HTTPStatus.OK:
        print("task_id: %s" % rsp.output.task_id)
    else:
        print('Failed, status_code: %s, code: %s, message: %s' %
              (rsp.status_code, rsp.code, rsp.message))

    # Query task status
    status = VideoSynthesis.fetch(task=rsp, api_key=api_key)
    if status.status_code == HTTPStatus.OK:
        print(status.output.task_status)
    else:
        print('Failed, status_code: %s, code: %s, message: %s' %
              (status.status_code, status.code, status.message))

    # Wait for task to complete
    rsp = VideoSynthesis.wait(task=rsp, api_key=api_key)
    print(rsp)
    if rsp.status_code == HTTPStatus.OK:
        print(rsp.output.video_url)
    else:
        print('Failed, status_code: %s, code: %s, message: %s' %
              (rsp.status_code, rsp.code, rsp.message))

if __name__ == '__main__':
    sample_async_call()

Text-to-video (custom shot division)

Supported models: kling/kling-v3-turbo-video-generation, kling/kling-v3-video-generation, and kling/kling-v3-omni-video-generation.

# The URL below is for the China (Beijing) region. Replace {WorkspaceId} with your actual workspace ID.
curl --location 'https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis' \
    -H 'X-DashScope-Async: enable' \
    -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
    -H 'Content-Type: application/json' \
    -d '{
    "model": "kling/kling-v3-video-generation",
    "input": {
        "prompt": "",
        "multi_shot": true,
        "shot_type": "customize",
        "multi_prompt": [
            {
                "index": 1,
                "prompt": "Wuling Town is smaller than it appears on the map. Mountain mist, like cotton fluff, blocks the street entrance. Behind the post office, there are indeed three locust trees. The soil by the roots of the third tree has been disturbed.",
                "duration": 5
            },
            {
                "index": 2,
                "prompt": "Lin Che squats down and digs up an iron box. Inside, besides a rusty key, is an old cassette tape. The tape recorder was borrowed from the post office. When the play button is pressed, his father's voice emerges from the static: 'If you are hearing this, it means you have walked the path I once walked.'",
                "duration": 5
            }
        ],
        "media": [],
        "element_list": []
    },
    "parameters": {
        "mode": "pro",
        "duration": 10,
        "audio": true,
        "aspect_ratio": "9:16",
        "watermark": true
    }
}'

Image-to-video (from a first frame)

Supported models: kling/kling-v3-turbo-video-generation, kling/kling-v3-video-generation, and kling/kling-v3-omni-video-generation.

# The URL below is for the China (Beijing) region. Replace {WorkspaceId} with your actual workspace ID.
curl --location 'https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis' \
    -H 'X-DashScope-Async: enable' \
    -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
    -H 'Content-Type: application/json' \
    -d '{
    "model": "kling/kling-v3-omni-video-generation",
    "input": {
        "prompt": "Animate the person in the picture, with their hair blowing in a gentle breeze",
        "media": [
            {
                "type": "first_frame",
                "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260121/zlpocv/wan-i2v-haigui.webp"
            }
        ]
    },
    "parameters": {
        "mode": "std",
        "duration": 5,
        "audio": false,
        "watermark": true
    }
}'

Image-to-video (from first and last frames)

Supported models: kling/kling-v3-video-generation and kling/kling-v3-omni-video-generation.

# The URL below is for the China (Beijing) region. Replace {WorkspaceId} with your actual workspace ID.
curl --location 'https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis' \
    -H 'X-DashScope-Async: enable' \
    -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
    -H 'Content-Type: application/json' \
    -d '{
    "model": "kling/kling-v3-omni-video-generation",
    "input": {
        "prompt": "Realistic style, a small black cat looks up at the sky curiously. The camera starts at eye level, gradually rises, and ends with a top-down shot of its curious eyes.",
        "media": [
            {
                "type": "first_frame",
                "url": "https://wanx.alicdn.com/material/20250318/first_frame.png"
            },
          {
                "type": "last_frame",
                "url": "https://wanx.alicdn.com/material/20250318/last_frame.png"
            }
        ]
    },
    "parameters": {
        "mode": "std",
        "duration": 5,
        "audio": false,
        "watermark": true
    }
}'

Video editing

Supported model: kling/kling-v3-omni-video-generation.

# The URL below is for the China (Beijing) region. Replace {WorkspaceId} with your actual workspace ID.
curl --location 'https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis' \
    -H 'X-DashScope-Async: enable' \
    -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
    -H 'Content-Type: application/json' \
    -d '{
    "model": "kling/kling-v3-omni-video-generation",
    "input": {
        "prompt": "<<<element_1>>> background, <<<image_2>>> and <<<image_1>>> shake hands and talk, <<<video_1>>> a detective in a black trench coat stands on the roof of an apartment building, observing the street with binoculars",
        "multi_shot": false,
        "shot_type": "intelligence",
        "multi_prompt": [],
        "media": [
            {
                "url": "https://p2-kling.klingai.com/kcdn/cdn-kcdn112452/kling-qa-test/lip_sync_5s.mp4",
                "type": "base",
                "keep_original_sound": "yes"
            },
            {
                "type": "refer",
                "url": "https://p2-kling.klingai.com/kcdn/cdn-kcdn112452/kling-qa-test/zem_test/yangmi01.jpg"
            },
            {
                "type": "refer",
                "url": "https://p2-kling.klingai.com/kcdn/cdn-kcdn112452/kling-qa-test/human_2.JPG"
            }
        ],
        "element_list": [
            {
                "element_id": 171
            }
        ]
    },
    "parameters": {
        "mode": "pro",
        "duration": 10,
        "audio": false,
        "aspect_ratio": "1:1",
        "watermark": true
    }
}'

Successful response

Save the task_id to query the task status and result.

{
    "output": {
        "task_status": "PENDING",
        "task_id": "0385dc79-5ff8-4d82-bcb6-xxxxxx"
    },
    "request_id": "4909100c-7b5a-9f92-bfe5-xxxxxx"
}

Error response

Task creation failed. See Error codes.

{
    "code": "InvalidApiKey",
    "message": "Invalid API-key provided.",
    "request_id": "7438d53d-6eb8-4596-8835-xxxxxx"
}

Query task result

Replace {task_id} with the task_id value returned by the previous API call. The task_id is valid for queries for 24 hours, Replace {WorkspaceId} with your actual workspace ID.

curl -X GET https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/tasks/{task_id} \
--header "Authorization: Bearer $DASHSCOPE_API_KEY"

Task successful

{
    "request_id": "340f0d7d-bf7e-4c8f-9c03-xxxxxx",
    "output": {
        "task_id": "24f5c51e-d67b-44dc-9acb-xxxxxx",
        "task_status": "SUCCEEDED",
        "submit_time": "2026-03-27 21:30:32.575",
        "scheduled_time": "2026-03-27 21:30:32.603",
        "end_time": "2026-03-27 21:31:09.177",
        "video_url": "https://v4-fdl.kechuangai.com/ksc2/xxx.mp4?xxxx",
        "watermark_video_url": "https://v2-fdl.kechuangai.com/ksc2/xxx.mp4?xxxx"
    },
    "usage": {
        "duration": 5,
        "size": "1280*720",
        "fps": 24,
        "video_count": 1,
        "audio": false,
        "SR": "720"
    }
}

Task failed

When a task fails, task_status is FAILED with an error code and message. See Error codes.

{
    "request_id": "e5d70b02-ebd3-98ce-9fe8-759d7d7b107d",
    "output": {
        "task_id": "86ecf553-d340-4e21-af6e-a0c6a421c010",
        "task_status": "FAILED",
        "code": "InvalidParameter",
        "message": "The parameter is invalid xxxxxx"
    }
}

Task query expired

The task_id is valid for 24 hours. After this period, queries return the following error.

{
    "request_id": "a4de7c32-7057-9f82-8581-xxxxxx",
    "output": {
        "task_id": "502a00b1-19d9-4839-a82f-xxxxxx",
        "task_status": "UNKNOWN"
    }
}