Skip to main content

​
Endpoint

GET https://openapi.akool.com/api/open/v4/headswap/task/detail?_id={{task_id}}

​
Request Headers

ParameterValueDescription
x-api-keyAPI KeyRequest authorization. Get Token for Bearer alternative.
AuthorizationBearer {token}Optional Bearer token

​
Query Parameters

ParameterTypeRequiredDescription
_idStringtrue_id returned from Create Head Swap Task
You can only query tasks that belong to the authenticated team.

​
Response Attributes

ParameterTypeDescription
codeIntegerBusiness status code (1000 = success)
msgStringStatus message
dataObjectTask detail
- _idStringTask id
- uidIntegerUser id
- team_idStringTeam id
- source_video_urlStringSource video URL
- create_timeLongCreation time (ms)
- statusInteger1 queue, 2 processing, 3 completed, 4 failed
- video_durationNumberDuration in seconds
- resolutionStringOutput resolution
- deduction_durationNumberBilling-related duration metric (meaning per platform agreement)
- video_urlString | nullOutput video URL when completed; may be empty while processing
- progressNumberApproximate 0–100
- priorityNumberPriority-related value if returned
- task_idStringInternal processing id
- error_reasonStringFailure reason when failed
- error_codeNumberFailure code when failed
- file_nameStringOutput file name
- model_nameStringModel id

​
Example

​
Request

curl --location 'https://openapi.akool.com/api/open/v4/headswap/task/detail?_id=6a066dc58570ecbf64f761a5' \
--header 'x-api-key: {{API Key}}'

​
Response (task completed)

{
  "code": 1000,
  "msg": "OK",
  "data": {
    "_id": "6a066dc58570ecbf64f761a5",
    "uid": 101400,
    "team_id": "6805fb69e92d9edc7ca0b409",
    "source_video_url": "https://example.com/videos/source.mp4",
    "create_time": 1778806213962,
    "status": 3,
    "video_duration": 10,
    "resolution": "720p",
    "deduction_duration": 15,
    "video_url": "https://example.com/output/result.mp4",
    "progress": 100,
    "priority": 9,
    "task_id": "6a066dc52872921bde86b745",
    "file_name": "Headswap_1778806213962.mp4",
    "model_name": "akool-premium"
  }
}

​
Response (still processing)

While status is 1 or 2, video_url may be empty. Keep polling or rely on webhookUrl from Create Head Swap Task.

​
Task Status

StatusDescription
1In queue
2Processing
3Completed — use video_url for the rendered file
4Failed — inspect error_reason / error_code if present

​
Important Notes

  • Use the _id from the create-task response as the _id query parameter here (not the analysis record id).
  • Download the output promptly; hosted URLs may expire per platform policy.
  • Other status values may appear as the API evolves — confirm with support if you encounter unexpected codes.