curl --request POST \
--url 'https://openapi.akool.com/api/open/v5/motionSwap/create' \
--header 'x-api-key: <api-key>' \
--header 'Content-Type: application/json' \
--data '{
"video": "https://example.com/motion.mp4",
"images": [
"https://example.com/character.jpg"
],
"model_name": "kwaivgi/kling-v3.0-pro/motion-control",
"resolution": "720P",
"character_orientation": "video",
"keep_original_sound": true
}'
curl --request POST \
--url 'https://openapi.akool.com/api/open/v5/motionSwap/create' \
--header 'x-api-key: <api-key>' \
--header 'Content-Type: application/json' \
--data '{
"video": "https://example.com/motion.mp4",
"images": [
"https://example.com/character.jpg"
],
"model_name": "wavespeed-ai/wan-2.2/animate",
"resolution": "720p",
"mode": "animate",
"prompt": "Preserve the character appearance.",
"negative_prompt": "blur",
"keep_original_sound": true
}'
curl --request POST \
--url 'https://openapi.akool.com/api/open/v5/motionSwap/create' \
--header 'x-api-key: <api-key>' \
--header 'Content-Type: application/json' \
--data '{
"video": "https://example.com/motion.mp4",
"images": [
"https://example.com/character.jpg"
],
"model_name": "pixverse/motion-control",
"resolution": "720p",
"keep_original_sound": true
}'
{
"code": 1000,
"msg": "OK",
"data": {
"list": [
{
"_id": "670000000000000000000002",
"status": 1,
"media_type": "video",
"model_name": "kwaivgi/kling-v3.0-pro/motion-control",
"deduction_credit": 6,
"create_time": 1791777600000,
"task_id": ""
}
],
"errors": []
}
}
{
"code": 1000,
"msg": "OK",
"data": {
"list": [
{
"_id": "670000000000000000000002",
"status": 1,
"media_type": "video",
"model_name": "wavespeed-ai/wan-2.2/animate",
"deduction_credit": 6,
"create_time": 1791777600000,
"task_id": ""
}
],
"errors": []
}
}
{
"code": 1000,
"msg": "OK",
"data": {
"list": [
{
"_id": "670000000000000000000002",
"status": 1,
"media_type": "video",
"model_name": "pixverse/motion-control",
"deduction_credit": 6,
"create_time": 1791777600000,
"task_id": ""
}
],
"errors": []
}
}
API Endpoints
Create Task
Create Task for Motion Swap V5.
POST
/
api
/
open
/
v5
/
motionSwap
/
create
curl --request POST \
--url 'https://openapi.akool.com/api/open/v5/motionSwap/create' \
--header 'x-api-key: <api-key>' \
--header 'Content-Type: application/json' \
--data '{
"video": "https://example.com/motion.mp4",
"images": [
"https://example.com/character.jpg"
],
"model_name": "kwaivgi/kling-v3.0-pro/motion-control",
"resolution": "720P",
"character_orientation": "video",
"keep_original_sound": true
}'
curl --request POST \
--url 'https://openapi.akool.com/api/open/v5/motionSwap/create' \
--header 'x-api-key: <api-key>' \
--header 'Content-Type: application/json' \
--data '{
"video": "https://example.com/motion.mp4",
"images": [
"https://example.com/character.jpg"
],
"model_name": "wavespeed-ai/wan-2.2/animate",
"resolution": "720p",
"mode": "animate",
"prompt": "Preserve the character appearance.",
"negative_prompt": "blur",
"keep_original_sound": true
}'
curl --request POST \
--url 'https://openapi.akool.com/api/open/v5/motionSwap/create' \
--header 'x-api-key: <api-key>' \
--header 'Content-Type: application/json' \
--data '{
"video": "https://example.com/motion.mp4",
"images": [
"https://example.com/character.jpg"
],
"model_name": "pixverse/motion-control",
"resolution": "720p",
"keep_original_sound": true
}'
{
"code": 1000,
"msg": "OK",
"data": {
"list": [
{
"_id": "670000000000000000000002",
"status": 1,
"media_type": "video",
"model_name": "kwaivgi/kling-v3.0-pro/motion-control",
"deduction_credit": 6,
"create_time": 1791777600000,
"task_id": ""
}
],
"errors": []
}
}
{
"code": 1000,
"msg": "OK",
"data": {
"list": [
{
"_id": "670000000000000000000002",
"status": 1,
"media_type": "video",
"model_name": "wavespeed-ai/wan-2.2/animate",
"deduction_credit": 6,
"create_time": 1791777600000,
"task_id": ""
}
],
"errors": []
}
}
{
"code": 1000,
"msg": "OK",
"data": {
"list": [
{
"_id": "670000000000000000000002",
"status": 1,
"media_type": "video",
"model_name": "pixverse/motion-control",
"deduction_credit": 6,
"create_time": 1791777600000,
"task_id": ""
}
],
"errors": []
}
}
POST https://openapi.akool.com/api/open/v5/motionSwap/create
| Parameter | Value | Description |
|---|---|---|
| x-api-key | API Key | API key used for authorization. Authorization takes precedence when both headers are supplied. |
| Authorization | Bearer {token} | Get Token. |
| Content-Type | application/json | Required for JSON requests. |
Each reference image produces a separate video task. Use a model returned by this operation’s models endpoint and its exact resolution values. Optional mode is forwarded for Wan; character_orientation is used for Kling. duration does not trim or replace the measured driving-video duration.
| Parameter | Type | Required | Description |
|---|---|---|---|
| video | String | true | Public driving video URL. |
| images | Array | true | 1–50 public character image URLs. Each image creates an independent video task. |
| model_name | String | true | Motion-control model ID from the models endpoint. |
| resolution | String | false | Case-sensitive resolution supported by the selected model. |
| mode | String | false | Wan models: animate or replace, defaults to animate. |
| prompt | String | false | Optional instructions: up to 2500 characters for Kling and 5000 for Wan. Overlong prompts are rejected before generation. |
| negative_prompt | String | false | Optional negative instructions, up to 5000 characters, for Wan/Kling models. |
| character_orientation | String | false | Kling models: image or video, defaults to video; image orientation supports at most 10 seconds. |
| keep_original_sound | Boolean | false | Keep source audio in the generated video; defaults to true. |
| duration | Number | false | Optional compatibility field (1–120). The server measures the actual video duration for limits and billing; this field does not trim or override it. |
| webhookUrl | String | false | Optional final-state callback URL; follow the Webhook guide. |
| Parameter | Type | Description |
|---|---|---|
| code | Integer | Business response code; 1000 means the request succeeded. |
| msg | String | Response message. |
| data | Object | Batch creation result. |
| - list | Array | Successfully created tasks. |
| — _id | String | Task ID to use for result polling. |
| — task_id | String | Downstream algorithm/provider task ID; may be empty until submission. Use _id, not this value, for task-detail queries. It may change between workflow stages. |
| — status | Integer | Initial task status. |
| — media_type | String | Output media type: image or video. |
| — model_name | String | Selected model ID. |
| — deduction_credit | Number | Task billing amount. |
| — create_time | Number | Creation timestamp in milliseconds. |
| - errors | Array | Inputs that could not create a task. Inspect this array even when code is 1000. |
| — index | Integer | Zero-based plan/input index that failed during submission. |
| — error | String | Submission failure description. |
Request examples
Select the model family matching your request. Replace the sample assets and model selection with values available to your account. Resolution is case-sensitive (for example, Kling 720P versus Wan/Pixverse 720p).- Kling
- Wan
- Pixverse
Body
{
"video": "https://example.com/motion.mp4",
"images": [
"https://example.com/character.jpg"
],
"model_name": "kwaivgi/kling-v3.0-pro/motion-control",
"resolution": "720P",
"character_orientation": "video",
"keep_original_sound": true
}
Body
{
"video": "https://example.com/motion.mp4",
"images": [
"https://example.com/character.jpg"
],
"model_name": "wavespeed-ai/wan-2.2/animate",
"resolution": "720p",
"mode": "animate",
"prompt": "Preserve the character appearance.",
"negative_prompt": "blur",
"keep_original_sound": true
}
Body
{
"video": "https://example.com/motion.mp4",
"images": [
"https://example.com/character.jpg"
],
"model_name": "pixverse/motion-control",
"resolution": "720p",
"keep_original_sound": true
}
For input limits, billing, callbacks, and error codes, see the Motion Swap V5 overview.
curl --request POST \
--url 'https://openapi.akool.com/api/open/v5/motionSwap/create' \
--header 'x-api-key: <api-key>' \
--header 'Content-Type: application/json' \
--data '{
"video": "https://example.com/motion.mp4",
"images": [
"https://example.com/character.jpg"
],
"model_name": "kwaivgi/kling-v3.0-pro/motion-control",
"resolution": "720P",
"character_orientation": "video",
"keep_original_sound": true
}'
curl --request POST \
--url 'https://openapi.akool.com/api/open/v5/motionSwap/create' \
--header 'x-api-key: <api-key>' \
--header 'Content-Type: application/json' \
--data '{
"video": "https://example.com/motion.mp4",
"images": [
"https://example.com/character.jpg"
],
"model_name": "wavespeed-ai/wan-2.2/animate",
"resolution": "720p",
"mode": "animate",
"prompt": "Preserve the character appearance.",
"negative_prompt": "blur",
"keep_original_sound": true
}'
curl --request POST \
--url 'https://openapi.akool.com/api/open/v5/motionSwap/create' \
--header 'x-api-key: <api-key>' \
--header 'Content-Type: application/json' \
--data '{
"video": "https://example.com/motion.mp4",
"images": [
"https://example.com/character.jpg"
],
"model_name": "pixverse/motion-control",
"resolution": "720p",
"keep_original_sound": true
}'
{
"code": 1000,
"msg": "OK",
"data": {
"list": [
{
"_id": "670000000000000000000002",
"status": 1,
"media_type": "video",
"model_name": "kwaivgi/kling-v3.0-pro/motion-control",
"deduction_credit": 6,
"create_time": 1791777600000,
"task_id": ""
}
],
"errors": []
}
}
{
"code": 1000,
"msg": "OK",
"data": {
"list": [
{
"_id": "670000000000000000000002",
"status": 1,
"media_type": "video",
"model_name": "wavespeed-ai/wan-2.2/animate",
"deduction_credit": 6,
"create_time": 1791777600000,
"task_id": ""
}
],
"errors": []
}
}
{
"code": 1000,
"msg": "OK",
"data": {
"list": [
{
"_id": "670000000000000000000002",
"status": 1,
"media_type": "video",
"model_name": "pixverse/motion-control",
"deduction_credit": 6,
"create_time": 1791777600000,
"task_id": ""
}
],
"errors": []
}
}
Authorizations
ApiKeyAuthBearerAuth
Body
application/json
Public driving video URL.
1–50 public character image URLs. Each image creates an independent video task.
Required array length:
1 - 50 elementsMotion-control model ID from the models endpoint.
Case-sensitive resolution supported by the selected model.
Wan models: animate or replace; defaults to animate. Not forwarded to other model families.
Available options:
animate, replace Optional instructions, up to 5000 characters, for Wan/Kling models.
Maximum string length:
5000Optional negative instructions, up to 5000 characters, for Wan/Kling models.
Maximum string length:
5000Kling models: image or video; defaults to video. image orientation supports at most 10 seconds. Not forwarded to other model families.
Available options:
image, video Keep source audio in the generated video; defaults to true.
Optional compatibility field. Actual video duration is measured for limits and billing; this does not trim or override it.
Required range:
1 <= x <= 120Optional final-state callback URL; follow the Webhook guide.