Create Task

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

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

POST

api

open

headswap

create

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

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

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

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

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

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

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

Authorizations

x-api-key

string

header

required

Body

application/json

media_type

enum<string>

required

Always video.

Available options:

video

target_url

string<uri>

required

Public source video URL; must match the completed analysis.

analyze_id

string

required

Completed head analysis ID.

Pattern: ^[a-fA-F0-9]{24}$

mappings

object[]

required

1–5 objects pairing detected people with reference images.

Required array length: 1 - 5 elements

Show child attributes

model_name

string

Defaults to akool-premium.

resolution

enum<string>

480p or 720p; uses the selected model default, otherwise 480p.

Available options:

480p,

720p

keep_original_sound

boolean

Keep source video audio; defaults to true. Applies to video requests.

webhookUrl

string<uri>

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

prompt

string

Optional generation instructions, up to 5000 characters.

Maximum string length: 5000

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