Motion Control API Usage

Submit Task

Method: POST
Path: /v1/common_task/motion_control/task/submit
Headers: Topview-Uid, Authorization

Request

{
  "model": "Kling Motion Control Std V3",
  "characterImageFileId": "file_image_123",
  "motionReferenceVideoFileId": "file_video_456",
  "prompt": "Let the character follow the same dance motion.",
  "resolution": 720,
  "characterOrientation": "video",
  "keepOriginalSound": true,
  "boardId": "board_xxx",
  "noticeUrl": "https://example.com/topview/callback"
}

Supported Models

Model Name (value for `model` field)	Supported Resolution	Credit Rate
`Kling Motion Control Pro V3`	`1080`	1.0 credit/s
`Kling Motion Control Std V3`	`720`	0.8 credit/s
`Kling Motion Control Pro`	`1080`	0.5 credit/s
`Kling Motion Control Std`	`720`	0.31 credit/s

Note: The resolution value must match the model. Pro models require 1080; Std models require 720. A mismatch returns a parameter error.

Credit Deduction

Credits are deducted only when the task succeeds, based on the actual duration of the output video. Failed tasks are not charged.

Formula:

Credits consumed = Credit rate (credits/s) × Output video duration (s)

Examples (assuming a 5-second output video):

Model	Credit Rate	Example Duration	Credits Consumed
Kling Motion Control Pro V3	1.0 credit/s	5s	5.0 credits
Kling Motion Control Std V3	0.8 credit/s	5s	4.0 credits
Kling Motion Control Pro	0.5 credit/s	5s	2.5 credits
Kling Motion Control Std	0.31 credit/s	5s	1.55 credits

The costCredit field in the query response shows the actual credits consumed for the task. outputDuration is the output video duration in milliseconds.

Parameters

Field	Type	Required	Description
`model`	String	Yes	Display model name. See the Supported Models table above.
`characterImageFileId`	String	Yes	Character image fileId (jpg/jpeg/png only)
`motionReferenceVideoFileId`	String	Yes	Motion reference video fileId (mp4/mov only)
`prompt`	String	No	Positive prompt
`resolution`	Integer	Yes	Resolution: `720` for Std models, `1080` for Pro models
`characterOrientation`	String	No	Character orientation in the output: `video` (follow reference video pose) / `image` (follow reference image pose), default `video`
`keepOriginalSound`	Boolean	No	Whether to keep the original audio from the reference video, default `true`
`boardId`	String	No	Board ID
`noticeUrl`	String	No	Task completion callback URL

Validation Rules

Both the character image and reference video are validated via FFmpeg media parsing asynchronously after upload. Validation failure sets the task status to fail immediately.
Image constraints: format jpg/jpeg/png; width and height both in 300~65536; aspect ratio (short side / long side) in 0.4~2.5.
Video constraints: format mp4/mov; width and height both in 340~3850; duration 3~30s.
When characterOrientation=image, video duration is additionally limited to <=10s.

Response

{
  "code": "200",
  "message": "Success",
  "result": {
    "taskId": "a1b2c3d4e5",
    "status": "success",
    "boardId": "board_xxx"
  }
}

Query Task

Method: GET
Path: /v1/common_task/motion_control/task/query
Headers: Topview-Uid, Authorization

Query Parameters

Parameter	Type	Required	Description
`taskId`	String	Yes	Task ID returned by submit API
`needCloudFrontUrl`	Boolean	No	Whether to return CloudFront URL, default `false`

Response

{
  "code": "200",
  "message": "Success",
  "result": {
    "taskId": "a1b2c3d4e5",
    "status": "success",
    "costCredit": 1.24,
    "outputVideoFileId": "file_out_video_123",
    "outputCoverFileId": "file_out_cover_456",
    "outputVideoUrl": "https://cdn.example.com/video.mp4",
    "outputCoverUrl": "https://cdn.example.com/cover.jpg",
    "outputWidth": 720,
    "outputHeight": 1280,
    "outputDuration": 5000
  }
}

Status Enum

Status	Meaning
`init`	Submitted, waiting for processing
`running`	Processing (unfinished tasks are normalized to running)
`success`	Completed successfully
`fail`	Failed (check `errorMsg`)