tencent cloud

Video Generation Models

Download
Focus Mode
Font Size
Last updated: 2026-11-17 14:27:53
AI-Translated & Reviewed

Overview

CMR Video API generates videos asynchronously based on text prompts and optional image and video materials, and is suitable for scenarios such as marketing content creation, short video production, and video editing. You only need to use the unified API and CMR API Key to call video generation models from different vendors. Video generation is an asynchronous task: first call the creation API to submit a task and obtain a task ID, then poll the task status through the query API, and after the task is completed, obtain the video download address from the response. Use the following APIs for related operations:
POST /v1/videos — Create a video generation task
GET /v1/videos/{video_id} — Query a single task
GET /v1/videos — Query the task list
DELETE /v1/videos/{video_id} — Cancel a task

Prerequisites

1. It is recommended to read Usage Constraints and Supported Model Providers in advance for relevant information.
2. A CMR instance has been created. For detailed instructions, see Creating a CMR Instance.
3. A BYOK instance has been created. For detailed instructions, see Creating a BYOK Instance.
4. A CMR API key has been created. For detailed instructions, see Creating a CMR API Key.
5. Video generation model association and CMR policy configuration have been completed. For detailed instructions, see Configuring Model Scheduling Management.

API Endpoint and Authentication

Request URL

POST {CMR_BASE_URL}/v1/videos
GET {CMR_BASE_URL}/v1/videos/{video_id}
GET {CMR_BASE_URL}/v1/videos
DELETE {CMR_BASE_URL}/v1/videos/{video_id}
CMR_BASE_URL is the instance access address displayed in the console. Use the CMR model name and CMR API Key for requests. You do not need to provide the vendor's API address or API Key.

Request Header

Header
Required
Description
Authorization
Yes
Bearer <CMR_API_KEY>
Content-Type
Yes
Fixed as application/json

Quick Start

Replace the access address, API Key, and model name in the example with your own configuration.

cURL

# ① Create a task
curl --request POST "${CMR_BASE_URL}/v1/videos" \\
--header "Authorization: Bearer ${CMR_API_KEY}" \\
--header "Content-Type: application/json" \\
--data '{
"model": "kling-v3",
"contents": [
{ "type": "text", "text": "An orange kitten on the windowsill looks at the camera, with sunlight falling on its fur" }
],
"duration": 5,
"resolution": "1080p",
"aspect_ratio": "16:9"
}'
# → {"id":"video_abc123","error":null}

# ② Poll the task status until the status is completed or failed
curl --request GET "${CMR_BASE_URL}/v1/videos/video_abc123" \\
--header "Authorization: Bearer ${CMR_API_KEY}"

# ③ After status=completed, obtain the video from outputs[0].url and download and transfer it as soon as possible

Python

import os
import time
import requests

base_url = os.environ["CMR_BASE_URL"]
headers = {
"Authorization": f"Bearer {os.environ['CMR_API_KEY']}",
"Content-Type": "application/json",
}

# ① Create a task
resp = requests.post(
f"{base_url}/v1/videos",
headers=headers,
json={
"model": "kling-v3",
"contents": [
{"type": "text", "text": "An orange kitten on the windowsill looks at the camera, with sunlight falling on its fur"}
],
"duration": 5,
"resolution": "1080p",
"aspect_ratio": "16:9",
},
timeout=30,
)
resp.raise_for_status()
video_id = resp.json()["id"]

# ② Poll the task status (recommended interval: 5 seconds or more)
while True:
task = requests.get(
f"{base_url}/v1/videos/{video_id}",
headers=headers,
timeout=30,
).json()
if task["status"] in ("completed", "failed", "expired"):
break
time.sleep(5)

# ③ Obtain the result
if task["status"] == "completed":
print(task["outputs"][0]["url"]) # Video URL. Download and transfer it as soon as possible.
else:
print(task["error"])

Creating a Task

POST /v1/videos

Request Parameters

Parameter
Type
Required
Description
model
string
Yes
CMR model name. Available values are subject to the console.
contents
array
Yes
Material array. See Material Structure. Must contain at least one type=text prompt.
task_type
string
No
Task type: text_to_video (text-to-video), image_to_video (image-to-video), video_reference (video reference). If not specified, the task type is automatically inferred based on the materials; if explicitly specified, it must match the materials.
duration
integer | "auto"
No
Video duration, in seconds. "auto" indicates that the model selects the duration automatically (supported only by some models).
resolution
string
No
Resolution levels: 480p, 540p, 720p, 768p, 1080p, 2k, 4k
aspect_ratio
string
No
Aspect ratio: 16:9, 9:16, 1:1, 4:3, 3:4, 21:9, 2:3, 3:2
audio
string
No
Audio settings: native (audio is included when the video is generated), original (retains the original audio of the reference video, which requires including video material in contents), none (default, no audio). Whether the selected model supports audio depends on the model. If audio is not supported, the video is processed as silent or a corresponding error is returned.
seed
integer
No
Random seed, used for result reproduction (subject to model support).
watermark
boolean
No
Whether to add a watermark. Default value: false (subject to model support).
negative_prompt
string
No
Negative prompt, which describes content that is not expected to appear (subject to model support).
Parameter Values and Model Capabilities: Whether values of parameters such as duration, resolution, and aspect_ratio are supported by the selected model is validated by the model. If an unsupported value is passed, the request returns an error with the error message from the model for easier troubleshooting. Whether an optional parameter takes effect depends on the selected model, and CMR does not automatically fill default values for unspecified optional parameters.

Material Structure

Each item in the contents array is a material object:
Type
Format
Description
Text
{"type":"text","text":"..."}
Prompt, the only entry. At least one per task.
Figure
{"type":"image","role":"first_frame" | "last_frame" | "reference","url":"...","id":"..."}
url supports public URLs or Data URIs; role indicates the purpose (first frame/last frame/reference image); id is an optional reference anchor for prompts to reference materials, and must be unique within the same task.
Video
{"type":"video","role":"base" | "feature","url":"...","id":"..."}
Only public URLs are supported; base is the main video to be edited, and feature is the reference video.
Subject
{"type":"element","element_id":"..."}
Preset subject asset ID on the vendor side (supported by model)
Matching Materials with Task Types:
Task type
contents Composition
Description
Text-to-video text_to_video
Text only
Passing an image or video returns 400.
Image-to-video image_to_video
Text + image ≥1
First frame, last frame, or reference image can be used. At least one image is required.
Video reference video_reference
Text + video ≥1 + optional image
Generate a new video using the video as a reference.
Format Constraints: Images support jpg, jpeg, png, and webp formats, with a size less than or equal to 50 MB and a short side greater than or equal to 300 px. Videos support mp4 and mov formats, and the duration limit is determined by the selected model. first_frame+last_frame materials cannot be mixed with reference materials. base videos cannot be mixed with feature videos.

Request Example

Image-to-video (with specified first frame):
{
"model": "kling-v3",
"contents": [
{ "type": "text", "text": "Make the subject in the frame turn their head naturally, with a breeze blowing through their hair" },
{ "type": "image", "role": "first_frame", "url": "https://example.com/start.jpg" }
],
"duration": 5,
"resolution": "1080p",
"aspect_ratio": "16:9"
}
Video-to-video:
{
"model": "kling-3.0-omni",
"contents": [
{ "type": "text", "text": "Make the subject in the frame turn their head naturally" },
{ "type": "video", "role": "feature", "url": "https://example.com/clip.mp4" }
]
}

Response Parameters

Parameter
Type
Returned or Not
Description
id
string
Yes
Task ID, the unique handle for subsequent queries and cancellation
error
object | null
Yes
On success, it is always null; on failure, a unified error format is returned.

Response Example

{
"id": "video_abc123",
"error": null
}
The creation API processes requests asynchronously. The returned id only indicates that the task has been accepted and queued, not that generation has succeeded. Obtain the final result through the query API.

Provider Custom Parameters

Parameter conversion is enabled by default for a CMR instance, and vendor-defined parameters are passed through by default. Place parameters in the request as required by the vendor. You do not need to configure allowlisting for each parameter. If parameter filtering rules are configured for the instance, parameters are processed according to those rules.
For example, if the selected model supports return_last_frame (returns the last frame image for multi-segment video continuation), you can make the request as follows:
{
"model": "doubao-seedance-2-5",
"contents": [{ "type": "text", "text": "In a café in the early morning, a cup of coffee is steaming" }],
"return_last_frame": true
}
To set default values, modify parameter values, or filter fields, you can configure rules in the parameter conversion settings of the target CMR instance. When configuring through the management API, use CreateParamTranslationConfig to save and TestParamTranslationConfig to preview. For Video rules, set the endpoint to video. For configuration methods and examples, see the parameter protocol conversion documentation. The names, tiers, and values of custom parameters are subject to the vendor documentation. After changing the model or vendor, confirm that these parameters still apply.

Querying a Task

GET /v1/videos/{video_id}
The path parameter video_id is the task ID returned at creation.

Response Parameters

Basic fields:
Parameter
Type
Returned or Not
Description
id
string
Yes
Task ID
object
string
Yes
Fixed to video
status
string
Yes
Task status. See Task status.
created_at
integer
Yes
Task creation time, Unix timestamp in seconds
completed_at
integer | null
Yes
Time when the task reaches a final state; null if not in a final state.
model
string
Yes
Model name in the creation request
error
object | null
Yes
Reason for task failure; null for success and in-progress states.
outputs
array
No
Generated outputs, returned only when status=completed.
usage
object
No
Usage information, returned only in final states.
Task failure: If the query API itself fails (for example, the task does not exist or you do not have permission), a unified error format is returned. Task generation failure is a task attribute rather than a request failure -- the query still returns HTTP 200, and the failure reason is in the error field.
Outputs outputs[] (currently, each task returns one video):
Parameter
Type
Returned or Not
Description
outputs[].url
string
Yes
Video download URL (temporary URL; save it as soon as possible)
outputs[].cover_url
string | null
Yes
Cover image URL; null if not provided by the model.
outputs[].watermark_url
string | null
Yes
Watermarked version URL; null if not provided by the model.
outputs[].last_frame_url
string | null
Yes
Last frame image URL (for multi-segment relay); null if not requested or not supported by the model.
Usage usage (returned in the final state; null while in progress):
Parameter
Type
Returned or Not
Description
usage.seconds
integer
Yes
Actual generation duration, in seconds.
usage.width / usage.height
integer | null
Yes
Video pixel width and height; null if it cannot be determined.
usage.fps
integer | null
Yes
Frame rate; null if not provided by the model.
usage.tokens
integer | null
Yes
Usage for token-based billing models; null for second-based billing models.
usage.billing
array | null
Yes
Official billing details returned by some models (amount, resource package deduction, and others), serving as the reconciliation basis; null if not provided by the model.
CMR returns only the usage fields actually provided by the model. Missing items are null instead of padded with 0.

Response Example

{
"id": "video_abc123",
"object": "video",
"status": "completed",
"created_at": 1787000000,
"completed_at": 1787000300,
"model": "kling-v3",
"error": null,
"outputs": [
{
"url": "https://example-cdn.com/output/abc123.mp4?sign=...",
"cover_url": "https://example-cdn.com/output/abc123_cover.jpg?sign=...",
"watermark_url": null,
"last_frame_url": null
}
],
"usage": {
"seconds": 5,
"width": 1920,
"height": 1080,
"fps": 24,
"tokens": null,
"billing": null
}
}

Queries the task list

GET /v1/videos

Request Parameters

Parameter
Type
Description
status
string
Filter by status: queued, in_progress, completed, failed, expired
model
string
Filter by exact model name
offset
integer
Offset. Default value: 0 (in descending order by creation time)
limit
integer
Number of items per page. Value range: 1-100. Default value: 20

Response Parameters

Parameter
Type
Description
data
array
Task list. Each item contains id, object, status, model, created_at, completed_at, and error (excluding outputs/usage; to obtain outputs, query a single task).
total
integer
Total number of tasks that meet the current filter criteria
When offset + limit is less than total, there is a next page, which the caller determines. The list returns only the tasks of the instance to which the current CMR API Key belongs.

Canceling Task

DELETE /v1/videos/{video_id}
Only tasks in the queued state can be canceled. If the cancellation is successful, 204 No Content is returned with no response body.
After a successful cancellation, the task enters the failed final state, and error.code is cancelled.
Whether cancellation is supported depends on the vendor of the selected model. If it is not supported, 405 (cancel_not_supported) is returned. If the task has already started generating or is in a final state, 409 (conflict) is returned.

Task Status

Status
Description
queued
Accepted and queued (this status can be canceled)
in_progress
Generating
completed
Generated successfully, and outputs are available.
failed
Generation failed (including user cancellation and content moderation rejection). For the reason, see error.
expired
The task has exceeded the retention period, and the outputs are no longer available.
Status only moves forward and never rolls back. Terminal states (completed/failed/expired) no longer change. A polling interval of at least 5 seconds is recommended to avoid high-frequency queries.

Result Address Description

outputs[].url is a temporary download URL on the model side. The validity period varies by vendor, with a minimum of about 12 hours. Download and store the file as soon as possible after the task is completed.
Access fails after the URL expires, and CMR does not provide the ability to obtain the address again.
Callers that require the exact expiration time can parse the signature parameters in the URL themselves, such as the Expires and q-sign-time fields, subject to the actual response.

Error Response

When a request fails, CMR returns a unified error format:
{
"error": {
"message": "duration 7 exceeds the range supported by the model",
"type": "invalid_request_error",
"param": "duration",
"code": "invalid_parameter"
}
}
Parameter
Description
error.message
Error description. For errors from the model side, keep the original text for troubleshooting.
error.type
Error type
error.param
Related request parameter. It is null when it cannot be located.
error.code
Error code. Subject to the actual response.
Common Error Codes
HTTP
type
code
Scenario and Handling Suggestion
400
invalid_request_error
invalid_parameter
The request format is invalid, the material combination does not match, or the parameter value is not supported by the model. Check and correct the request.
400
invalid_request_error
content_policy_violation
The content failed moderation. Adjust the prompt or materials.
400
invalid_request_error
model_not_supported
The model does not exist or is not bound to an instance. Check the model name.
401
authentication_error
unauthorized
The API Key is invalid. Check CMR_API_KEY.
403
permission_error
capability_not_enabled
Video capability is not enabled for the instance.
403
permission_error
forbidden
Accessed a task that does not belong to the current Key.
404
not_found_error
not_found
The task does not exist. Check video_id.
405
invalid_request_error
cancel_not_supported
This model does not support cancellation.
409
invalid_request_error
conflict
The canceled task is not in the queued state.
429
rate_limit_error
rate_limited
The number of concurrent tasks or the creation rate exceeds the limit. Refer to Retry-After (if available) and retry after reducing the rate.
500
api_error
internal_error
An internal error occurred on the platform. Retry later.
502
api_error
upstream_error
Creation failed on the model side and retries are exhausted. Retry later. If failures persist, record the task ID and contact support.

Help and Support

Was this page helpful?

Help us improve! Rate your documentation experience in 5 mins.

Feedback