Create Task

curl --request POST \
--url 'https://openapi.akool.com/api/open/v5/hairswap/create' \
--header 'x-api-key: <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"
}'

curl --request POST \
--url 'https://openapi.akool.com/api/open/v5/hairswap/create' \
--header 'x-api-key: <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"
}'

curl --request POST \
--url 'https://openapi.akool.com/api/open/v5/hairswap/create' \
--header 'x-api-key: <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
}'

{
  "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": []
  }
}

{
  "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": []
  }
}

{
  "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": []
  }
}

POST

api

open

hairswap

create

curl --request POST \
--url 'https://openapi.akool.com/api/open/v5/hairswap/create' \
--header 'x-api-key: <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"
}'

curl --request POST \
--url 'https://openapi.akool.com/api/open/v5/hairswap/create' \
--header 'x-api-key: <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"
}'

curl --request POST \
--url 'https://openapi.akool.com/api/open/v5/hairswap/create' \
--header 'x-api-key: <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
}'

{
  "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": []
  }
}

{
  "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": []
  }
}

{
  "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": []
  }
}

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

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.

Images
Face mappings
Multiple views

Body

{
  "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

{
  "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

{
  "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.

curl --request POST \
--url 'https://openapi.akool.com/api/open/v5/hairswap/create' \
--header 'x-api-key: <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"
}'

curl --request POST \
--url 'https://openapi.akool.com/api/open/v5/hairswap/create' \
--header 'x-api-key: <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"
}'

curl --request POST \
--url 'https://openapi.akool.com/api/open/v5/hairswap/create' \
--header 'x-api-key: <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
}'

{
  "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": []
  }
}

{
  "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": []
  }
}

{
  "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": []
  }
}

Authorizations

x-api-key

string

header

required

Body

application/json

Option 1
Option 2

target_url

string<uri>

required

Public target portrait image URL.

mappings

object[]

required

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.

Required array length: 1 - 50 elements

Show child attributes

images

string<uri>[]

1–50 reference URLs (at most 12 when multi_shot=true). Supply images or mappings; mappings takes precedence.

Required array length: 1 - 50 elements

multi_shot

boolean

Generate three additional hairstyle views; defaults to false. Single-person targets only.

target_face_index

integer

Zero-based face index for the images shortcut; defaults to 0. When using mappings, set the index on each mappings[] object instead.

Required range: x >= 0

source_face_index

integer

Zero-based face index for the images shortcut; defaults to 0. When using mappings, set the index on each mappings[] object instead.

Required range: x >= 0

model_name

string

Defaults to akool/hair-swap.

webhookUrl

string<uri>

Optional final-state callback URL; follow the Webhook guide.

Response

200 - application/json

Business response. Code 1000 means the request succeeded; inspect task status or data.errors for generation/submission outcomes.

code

integer

Example:

1000

msg

string

Example:

"OK"

data

object

Show child attributes

Authentication

Face Swap

Streaming Avatar

Talking Photo

Video Translation

Face Detection

Swap Studio V5

Image Generate

Image to Video

AI Tools Suite

Request examples

Authorizations

Body

Response

​Request examples

Authorizations

Body

Response

Request examples