> ## 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 Head Swap V5.
```
POST https://openapi.akool.com/api/open/v5/headswap/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. |
Analyze the source video with media\_type=video and type=head, wait for status=3 and track\_manifest\_url, then pass that analysis \_id as analyze\_id. Use the identical target\_url and distinct mappings\[].obj\_id values from analysis\_result.media.
**Body Attributes**
| **Parameter** | **Type** | **Required** | **Description** |
| - | - | - | - |
| media\_type | String | true | Always `video`. |
| target\_url | String | true | Public source video URL; must match the completed analysis. |
| analyze\_id | String | true | Completed head analysis ID. |
| mappings | Array | true | 1–5 objects pairing detected people with reference images. |
| mappings\[].obj\_id | Integer | true | Person ID from the analysis result. |
| mappings\[].img\_url | String | true | Reference head image URL. |
| model\_name | String | false | Defaults to `akool-premium`. |
| resolution | String | false | `480p` or `720p`; uses the selected model default, otherwise `480p`. |
| prompt | String | false | Optional generation instructions, up to 5000 characters. |
| 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}
{
"media_type": "video",
"target_url": "https://example.com/source.mp4",
"analyze_id": "670000000000000000000001",
"mappings": [
{
"obj_id": 0,
"img_url": "https://example.com/head.jpg"
}
],
"model_name": "akool-premium",
"resolution": "480p",
"keep_original_sound": true,
"prompt": "Preserve the source scene."
}
```
For input limits, billing, callbacks, and error codes, see the [Head Swap V5 overview](/ai-tools-suite/swap-studio/head-swap-v5).
```bash Head video theme={null}
curl --request POST \
--url 'https://openapi.akool.com/api/open/v5/headswap/create' \
--header 'x-api-key: ' \
--header 'Content-Type: application/json' \
--data '{
"media_type": "video",
"target_url": "https://example.com/source.mp4",
"analyze_id": "670000000000000000000001",
"mappings": [
{
"obj_id": 0,
"img_url": "https://example.com/head.jpg"
}
],
"model_name": "akool-premium",
"resolution": "480p",
"keep_original_sound": true,
"prompt": "Preserve the source scene."
}'
```
```json Head video theme={null}
{
"code": 1000,
"msg": "OK",
"data": {
"list": [
{
"_id": "670000000000000000000002",
"status": 1,
"media_type": "video",
"model_name": "akool-premium",
"deduction_credit": 6,
"create_time": 1791777600000,
"task_id": ""
}
],
"errors": []
}
}
```
## OpenAPI
````yaml POST /api/open/v5/headswap/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/headswap/create:
post:
tags:
- Head Swap
summary: Create Task — Head Swap
description: >-
Analyze the source video with media_type=video and type=head, wait for
status=3 and track_manifest_url, then pass that analysis _id as
analyze_id. Use the identical target_url and distinct mappings[].obj_id
values from analysis_result.media. Examples are illustrative; replace
sample assets and IDs. Authorization takes precedence when both
authentication headers are supplied.
operationId: headswap_create
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
media_type:
type: string
description: Always `video`.
enum:
- video
target_url:
type: string
description: Public source video URL; must match the completed analysis.
format: uri
analyze_id:
type: string
description: Completed head analysis ID.
pattern: ^[a-fA-F0-9]{24}$
mappings:
type: array
description: 1–5 objects pairing detected people with reference images.
items:
type: object
properties:
obj_id:
type: integer
description: Person ID from the analysis result.
minimum: 0
img_url:
type: string
description: Reference head image URL.
format: uri
required:
- obj_id
- img_url
minItems: 1
maxItems: 5
model_name:
type: string
description: Defaults to `akool-premium`.
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
prompt:
type: string
maxLength: 5000
description: Optional generation instructions, up to 5000 characters.
required:
- media_type
- target_url
- analyze_id
- mappings
examples:
headVideo:
summary: Video head replacement
value:
media_type: video
target_url: https://example.com/source.mp4
analyze_id: '670000000000000000000001'
mappings:
- obj_id: 0
img_url: https://example.com/head.jpg
model_name: akool-premium
resolution: 480p
keep_original_sound: true
prompt: Preserve the source scene.
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:
headVideo:
summary: Video head replacement
value:
code: 1000
msg: OK
data:
list:
- _id: '670000000000000000000002'
status: 1
media_type: video
model_name: akool-premium
deduction_credit: 6
create_time: 1791777600000
task_id: ''
errors: []
x-codeSamples:
- lang: bash
label: Video head replacement
source: |-
curl --request POST \
--url 'https://openapi.akool.com/api/open/v5/headswap/create' \
--header 'x-api-key: ' \
--header 'Content-Type: application/json' \
--data '{
"media_type": "video",
"target_url": "https://example.com/source.mp4",
"analyze_id": "670000000000000000000001",
"mappings": [
{
"obj_id": 0,
"img_url": "https://example.com/head.jpg"
}
],
"model_name": "akool-premium",
"resolution": "480p",
"keep_original_sound": true,
"prompt": "Preserve the source scene."
}'
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.