> ## 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 Hair Swap V5.
```
POST https://openapi.akool.com/api/open/v5/hairswap/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. |
Use images for reference-image batches or mappings for per-face selection. When mappings is supplied it takes precedence; top-level face indexes apply only to the images shortcut. Multi-person targets combine mappings into one primary task and each target face can appear only once. multi\_shot=true requires a single-person target and at most 12 references (four outputs per primary task).
**Body Attributes**
| **Parameter** | **Type** | **Required** | **Description** |
| - | - | - | - |
| target\_url | String | true | Public target portrait image URL. |
| images | Array | conditional | 1–50 reference hairstyle image URLs (at most 12 with `multi_shot: true`). Provide `images` or `mappings`. |
| mappings | Array | conditional | 1–50 objects (at most 12 with `multi_shot: true`); takes precedence over `images`. |
| mappings\[].source\_url | String | true | Reference hairstyle image URL. |
| mappings\[].target\_face\_index | Integer | false | Zero-based target face index for this mapping; defaults to 0. |
| mappings\[].source\_face\_index | Integer | false | Zero-based reference face index for this mapping; defaults to 0. |
| multi\_shot | Boolean | false | Generate three additional hairstyle views; defaults to false. Single-person targets only. |
| target\_face\_index | Integer | false | Zero-based target face index for `images` only; defaults to `0`. For `mappings`, set it on each mapping. |
| source\_face\_index | Integer | false | Zero-based reference face index for `images` only; defaults to `0`. For `mappings`, set it on each mapping. |
| model\_name | String | false | Defaults to `akool/hair-swap`. |
| 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/portrait.jpg",
"images": [
"https://example.com/hairstyle.jpg"
],
"target_face_index": 0,
"source_face_index": 0,
"model_name": "akool/hair-swap"
}
```
**Body**
```json theme={null}
{
"target_url": "https://example.com/group.jpg",
"mappings": [
{
"source_url": "https://example.com/hairstyle.jpg",
"target_face_index": 0,
"source_face_index": 0
},
{
"source_url": "https://example.com/hairstyle-2.jpg",
"target_face_index": 1,
"source_face_index": 0
}
],
"model_name": "akool/hair-swap"
}
```
**Body**
```json theme={null}
{
"target_url": "https://example.com/portrait.jpg",
"images": [
"https://example.com/hairstyle.jpg"
],
"model_name": "akool/hair-swap",
"multi_shot": true
}
```
For input limits, billing, callbacks, and error codes, see the [Hair Swap V5 overview](/ai-tools-suite/swap-studio/hair-swap-v5).
```bash Images theme={null}
curl --request POST \
--url 'https://openapi.akool.com/api/open/v5/hairswap/create' \
--header 'x-api-key: ' \
--header 'Content-Type: application/json' \
--data '{
"target_url": "https://example.com/portrait.jpg",
"images": [
"https://example.com/hairstyle.jpg"
],
"target_face_index": 0,
"source_face_index": 0,
"model_name": "akool/hair-swap"
}'
```
```bash Face mappings theme={null}
curl --request POST \
--url 'https://openapi.akool.com/api/open/v5/hairswap/create' \
--header 'x-api-key: ' \
--header 'Content-Type: application/json' \
--data '{
"target_url": "https://example.com/group.jpg",
"mappings": [
{
"source_url": "https://example.com/hairstyle.jpg",
"target_face_index": 0,
"source_face_index": 0
},
{
"source_url": "https://example.com/hairstyle-2.jpg",
"target_face_index": 1,
"source_face_index": 0
}
],
"model_name": "akool/hair-swap"
}'
```
```bash Multiple views theme={null}
curl --request POST \
--url 'https://openapi.akool.com/api/open/v5/hairswap/create' \
--header 'x-api-key: ' \
--header 'Content-Type: application/json' \
--data '{
"target_url": "https://example.com/portrait.jpg",
"images": [
"https://example.com/hairstyle.jpg"
],
"model_name": "akool/hair-swap",
"multi_shot": true
}'
```
```json Images theme={null}
{
"code": 1000,
"msg": "OK",
"data": {
"list": [
{
"_id": "670000000000000000000002",
"status": 1,
"media_type": "image",
"model_name": "akool/hair-swap",
"deduction_credit": 6,
"create_time": 1791777600000,
"task_id": ""
}
],
"errors": []
}
}
```
```json Face mappings theme={null}
{
"code": 1000,
"msg": "OK",
"data": {
"list": [
{
"_id": "670000000000000000000002",
"status": 1,
"media_type": "image",
"model_name": "akool/hair-swap",
"deduction_credit": 6,
"create_time": 1791777600000,
"task_id": ""
}
],
"errors": []
}
}
```
```json Multiple views theme={null}
{
"code": 1000,
"msg": "OK",
"data": {
"list": [
{
"_id": "670000000000000000000002",
"status": 1,
"media_type": "image",
"model_name": "akool/hair-swap",
"deduction_credit": 6,
"create_time": 1791777600000,
"task_id": ""
}
],
"errors": []
}
}
```
## OpenAPI
````yaml POST /api/open/v5/hairswap/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/hairswap/create:
post:
tags:
- Hair Swap
summary: Create Task — Hair Swap
description: >-
Use images for reference-image batches or mappings for per-face
selection. When mappings is supplied it takes precedence; top-level face
indexes apply only to the images shortcut. Multi-person targets combine
mappings into one primary task and each target face can appear only
once. multi_shot=true requires a single-person target and at most 12
references (four outputs per primary task). Examples are illustrative;
replace sample assets and IDs. Authorization takes precedence when both
authentication headers are supplied.
operationId: hairswap_create
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
target_url:
type: string
description: Public target portrait image URL.
format: uri
images:
type: array
description: >-
1–50 reference URLs (at most 12 when multi_shot=true).
Supply images or mappings; mappings takes precedence.
items:
type: string
format: uri
minItems: 1
maxItems: 50
mappings:
type: array
description: >-
1–50 per-face mappings (at most 12 when multi_shot=true).
Takes precedence over images. Each target face can appear
once for a multi-person target.
items:
type: object
properties:
source_url:
type: string
description: Reference hairstyle image URL.
format: uri
target_face_index:
type: integer
description: >-
Zero-based target face index for this mapping;
defaults to 0.
minimum: 0
source_face_index:
type: integer
description: >-
Zero-based reference face index for this mapping;
defaults to 0.
minimum: 0
required:
- source_url
minItems: 1
maxItems: 50
multi_shot:
type: boolean
description: >-
Generate three additional hairstyle views; defaults to
false. Single-person targets only.
target_face_index:
type: integer
description: >-
Zero-based face index for the images shortcut; defaults to
0. When using mappings, set the index on each mappings[]
object instead.
minimum: 0
source_face_index:
type: integer
description: >-
Zero-based face index for the images shortcut; defaults to
0. When using mappings, set the index on each mappings[]
object instead.
minimum: 0
model_name:
type: string
description: Defaults to `akool/hair-swap`.
webhookUrl:
type: string
description: >-
Optional final-state callback URL; follow the [Webhook
guide](/ai-tools-suite/webhook).
format: uri
required:
- target_url
anyOf:
- required:
- mappings
- required:
- images
examples:
images:
summary: Reference images
value:
target_url: https://example.com/portrait.jpg
images:
- https://example.com/hairstyle.jpg
target_face_index: 0
source_face_index: 0
model_name: akool/hair-swap
mappings:
summary: Per-face mappings
value:
target_url: https://example.com/group.jpg
mappings:
- source_url: https://example.com/hairstyle.jpg
target_face_index: 0
source_face_index: 0
- source_url: https://example.com/hairstyle-2.jpg
target_face_index: 1
source_face_index: 0
model_name: akool/hair-swap
multiShot:
summary: Single-person multiple views
value:
target_url: https://example.com/portrait.jpg
images:
- https://example.com/hairstyle.jpg
model_name: akool/hair-swap
multi_shot: 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:
images:
summary: Reference images
value:
code: 1000
msg: OK
data:
list:
- _id: '670000000000000000000002'
status: 1
media_type: image
model_name: akool/hair-swap
deduction_credit: 6
create_time: 1791777600000
task_id: ''
errors: []
mappings:
summary: Per-face mappings
value:
code: 1000
msg: OK
data:
list:
- _id: '670000000000000000000002'
status: 1
media_type: image
model_name: akool/hair-swap
deduction_credit: 6
create_time: 1791777600000
task_id: ''
errors: []
multiShot:
summary: Single-person multiple views
value:
code: 1000
msg: OK
data:
list:
- _id: '670000000000000000000002'
status: 1
media_type: image
model_name: akool/hair-swap
deduction_credit: 6
create_time: 1791777600000
task_id: ''
errors: []
x-codeSamples:
- lang: bash
label: Reference images
source: |-
curl --request POST \
--url 'https://openapi.akool.com/api/open/v5/hairswap/create' \
--header 'x-api-key: ' \
--header 'Content-Type: application/json' \
--data '{
"target_url": "https://example.com/portrait.jpg",
"images": [
"https://example.com/hairstyle.jpg"
],
"target_face_index": 0,
"source_face_index": 0,
"model_name": "akool/hair-swap"
}'
- lang: bash
label: Per-face mappings
source: |-
curl --request POST \
--url 'https://openapi.akool.com/api/open/v5/hairswap/create' \
--header 'x-api-key: ' \
--header 'Content-Type: application/json' \
--data '{
"target_url": "https://example.com/group.jpg",
"mappings": [
{
"source_url": "https://example.com/hairstyle.jpg",
"target_face_index": 0,
"source_face_index": 0
},
{
"source_url": "https://example.com/hairstyle-2.jpg",
"target_face_index": 1,
"source_face_index": 0
}
],
"model_name": "akool/hair-swap"
}'
- lang: bash
label: Single-person multiple views
source: |-
curl --request POST \
--url 'https://openapi.akool.com/api/open/v5/hairswap/create' \
--header 'x-api-key: ' \
--header 'Content-Type: application/json' \
--data '{
"target_url": "https://example.com/portrait.jpg",
"images": [
"https://example.com/hairstyle.jpg"
],
"model_name": "akool/hair-swap",
"multi_shot": 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.