> ## Documentation Index
> Fetch the complete documentation index at: https://docs.akool.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Create Task
> Create Task for Motion Swap V5.
```
POST https://openapi.akool.com/api/open/v5/motionSwap/create
```
**Request Headers**
| **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](/authentication/usage#get-the-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.
**Body Attributes**
| **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](/ai-tools-suite/webhook). |
**Response Attributes**
| **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).
**Body**
```json theme={null}
{
"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**
```json theme={null}
{
"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**
```json theme={null}
{
"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](/ai-tools-suite/swap-studio/motion-swap-v5).
```bash Kling theme={null}
curl --request POST \
--url 'https://openapi.akool.com/api/open/v5/motionSwap/create' \
--header 'x-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
}'
```
```bash Wan theme={null}
curl --request POST \
--url 'https://openapi.akool.com/api/open/v5/motionSwap/create' \
--header 'x-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
}'
```
```bash Pixverse theme={null}
curl --request POST \
--url 'https://openapi.akool.com/api/open/v5/motionSwap/create' \
--header 'x-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
}'
```
```json Kling theme={null}
{
"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": []
}
}
```
```json Wan theme={null}
{
"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": []
}
}
```
```json Pixverse theme={null}
{
"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": []
}
}
```
## OpenAPI
````yaml POST /api/open/v5/motionSwap/create
openapi: 3.0.3
info:
title: Swap Studio V5 API
version: 5.0.0
description: Asynchronous character, motion, head, hair and clothing replacement APIs.
servers:
- url: https://openapi.akool.com
security:
- ApiKeyAuth: []
- BearerAuth: []
paths:
/api/open/v5/motionSwap/create:
post:
tags:
- Motion Swap
summary: Create Task — Motion Swap
description: >-
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. Examples are illustrative; replace sample assets
and IDs. Authorization takes precedence when both authentication headers
are supplied.
operationId: motionSwap_create
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
video:
type: string
description: Public driving video URL.
format: uri
images:
type: array
description: >-
1–50 public character image URLs. Each image creates an
independent video task.
items:
type: string
format: uri
minItems: 1
maxItems: 50
model_name:
type: string
description: Motion-control model ID from the models endpoint.
resolution:
type: string
description: Case-sensitive resolution supported by the selected model.
mode:
type: string
description: >-
Wan models: animate or replace; defaults to animate. Not
forwarded to other model families.
enum:
- animate
- replace
prompt:
type: string
description: >-
Optional instructions, up to 5000 characters, for Wan/Kling
models.
maxLength: 5000
negative_prompt:
type: string
description: >-
Optional negative instructions, up to 5000 characters, for
Wan/Kling models.
maxLength: 5000
character_orientation:
type: string
description: >-
Kling models: image or video; defaults to video. image
orientation supports at most 10 seconds. Not forwarded to
other model families.
enum:
- image
- video
keep_original_sound:
type: boolean
description: Keep source audio in the generated video; defaults to true.
duration:
type: number
description: >-
Optional compatibility field. Actual video duration is
measured for limits and billing; this does not trim or
override it.
minimum: 1
maximum: 120
webhookUrl:
type: string
description: >-
Optional final-state callback URL; follow the [Webhook
guide](/ai-tools-suite/webhook).
format: uri
required:
- video
- images
- model_name
examples:
kling:
summary: Kling motion transfer
value:
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
wan:
summary: Wan motion transfer
value:
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
pixverse:
summary: Pixverse motion transfer
value:
video: https://example.com/motion.mp4
images:
- https://example.com/character.jpg
model_name: pixverse/motion-control
resolution: 720p
keep_original_sound: true
responses:
'200':
description: >-
Business response. Code 1000 means the request succeeded; inspect
task status or data.errors for generation/submission outcomes.
content:
application/json:
schema:
type: object
properties:
code:
type: integer
example: 1000
msg:
type: string
example: OK
data:
type: object
properties:
list:
type: array
items:
$ref: '#/components/schemas/Task'
errors:
type: array
items:
type: object
properties:
index:
type: integer
minimum: 0
error:
type: string
examples:
kling:
summary: Kling motion transfer
value:
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: []
wan:
summary: Wan motion transfer
value:
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: []
pixverse:
summary: Pixverse motion transfer
value:
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: []
x-codeSamples:
- lang: bash
label: Kling motion transfer
source: |-
curl --request POST \
--url 'https://openapi.akool.com/api/open/v5/motionSwap/create' \
--header 'x-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
}'
- lang: bash
label: Wan motion transfer
source: |-
curl --request POST \
--url 'https://openapi.akool.com/api/open/v5/motionSwap/create' \
--header 'x-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
}'
- lang: bash
label: Pixverse motion transfer
source: |-
curl --request POST \
--url 'https://openapi.akool.com/api/open/v5/motionSwap/create' \
--header 'x-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
}'
components:
schemas:
Task:
type: object
properties:
_id:
type: string
description: ID used for task-detail queries.
task_id:
type: string
description: >-
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:
type: integer
enum:
- 1
- 2
- 3
- 4
media_type:
type: string
enum:
- image
- video
model_name:
type: string
deduction_credit:
type: number
create_time:
type: number
progress:
type: number
url:
type: string
error_reason:
type: string
multi_shot_results:
type: array
items:
type: object
additionalProperties: true
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: x-api-key
BearerAuth:
type: http
scheme: bearer
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.