Skip to main content

​
Endpoint

GET https://openapi.akool.com/api/open/v4/headswap/analyze/detail?_id={{analysis_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 Submit Person Analysis

​
Response Attributes

ParameterTypeDescription
codeIntegerBusiness status code (1000 = success)
msgStringStatus message
dataObjectSame shape as analyze submit response when successful
- _idStringAnalysis record id
- statusInteger1 queue, 2 processing, 3 completed, 4 failed
- progressNumberApproximate 0–100
- analysis_resultObject | nullWhen status is 3, contains detection output (see below)
- error_reasonStringFailure or status text
- error_codeNumberError code if any

​
analysis_result (when ready)

ParameterTypeDescription
detected_objectsNumberDetected person count (if returned)
mediaArrayList of detected subjects
- obj_idNumberZero-based id — use in mappings[].obj_id when creating a task
- img_urlStringPreview image URL for that person in the source video
- media_typeStringMedia type label (e.g. images)
video_infoObjectOptional source metadata
- widthNumberFrame width (px)
- heightNumberFrame height (px)
- fpsNumberFrames per second
- frame_countNumberTotal frames
Extra keys inside analysis_result may exist for forward compatibility.

​
Example

​
Request

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

​
Response (analysis completed)

{
  "code": 1000,
  "msg": "OK",
  "data": {
    "_id": "6a066d03625746c797390f55",
    "create_time": 1778806019014,
    "uid": 101400,
    "team_id": "6805fb69e92d9edc7ca0b409",
    "video_url": "https://example.com/videos/source.mp4",
    "type": "head",
    "status": 3,
    "task_id": "6a066d022872921bde86b72f",
    "analysis_result": {
      "detected_objects": 3,
      "media": [
        {
          "media_type": "images",
          "obj_id": 0,
          "img_url": "https://example.com/previews/subject_0.png"
        }
      ],
      "video_info": {
        "width": 1916,
        "height": 1082,
        "fps": 30,
        "frame_count": 450
      }
    },
    "progress": 100,
    "error_reason": "success",
    "error_code": 0
  }
}

​
Analysis Status

StatusDescription
1In queue — analysis_result may be empty
2Processing — keep polling
3Completed — use analysis_result.media for obj_id
4Failed

​
Important Notes

  • Poll until status is 3 or 4 before creating a head swap task (unless your product flow allows otherwise).
  • Wrong _id or no team access may yield not-found style errors (e.g. 1014 / Resource not found depending on environment).
  • mappings[].img_url at task creation is your reference face image; it does not have to match the analysis preview URL, but each obj_id must match an entry from media.