POST /v1/videos — Create a video generation taskGET /v1/videos/{video_id} — Query a single taskGET /v1/videos — Query the task listDELETE /v1/videos/{video_id} — Cancel a task
POST {CMR_BASE_URL}/v1/videosGET {CMR_BASE_URL}/v1/videos/{video_id}GET {CMR_BASE_URL}/v1/videosDELETE {CMR_BASE_URL}/v1/videos/{video_id}
Header | Required | Description |
Authorization | Yes | Bearer <CMR_API_KEY> |
Content-Type | Yes | Fixed as application/json |
# ① Create a taskcurl --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 failedcurl --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
import osimport timeimport requestsbase_url = os.environ["CMR_BASE_URL"]headers = {"Authorization": f"Bearer {os.environ['CMR_API_KEY']}","Content-Type": "application/json",}# ① Create a taskresp = 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"):breaktime.sleep(5)# ③ Obtain the resultif task["status"] == "completed":print(task["outputs"][0]["url"]) # Video URL. Download and transfer it as soon as possible.else:print(task["error"])
POST /v1/videos
Parameter | Type | Required | Description |
model | string | Yes | CMR model name. Available values are subject to the console. |
contents | array | Yes | |
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). |
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.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) |
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. |
first_frame+last_frame materials cannot be mixed with reference materials. base videos cannot be mixed with feature videos.{"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"}
{"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" }]}
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. |
{"id": "video_abc123","error": null}
id only indicates that the task has been accepted and queued, not that generation has succeeded. Obtain the final result through the query API.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}
GET /v1/videos/{video_id}
video_id is the task ID returned at creation.Parameter | Type | Returned or Not | Description |
id | string | Yes | Task ID |
object | string | Yes | Fixed to video |
status | string | Yes | |
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. |
error field.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 (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. |
null instead of padded with 0.{"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}}
GET /v1/videos
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 |
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 |
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.DELETE /v1/videos/{video_id}
queued state can be canceled. If the cancellation is successful, 204 No Content is returned with no response body.failed final state, and error.code is cancelled.cancel_not_supported) is returned. If the task has already started generating or is in a final state, 409 (conflict) is returned.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. |
completed/failed/expired) no longer change. A polling interval of at least 5 seconds is recommended to avoid high-frequency queries.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.Expires and q-sign-time fields, subject to the actual response.{"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. |
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. |
Was this page helpful?
You can also Contact sales or Submit a Ticket for help.
Help us improve! Rate your documentation experience in 5 mins.
Feedback