> ## 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](https://docs.akool.com/authentication/usage.md#get-the-token). |
| Content-Type | application/json | Required for JSON requests. |

> [!NOTE]
>
> 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](https://docs.akool.com/ai-tools-suite/webhook.md). |

**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).

> [tab] Kling
>
> **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
> }
> ```

> [tab] Wan
>
> **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
> }
> ```

> [tab] Pixverse
>
> **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
> }
> ```

> [!NOTE]
>
> For input limits, billing, callbacks, and error codes, see the [Motion Swap V5 overview](https://docs.akool.com/ai-tools-suite/swap-studio/motion-swap-v5.md).

```bash Kling theme={null}
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
}'
```

```bash Wan theme={null}
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
}'
```

```bash Pixverse theme={null}
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
}'
```

```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: <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: <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: <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.