Skip to main content
video_url must match the URL used in Submit Person Analysis. Each obj_id must exist in analysis_result.media for that analysis.

​
Endpoint

POST https://openapi.akool.com/api/open/v4/headswap/task/create

​
Request Headers

ParameterValueDescription
x-api-keyAPI KeyRequest authorization. If both Authorization and x-api-key are set, platform rules determine precedence.
AuthorizationBearer {token}Optional Bearer token. Get Token
Content-Typeapplication/jsonRequired

​
Body Attributes

ParameterTypeRequiredDescription
video_urlStringtrueIdentical source video URL as used in analysis
mappingsArraytrueAt least 1 object, at most 5
- obj_idNumbertrueSubject id from analysis_result.media[].obj_id
- img_urlStringtrueSingle reference face image URL (http / https) for that obj_id
model_nameStringtrueModel id — see Model names below
resolutionStringtrueOutput resolution: 480p or 720p
template_idStringfalseTemplate id when enabled for your tenant
keep_original_soundBooleanfalseKeep source audio (default true)
webhookUrlStringfalseHTTPS recommended; final-state callback (format per platform / support)

​
Model names

ValueDescription
akool-premiumHead swap generation model
If the account does not support the model, you may receive 1003 with a message such as Your current account does not support this feature.

​
Response Attributes

ParameterTypeDescription
codeIntegerBusiness status code (1000 = success)
msgStringStatus message
dataObjectCreated task
- _idStringTask id — use with Get Head Swap Task Detail
- create_timeLongCreation time (ms)
- uidIntegerUser id
- team_idStringTeam id
- video_durationNumberAssociated video duration (seconds)
- task_idStringInternal processing id
- resolutionStringOutput resolution
- statusIntegerUsually 1 (queue) when created
- deduction_lock_durationNumberPre-hold / lock value (billing semantics per agreement)
- model_nameStringModel used
- file_nameStringOutput file name (platform-generated)
- video_urlnullOften null at create time; poll Get Head Swap Task Detail for the result URL

​
Example

​
Request Body

{
  "video_url": "https://example.com/videos/source.mp4",
  "mappings": [
    {
      "obj_id": 0,
      "img_url": "https://example.com/faces/reference.jpeg"
    }
  ],
  "model_name": "akool-premium",
  "resolution": "720p",
  "keep_original_sound": true,
  "webhookUrl": "https://example.com/your-webhook"
}

​
Request

curl --location 'https://openapi.akool.com/api/open/v4/headswap/task/create' \
--header 'x-api-key: {{API Key}}' \
--header 'Content-Type: application/json' \
--data '{
  "video_url": "https://example.com/videos/source.mp4",
  "mappings": [
    {
      "obj_id": 0,
      "img_url": "https://example.com/faces/reference.jpeg"
    }
  ],
  "model_name": "akool-premium",
  "resolution": "720p",
  "keep_original_sound": true,
  "webhookUrl": "https://example.com/your-webhook"
}'

​
Response

{
  "code": 1000,
  "msg": "OK",
  "data": {
    "_id": "6a066dc58570ecbf64f761a5",
    "create_time": 1778806213962,
    "uid": 101400,
    "team_id": "6805fb69e92d9edc7ca0b409",
    "video_duration": 10,
    "task_id": "6a066dc52872921bde86b745",
    "resolution": "720p",
    "status": 1,
    "deduction_lock_duration": 100,
    "model_name": "akool-premium",
    "file_name": "Headswap_1778806213962.mp4",
    "video_url": null
  }
}

​
Important Notes

  • More than 5 mappings may return an error such as: Up to 5 characters can be replaced at one time.
  • Credits are validated on create; insufficient balance often returns 1104.
  • Store data._id and poll Get Head Swap Task Detail (or wait for webhookUrl) for the output video_url.