Analyze Frames - Akool open api documents

curl --request POST \
  --url https://openapi.akool.com/interface/detect-api/faceswap/analyze_frames \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "frame_urls": [
    "https://example.com/image.jpg"
  ]
}
'

{
  "success": true,
  "frame_count": 1,
  "persons": [
    {
      "person_id": "person_0",
      "index": 0,
      "face_url": "https://s3.example.com/faces/face_abc123.jpg",
      "bbox": [
        100,
        50,
        200,
        180
      ],
      "confidence": 0.95,
      "appearances": [
        {
          "timestamp": 0,
          "frame_idx": 0,
          "bbox": [
            100,
            50,
            200,
            180
          ]
        }
      ],
      "first_seen": 0,
      "last_seen": 0
    },
    {
      "person_id": "person_1",
      "index": 1,
      "face_url": "https://s3.example.com/faces/face_def456.jpg",
      "bbox": [
        300,
        60,
        400,
        190
      ],
      "confidence": 0.92,
      "appearances": [
        {
          "timestamp": 0,
          "frame_idx": 0,
          "bbox": [
            300,
            60,
            400,
            190
          ]
        }
      ],
      "first_seen": 0,
      "last_seen": 0
    }
  ]
}

POST

faceswap

analyze_frames

curl --request POST \
  --url https://openapi.akool.com/interface/detect-api/faceswap/analyze_frames \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "frame_urls": [
    "https://example.com/image.jpg"
  ]
}
'

{
  "success": true,
  "frame_count": 1,
  "persons": [
    {
      "person_id": "person_0",
      "index": 0,
      "face_url": "https://s3.example.com/faces/face_abc123.jpg",
      "bbox": [
        100,
        50,
        200,
        180
      ],
      "confidence": 0.95,
      "appearances": [
        {
          "timestamp": 0,
          "frame_idx": 0,
          "bbox": [
            100,
            50,
            200,
            180
          ]
        }
      ],
      "first_seen": 0,
      "last_seen": 0
    },
    {
      "person_id": "person_1",
      "index": 1,
      "face_url": "https://s3.example.com/faces/face_def456.jpg",
      "bbox": [
        300,
        60,
        400,
        190
      ],
      "confidence": 0.92,
      "appearances": [
        {
          "timestamp": 0,
          "frame_idx": 0,
          "bbox": [
            300,
            60,
            400,
            190
          ]
        }
      ],
      "first_seen": 0,
      "last_seen": 0
    }
  ]
}

Analyze faces in one or more images, returning a persons format optimized for face swap. Automatically deduplicates faces across multiple frames.

Request Parameters

Parameter	Type	Required	Default	Description
`frame_urls`	array	Yes	-	List of image URLs to analyze
`timestamps`	array	No	[0.0, 1.0, …]	Timestamps for each frame (seconds)
`expand_ratio`	number	No	0.3	Face crop expansion ratio (0-1)

Single Image: Each face becomes a separate person (no deduplication). Multiple Images: Same person across frames is merged into one entry.

Response Format

{
  "success": true,
  "frame_count": 3,
  "persons": [
    {
      "person_id": "person_0",
      "index": 0,
      "face_url": "https://s3.example.com/faces/face_abc123.jpg",
      "bbox": [100, 50, 200, 180],
      "confidence": 0.95,
      "appearances": [
        {"timestamp": 0.0, "frame_idx": 0, "bbox": [100, 50, 200, 180]},
        {"timestamp": 1.0, "frame_idx": 1, "bbox": [105, 52, 205, 182]}
      ],
      "first_seen": 0.0,
      "last_seen": 1.0
    }
  ]
}

Response Fields

Field	Type	Description
`success`	boolean	Whether analysis succeeded
`frame_count`	integer	Number of frames analyzed
`persons`	array	List of detected persons

Person Object

Field	Type	Description
`person_id`	string	Unique identifier (e.g., “person_0”)
`index`	integer	Sort index (left to right by x-coordinate)
`face_url`	string	Cropped face image URL
`bbox`	array	Bounding box `[x1, y1, x2, y2]` from first appearance
`confidence`	number	Detection confidence (0-1)
`appearances`	array	List of frame appearances with timestamp, frame_idx, bbox
`first_seen`	number	First appearance timestamp
`last_seen`	number	Last appearance timestamp

Examples

Example 1: Single Image Analysis

Request:

{
  "frame_urls": ["https://example.com/group_photo.jpg"]
}

Response:

{
  "success": true,
  "frame_count": 1,
  "persons": [
    {
      "person_id": "person_0",
      "index": 0,
      "face_url": "https://s3.example.com/faces/face_a1b2c3.jpg",
      "bbox": [100, 50, 200, 180],
      "confidence": 0.96,
      "appearances": [
        {"timestamp": 0.0, "frame_idx": 0, "bbox": [100, 50, 200, 180]}
      ],
      "first_seen": 0.0,
      "last_seen": 0.0
    },
    {
      "person_id": "person_1",
      "index": 1,
      "face_url": "https://s3.example.com/faces/face_d4e5f6.jpg",
      "bbox": [300, 60, 400, 190],
      "confidence": 0.94,
      "appearances": [
        {"timestamp": 0.0, "frame_idx": 0, "bbox": [300, 60, 400, 190]}
      ],
      "first_seen": 0.0,
      "last_seen": 0.0
    }
  ]
}

Example 2: Multi-Frame Analysis (Video Frames)

Request:

{
  "frame_urls": [
    "https://example.com/frame_0.jpg",
    "https://example.com/frame_1.jpg",
    "https://example.com/frame_2.jpg"
  ],
  "timestamps": [0.0, 1.0, 2.0]
}

Response:

{
  "success": true,
  "frame_count": 3,
  "persons": [
    {
      "person_id": "person_0",
      "index": 0,
      "face_url": "https://s3.example.com/faces/face_abc123.jpg",
      "bbox": [100, 50, 200, 180],
      "confidence": 0.95,
      "appearances": [
        {"timestamp": 0.0, "frame_idx": 0, "bbox": [100, 50, 200, 180]},
        {"timestamp": 1.0, "frame_idx": 1, "bbox": [105, 52, 205, 182]},
        {"timestamp": 2.0, "frame_idx": 2, "bbox": [110, 55, 210, 185]}
      ],
      "first_seen": 0.0,
      "last_seen": 2.0
    }
  ]
}

The same person appearing in all 3 frames is merged into a single person entry with multiple appearances.

Example 3: Custom Expand Ratio

Request:

{
  "frame_urls": ["https://example.com/photo.jpg"],
  "expand_ratio": 0.5
}

Error Responses

success	error	Description
false	frame_urls is required and must not be empty	Missing frame_urls
false	Failed to download image from URL	Download failed
true	(empty persons array)	No faces detected

Integration with Face Swap

import requests

# Analyze frames
response = requests.post(
    "https://openapi.akool.com/interface/detect-api/faceswap/analyze_frames",
    json={"frame_urls": ["https://example.com/target.jpg"]},
    headers={"x-api-key": "YOUR_API_KEY"}
)

result = response.json()
if result["success"]:
    for person in result["persons"]:
        face_url = person["face_url"]
        print(f"Person {person['person_id']}: {face_url}")
        # Use face_url directly in Face Swap API

Best Practices

URL Requirements: Use HTTPS, ensure publicly accessible
Multi-Frame: Use 3-10 frames for typical video clips
Expand Ratio: Use 0.5 for more facial context in face swap

Authorizations

x-api-key

string

header

required

Your API Key used for request authorization. If both Authorization and x-api-key have values, Authorization will be used first and x-api-key will be discarded.

Body

application/json

frame_urls

string<uri>[]

required

List of image URLs to analyze. Must be publicly accessible.

Single URL: Returns each face as a separate person
Multiple URLs: Automatically deduplicates faces across frames

Example:

["https://example.com/image.jpg"]

timestamps

number<float>[]

Optional timestamps for each frame (in seconds). If not provided, sequential indices (0.0, 1.0, 2.0, ...) will be used. Length should match frame_urls length.

Example:

[0, 1, 2]

expand_ratio

number<float>

default:0.3

Expansion ratio for face cropping. The face bounding box is expanded by this ratio on all sides before cropping. Higher values include more context around the face.

Required range: 0 <= x <= 1

Example:

0.3

Response

Face analysis completed successfully

success

boolean

required

Whether the analysis was successful

Example:

true

frame_count

integer

required

Number of frames that were analyzed

Example:

3

persons

object[]

required

List of detected persons. Each person contains:

Unique ID and index
Cropped face image URL
Bounding box and confidence
All appearances across frames
First and last seen timestamps

Show child attributes

Detect Faces Character Swap API Overview

​Request Parameters

​Response Format

​Response Fields

​Person Object

​Examples

​Example 1: Single Image Analysis

​Example 2: Multi-Frame Analysis (Video Frames)

​Example 3: Custom Expand Ratio

​Error Responses

​Integration with Face Swap

​Best Practices

Authorizations

Body

Response

Request Parameters

Response Format

Response Fields

Person Object

Examples

Example 1: Single Image Analysis

Example 2: Multi-Frame Analysis (Video Frames)

Example 3: Custom Expand Ratio

Error Responses

Integration with Face Swap

Best Practices