> ## 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 Character Swap V5.
```
POST https://openapi.akool.com/api/open/v5/characterSwap/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. |
Choose the matching request example: Image replacement, Akool video replacement, or Kling video replacement. analyze\_id is required only for Akool video. obj\_id and img\_url belong to mappings\[], not analyze\_id. Kling uses image and target\_url; image replacement uses source\_url, source\_bbox and target\_bbox inside mappings\[].
**Body Attributes**
| **Parameter** | **Type** | **Required** | **Description** |
| - | - | - | - |
| media\_type | String | true | `image` or `video`. |
| target\_url | String | true | Public source scene image or video URL. |
| model\_name | String | false | Defaults to `akool-premium-multi-person`. Get supported IDs from the models endpoint. |
| mappings | Array | conditional | Image: 1–2 mappings with `source_url`, `source_bbox`, and `target_bbox`. Akool video: 1–5 mappings with `obj_id` and `img_url`. |
| mappings\[].source\_url | String | image | Reference character image URL. |
| mappings\[].source\_bbox | Array | image | Reference face bounding box `[x1,y1,x2,y2]` in original-image pixels. |
| mappings\[].target\_bbox | Array | image | Target face bounding box `[x1,y1,x2,y2]` in original-image pixels. The same target box cannot be mapped twice. |
| mappings\[].obj\_id | Integer | Akool video | Person ID from the analysis result. |
| mappings\[].img\_url | String | Akool video | Reference character image URL. |
| analyze\_id | String | Akool video only | Completed person analysis \_id for the identical source video URL; not needed for image or Kling video. |
| character\_orientation | String | false | Kling video: `image` or `video`; defaults to `video`. |
| image | String | Kling video | Reference character URL for a single-person Kling replacement. |
| resolution | String | false | Image: automatic. Akool video: 480p or 720p. Kling: choose from the model's supported values. |
| keep\_original\_sound | Boolean | false | Keep source video audio; defaults to true. |
| prompt | String | false | Video generation instructions: up to 2500 characters for Kling and 5000 for Akool. Overlong prompts are rejected before generation. Image replacement generates its instructions from mappings. |
| negative\_prompt | String | false | Optional Kling video negative instructions, up to 5000 characters. |
| 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 a scenario below or in the request sample to view matching request and response examples. URLs, IDs and model selections are illustrative; replace them with accessible resources, completed analyses and models available to your account. Response credit values are examples, not price quotations. Poll each returned \_id until completion.
**Body**
```json theme={null}
{
"media_type": "image",
"target_url": "https://example.com/scene.jpg",
"model_name": "akool-premium-multi-person",
"mappings": [
{
"source_url": "https://example.com/character.jpg",
"source_bbox": [
10,
20,
200,
400
],
"target_bbox": [
100,
50,
350,
600
]
}
]
}
```
**Body**
```json theme={null}
{
"media_type": "video",
"target_url": "https://example.com/source.mp4",
"model_name": "akool-premium-multi-person",
"analyze_id": "670000000000000000000001",
"mappings": [
{
"obj_id": 0,
"img_url": "https://example.com/character.jpg"
}
],
"resolution": "480p",
"keep_original_sound": true,
"prompt": "Preserve the source scene."
}
```
**Body**
```json theme={null}
{
"media_type": "video",
"target_url": "https://example.com/source.mp4",
"model_name": "kling-v3.0-pro/character-swap",
"image": "https://example.com/character.jpg",
"character_orientation": "video",
"resolution": "720p",
"keep_original_sound": true,
"prompt": "Preserve the original movement.",
"negative_prompt": "blur"
}
```
For input limits, billing, callbacks, and error codes, see the [Character Swap V5 overview](/ai-tools-suite/swap-studio/character-swap-v5).
```bash Image theme={null}
curl --request POST \
--url 'https://openapi.akool.com/api/open/v5/characterSwap/create' \
--header 'x-api-key: ' \
--header 'Content-Type: application/json' \
--data '{
"media_type": "image",
"target_url": "https://example.com/scene.jpg",
"model_name": "akool-premium-multi-person",
"mappings": [
{
"source_url": "https://example.com/character.jpg",
"source_bbox": [
10,
20,
200,
400
],
"target_bbox": [
100,
50,
350,
600
]
}
]
}'
```
```bash Akool video theme={null}
curl --request POST \
--url 'https://openapi.akool.com/api/open/v5/characterSwap/create' \
--header 'x-api-key: ' \
--header 'Content-Type: application/json' \
--data '{
"media_type": "video",
"target_url": "https://example.com/source.mp4",
"model_name": "akool-premium-multi-person",
"analyze_id": "670000000000000000000001",
"mappings": [
{
"obj_id": 0,
"img_url": "https://example.com/character.jpg"
}
],
"resolution": "480p",
"keep_original_sound": true,
"prompt": "Preserve the source scene."
}'
```
```bash Kling video theme={null}
curl --request POST \
--url 'https://openapi.akool.com/api/open/v5/characterSwap/create' \
--header 'x-api-key: ' \
--header 'Content-Type: application/json' \
--data '{
"media_type": "video",
"target_url": "https://example.com/source.mp4",
"model_name": "kling-v3.0-pro/character-swap",
"image": "https://example.com/character.jpg",
"character_orientation": "video",
"resolution": "720p",
"keep_original_sound": true,
"prompt": "Preserve the original movement.",
"negative_prompt": "blur"
}'
```
```json Image theme={null}
{
"code": 1000,
"msg": "OK",
"data": {
"list": [
{
"_id": "670000000000000000000002",
"status": 1,
"media_type": "image",
"model_name": "akool-premium-multi-person",
"deduction_credit": 6,
"create_time": 1791777600000,
"task_id": ""
}
],
"errors": []
}
}
```
```json Akool video theme={null}
{
"code": 1000,
"msg": "OK",
"data": {
"list": [
{
"_id": "670000000000000000000002",
"status": 1,
"media_type": "video",
"model_name": "akool-premium-multi-person",
"deduction_credit": 6,
"create_time": 1791777600000,
"task_id": ""
}
],
"errors": []
}
}
```
```json Kling video theme={null}
{
"code": 1000,
"msg": "OK",
"data": {
"list": [
{
"_id": "670000000000000000000002",
"status": 1,
"media_type": "video",
"model_name": "kling-v3.0-pro/character-swap",
"deduction_credit": 6,
"create_time": 1791777600000,
"task_id": ""
}
],
"errors": []
}
}
```
## OpenAPI
````yaml POST /api/open/v5/characterSwap/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/characterSwap/create:
post:
tags:
- Character Swap
summary: Create Task — Character Swap
description: >-
Choose the matching request example: Image replacement, Akool video
replacement, or Kling video replacement. analyze_id is required only for
Akool video. obj_id and img_url belong to mappings[], not analyze_id.
Kling uses image and target_url; image replacement uses source_url,
source_bbox and target_bbox inside mappings[]. Examples are
illustrative; replace sample assets and IDs. Authorization takes
precedence when both authentication headers are supplied.
operationId: characterSwap_create
requestBody:
required: true
content:
application/json:
schema:
oneOf:
- properties:
media_type:
enum:
- image
target_url:
type: string
description: Public source scene image or video URL.
format: uri
model_name:
type: string
enum:
- akool-premium-multi-person
mappings:
type: array
description: >-
Image: 1–2 mappings with `source_url`, `source_bbox`,
and `target_bbox`. Akool video: 1–5 mappings with
`obj_id` and `img_url`.
items:
type: object
properties:
source_url:
type: string
description: Reference character image URL.
format: uri
source_bbox:
type: array
description: >-
Reference face bounding box `[x1,y1,x2,y2]` in
original-image pixels.
items:
type: number
minimum: 0
minItems: 4
maxItems: 4
target_bbox:
type: array
description: >-
Target face bounding box `[x1,y1,x2,y2]` in
original-image pixels. The same target box cannot
be mapped twice.
items:
type: number
minimum: 0
minItems: 4
maxItems: 4
required:
- source_url
- source_bbox
- target_bbox
minItems: 1
maxItems: 2
analyze_id:
type: string
description: >-
Required only for Akool video: completed person analysis
_id for the identical source video URL. Image and Kling
video do not need it.
pattern: ^[a-fA-F0-9]{24}$
character_orientation:
type: string
description: 'Kling video: `image` or `video`; defaults to `video`.'
enum:
- image
- video
image:
type: string
description: >-
Required only for Kling video: public
reference-character image URL. target_url is the source
video; both must contain a single person.
format: uri
resolution:
type: string
description: >-
Image: selected automatically. Akool video: 480p or
720p, using the model default or 480p fallback. Kling
video: select a supported value from models (720p
fallback).
keep_original_sound:
type: boolean
description: >-
Keep source video audio; defaults to true. Applies to
video requests.
prompt:
type: string
description: >-
Video generation instructions, up to 5000 characters.
Image replacement generates its instructions from
mappings.
maxLength: 5000
webhookUrl:
type: string
description: >-
Optional final-state callback URL; follow the [Webhook
guide](/ai-tools-suite/webhook).
format: uri
negative_prompt:
type: string
maxLength: 5000
description: Optional Kling video negative instructions.
required:
- media_type
- target_url
- mappings
title: Image
type: object
- properties:
media_type:
enum:
- video
target_url:
type: string
description: Public source scene image or video URL.
format: uri
model_name:
not:
enum:
- kling-v3.0-pro/character-swap
mappings:
type: array
description: >-
Image: 1–2 mappings with `source_url`, `source_bbox`,
and `target_bbox`. Akool video: 1–5 mappings with
`obj_id` and `img_url`.
items:
type: object
properties:
obj_id:
type: integer
description: Person ID from the analysis result.
minimum: 0
img_url:
type: string
description: Reference character image URL.
format: uri
required:
- obj_id
- img_url
minItems: 1
maxItems: 5
analyze_id:
type: string
description: >-
Required only for Akool video: completed person analysis
_id for the identical source video URL. Image and Kling
video do not need it.
pattern: ^[a-fA-F0-9]{24}$
character_orientation:
type: string
description: 'Kling video: `image` or `video`; defaults to `video`.'
enum:
- image
- video
image:
type: string
description: >-
Required only for Kling video: public
reference-character image URL. target_url is the source
video; both must contain a single person.
format: uri
resolution:
type: string
description: >-
Image: selected automatically. Akool video: 480p or
720p, using the model default or 480p fallback. Kling
video: select a supported value from models (720p
fallback).
keep_original_sound:
type: boolean
description: >-
Keep source video audio; defaults to true. Applies to
video requests.
prompt:
type: string
description: >-
Video generation instructions, up to 5000 characters.
Image replacement generates its instructions from
mappings.
maxLength: 5000
webhookUrl:
type: string
description: >-
Optional final-state callback URL; follow the [Webhook
guide](/ai-tools-suite/webhook).
format: uri
negative_prompt:
type: string
maxLength: 5000
description: Optional Kling video negative instructions.
required:
- media_type
- target_url
- analyze_id
- mappings
title: Akool video
type: object
- properties:
media_type:
enum:
- video
target_url:
type: string
description: Public source scene image or video URL.
format: uri
model_name:
enum:
- kling-v3.0-pro/character-swap
mappings:
type: array
description: >-
Required for image (1–2) and Akool video (1–5); not
required for Kling video. Select the matching request
example. obj_id and img_url are mappings[] fields.
items:
type: object
properties:
source_url:
type: string
description: Reference character image URL.
format: uri
source_bbox:
type: array
description: >-
Reference face bounding box `[x1,y1,x2,y2]` in
original-image pixels.
items:
type: number
minimum: 0
minItems: 4
maxItems: 4
target_bbox:
type: array
description: >-
Target face bounding box `[x1,y1,x2,y2]` in
original-image pixels. The same target box cannot
be mapped twice.
items:
type: number
minimum: 0
minItems: 4
maxItems: 4
obj_id:
type: integer
description: Person ID from the analysis result.
minimum: 0
img_url:
type: string
description: Reference character image URL.
format: uri
minItems: 1
maxItems: 5
analyze_id:
type: string
description: >-
Required only for Akool video: completed person analysis
_id for the identical source video URL. Image and Kling
video do not need it.
pattern: ^[a-fA-F0-9]{24}$
character_orientation:
type: string
description: 'Kling video: `image` or `video`; defaults to `video`.'
enum:
- image
- video
image:
type: string
description: >-
Required only for Kling video: public
reference-character image URL. target_url is the source
video; both must contain a single person.
format: uri
resolution:
type: string
description: >-
Image: selected automatically. Akool video: 480p or
720p, using the model default or 480p fallback. Kling
video: select a supported value from models (720p
fallback).
keep_original_sound:
type: boolean
description: >-
Keep source video audio; defaults to true. Applies to
video requests.
prompt:
type: string
description: >-
Video generation instructions, up to 5000 characters.
Image replacement generates its instructions from
mappings.
maxLength: 5000
webhookUrl:
type: string
description: >-
Optional final-state callback URL; follow the [Webhook
guide](/ai-tools-suite/webhook).
format: uri
negative_prompt:
type: string
maxLength: 5000
description: Optional Kling video negative instructions.
required:
- media_type
- target_url
- model_name
- image
title: Kling video
type: object
examples:
image:
summary: Image replacement
value:
media_type: image
target_url: https://example.com/scene.jpg
model_name: akool-premium-multi-person
mappings:
- source_url: https://example.com/character.jpg
source_bbox:
- 10
- 20
- 200
- 400
target_bbox:
- 100
- 50
- 350
- 600
akoolVideo:
summary: Akool video replacement
value:
media_type: video
target_url: https://example.com/source.mp4
model_name: akool-premium-multi-person
analyze_id: '670000000000000000000001'
mappings:
- obj_id: 0
img_url: https://example.com/character.jpg
resolution: 480p
keep_original_sound: true
prompt: Preserve the source scene.
klingVideo:
summary: Kling video replacement
value:
media_type: video
target_url: https://example.com/source.mp4
model_name: kling-v3.0-pro/character-swap
image: https://example.com/character.jpg
character_orientation: video
resolution: 720p
keep_original_sound: true
prompt: Preserve the original movement.
negative_prompt: blur
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:
image:
summary: Image replacement
value:
code: 1000
msg: OK
data:
list:
- _id: '670000000000000000000002'
status: 1
media_type: image
model_name: akool-premium-multi-person
deduction_credit: 6
create_time: 1791777600000
task_id: ''
errors: []
akoolVideo:
summary: Akool video replacement
value:
code: 1000
msg: OK
data:
list:
- _id: '670000000000000000000002'
status: 1
media_type: video
model_name: akool-premium-multi-person
deduction_credit: 6
create_time: 1791777600000
task_id: ''
errors: []
klingVideo:
summary: Kling video replacement
value:
code: 1000
msg: OK
data:
list:
- _id: '670000000000000000000002'
status: 1
media_type: video
model_name: kling-v3.0-pro/character-swap
deduction_credit: 6
create_time: 1791777600000
task_id: ''
errors: []
x-codeSamples:
- lang: bash
label: Image replacement
source: |-
curl --request POST \
--url 'https://openapi.akool.com/api/open/v5/characterSwap/create' \
--header 'x-api-key: ' \
--header 'Content-Type: application/json' \
--data '{
"media_type": "image",
"target_url": "https://example.com/scene.jpg",
"model_name": "akool-premium-multi-person",
"mappings": [
{
"source_url": "https://example.com/character.jpg",
"source_bbox": [
10,
20,
200,
400
],
"target_bbox": [
100,
50,
350,
600
]
}
]
}'
- lang: bash
label: Akool video replacement
source: |-
curl --request POST \
--url 'https://openapi.akool.com/api/open/v5/characterSwap/create' \
--header 'x-api-key: ' \
--header 'Content-Type: application/json' \
--data '{
"media_type": "video",
"target_url": "https://example.com/source.mp4",
"model_name": "akool-premium-multi-person",
"analyze_id": "670000000000000000000001",
"mappings": [
{
"obj_id": 0,
"img_url": "https://example.com/character.jpg"
}
],
"resolution": "480p",
"keep_original_sound": true,
"prompt": "Preserve the source scene."
}'
- lang: bash
label: Kling video replacement
source: |-
curl --request POST \
--url 'https://openapi.akool.com/api/open/v5/characterSwap/create' \
--header 'x-api-key: ' \
--header 'Content-Type: application/json' \
--data '{
"media_type": "video",
"target_url": "https://example.com/source.mp4",
"model_name": "kling-v3.0-pro/character-swap",
"image": "https://example.com/character.jpg",
"character_orientation": "video",
"resolution": "720p",
"keep_original_sound": true,
"prompt": "Preserve the original movement.",
"negative_prompt": "blur"
}'
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.