> ## 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 Clothing Swap V5.
```
POST https://openapi.akool.com/api/open/v5/clothingSwap/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 image or video example consistently in both analyze and create. Use a completed analysis of the identical target\_url and media\_type. Video requires track\_manifest\_url; image does not. mappings\[].obj\_id values must be distinct and come from analysis\_result.media.
**Body Attributes**
| **Parameter** | **Type** | **Required** | **Description** |
| - | - | - | - |
| target\_url | String | true | Public source image or video URL; must match analysis. |
| media\_type | String | true | `image` or `video`. |
| analyze\_id | String | true | Completed analysis ID for the source material. |
| mappings | Array | true | 1–50 detected-person and reference-outfit mappings. |
| mappings\[].obj\_id | Integer | true | Person ID from analysis. |
| mappings\[].img\_url | String | true | Reference outfit image URL. |
| clothing\_area | String | false | `Top`, `Bottom`, `Full Outfit`, or `Auto`. Values are case-sensitive. |
| model\_name | String | false | Defaults to `akool-premium/clothing_swap`. |
| resolution | String | false | `480p` or `720p`; uses the selected model default, otherwise `480p`. |
| keep\_original\_sound | Boolean | false | Keep source video audio; defaults to true. |
| 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}
{
"target_url": "https://example.com/source.jpg",
"media_type": "image",
"analyze_id": "670000000000000000000001",
"mappings": [
{
"obj_id": 0,
"img_url": "https://example.com/outfit.jpg"
}
],
"model_name": "akool-premium/clothing_swap",
"clothing_area": "Full Outfit"
}
```
**Body**
```json theme={null}
{
"target_url": "https://example.com/source.mp4",
"media_type": "video",
"analyze_id": "670000000000000000000001",
"mappings": [
{
"obj_id": 0,
"img_url": "https://example.com/outfit.jpg"
}
],
"model_name": "akool-premium/clothing_swap",
"clothing_area": "Top",
"resolution": "480p",
"keep_original_sound": true
}
```
For input limits, billing, callbacks, and error codes, see the [Clothing Swap V5 overview](/ai-tools-suite/swap-studio/clothing-swap-v5).
```bash Image theme={null}
curl --request POST \
--url 'https://openapi.akool.com/api/open/v5/clothingSwap/create' \
--header 'x-api-key: ' \
--header 'Content-Type: application/json' \
--data '{
"target_url": "https://example.com/source.jpg",
"media_type": "image",
"analyze_id": "670000000000000000000001",
"mappings": [
{
"obj_id": 0,
"img_url": "https://example.com/outfit.jpg"
}
],
"model_name": "akool-premium/clothing_swap",
"clothing_area": "Full Outfit"
}'
```
```bash Video theme={null}
curl --request POST \
--url 'https://openapi.akool.com/api/open/v5/clothingSwap/create' \
--header 'x-api-key: ' \
--header 'Content-Type: application/json' \
--data '{
"target_url": "https://example.com/source.mp4",
"media_type": "video",
"analyze_id": "670000000000000000000001",
"mappings": [
{
"obj_id": 0,
"img_url": "https://example.com/outfit.jpg"
}
],
"model_name": "akool-premium/clothing_swap",
"clothing_area": "Top",
"resolution": "480p",
"keep_original_sound": true
}'
```
```json Image theme={null}
{
"code": 1000,
"msg": "OK",
"data": {
"list": [
{
"_id": "670000000000000000000002",
"status": 1,
"media_type": "image",
"model_name": "akool-premium/clothing_swap",
"deduction_credit": 6,
"create_time": 1791777600000,
"task_id": ""
}
],
"errors": []
}
}
```
```json Video theme={null}
{
"code": 1000,
"msg": "OK",
"data": {
"list": [
{
"_id": "670000000000000000000002",
"status": 1,
"media_type": "video",
"model_name": "akool-premium/clothing_swap",
"deduction_credit": 6,
"create_time": 1791777600000,
"task_id": ""
}
],
"errors": []
}
}
```
## OpenAPI
````yaml POST /api/open/v5/clothingSwap/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/clothingSwap/create:
post:
tags:
- Clothing Swap
summary: Create Task — Clothing Swap
description: >-
Choose the image or video example consistently in both analyze and
create. Use a completed analysis of the identical target_url and
media_type. Video requires track_manifest_url; image does not.
mappings[].obj_id values must be distinct and come from
analysis_result.media. Examples are illustrative; replace sample assets
and IDs. Authorization takes precedence when both authentication headers
are supplied.
operationId: clothingSwap_create
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
target_url:
type: string
description: Public source image or video URL; must match analysis.
format: uri
media_type:
type: string
description: '`image` or `video`.'
enum:
- image
- video
analyze_id:
type: string
description: Completed analysis ID for the source material.
pattern: ^[a-fA-F0-9]{24}$
mappings:
type: array
description: 1–50 detected-person and reference-outfit mappings.
items:
type: object
properties:
obj_id:
type: integer
description: Person ID from analysis.
minimum: 0
img_url:
type: string
description: Reference outfit image URL.
format: uri
required:
- obj_id
- img_url
minItems: 1
maxItems: 50
clothing_area:
type: string
description: >-
`Top`, `Bottom`, `Full Outfit`, or `Auto`. Values are
case-sensitive.
enum:
- Top
- Bottom
- Full Outfit
- Auto
default: Top
model_name:
type: string
description: Defaults to `akool-premium/clothing_swap`.
resolution:
type: string
description: >-
480p or 720p; uses the selected model default, otherwise
480p.
enum:
- 480p
- 720p
keep_original_sound:
type: boolean
description: >-
Keep source video audio; defaults to true. Applies to video
requests.
webhookUrl:
type: string
description: >-
Optional final-state callback URL; follow the [Webhook
guide](/ai-tools-suite/webhook).
format: uri
required:
- target_url
- media_type
- analyze_id
- mappings
examples:
image:
summary: Image clothing replacement
value:
target_url: https://example.com/source.jpg
media_type: image
analyze_id: '670000000000000000000001'
mappings:
- obj_id: 0
img_url: https://example.com/outfit.jpg
model_name: akool-premium/clothing_swap
clothing_area: Full Outfit
video:
summary: Video clothing replacement
value:
target_url: https://example.com/source.mp4
media_type: video
analyze_id: '670000000000000000000001'
mappings:
- obj_id: 0
img_url: https://example.com/outfit.jpg
model_name: akool-premium/clothing_swap
clothing_area: Top
resolution: 480p
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:
image:
summary: Image clothing replacement
value:
code: 1000
msg: OK
data:
list:
- _id: '670000000000000000000002'
status: 1
media_type: image
model_name: akool-premium/clothing_swap
deduction_credit: 6
create_time: 1791777600000
task_id: ''
errors: []
video:
summary: Video clothing replacement
value:
code: 1000
msg: OK
data:
list:
- _id: '670000000000000000000002'
status: 1
media_type: video
model_name: akool-premium/clothing_swap
deduction_credit: 6
create_time: 1791777600000
task_id: ''
errors: []
x-codeSamples:
- lang: bash
label: Image clothing replacement
source: |-
curl --request POST \
--url 'https://openapi.akool.com/api/open/v5/clothingSwap/create' \
--header 'x-api-key: ' \
--header 'Content-Type: application/json' \
--data '{
"target_url": "https://example.com/source.jpg",
"media_type": "image",
"analyze_id": "670000000000000000000001",
"mappings": [
{
"obj_id": 0,
"img_url": "https://example.com/outfit.jpg"
}
],
"model_name": "akool-premium/clothing_swap",
"clothing_area": "Full Outfit"
}'
- lang: bash
label: Video clothing replacement
source: |-
curl --request POST \
--url 'https://openapi.akool.com/api/open/v5/clothingSwap/create' \
--header 'x-api-key: ' \
--header 'Content-Type: application/json' \
--data '{
"target_url": "https://example.com/source.mp4",
"media_type": "video",
"analyze_id": "670000000000000000000001",
"mappings": [
{
"obj_id": 0,
"img_url": "https://example.com/outfit.jpg"
}
],
"model_name": "akool-premium/clothing_swap",
"clothing_area": "Top",
"resolution": "480p",
"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.