Skip to main content
Use the same video_url later when creating the head swap task. Analysis and task creation must refer to the same source video URL.

​
Endpoint

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

​
Request Headers

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

​
Body Attributes

ParameterTypeRequiredDescription
video_urlStringtruePublicly accessible source video URL (http or https)
typeStringtrueFor head swap, always head

​
Response Attributes

ParameterTypeDescription
codeIntegerBusiness status code (1000 = success)
msgStringStatus message (often Analyze success on success)
dataObjectAnalysis record
- _idStringAnalysis record id — use with Get Analysis Result
- create_timeLongCreation time (ms)
- uidIntegerUser id
- team_idStringTeam id
- video_urlStringSource video URL
- typeStringhead
- statusInteger1 queue, 2 processing, 3 completed, 4 failed
- task_idStringInternal processing id (support / tickets)
- progressNumberApproximate progress 0–100
- analysis_resultObject | nullUsually null right after submit; populated when completed
- error_reasonStringError description if any
- error_codeNumberError code if any

​
Example

​
Request Body

{
  "video_url": "https://example.com/videos/source.mp4",
  "type": "head"
}

​
Request

curl --location 'https://openapi.akool.com/api/open/v4/headswap/analyze' \
--header 'x-api-key: {{API Key}}' \
--header 'Content-Type: application/json' \
--data '{
  "video_url": "https://example.com/videos/source.mp4",
  "type": "head"
}'

​
Response

{
  "code": 1000,
  "msg": "Analyze success",
  "data": {
    "_id": "6a066d03625746c797390f55",
    "create_time": 1778806019014,
    "uid": 101400,
    "team_id": "6805fb69e92d9edc7ca0b409",
    "video_url": "https://example.com/videos/source.mp4",
    "type": "head",
    "status": 1,
    "task_id": "6a066d022872921bde86b72f",
    "progress": 0
  }
}

​
Important Notes

  • Save data._id and poll Get Analysis Result until status is 3 or 4.
  • Video length must be within the documented duration window (about 3–20 seconds).
  • Invalid video_url, wrong type, or service issues return non-1000 code / descriptive msg.