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
    }
  ]
}

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

Authentication

Face Swap

Streaming Avatar

Talking Photo

Video Translation

Face Detection

Character Swap

Image Generate

Image to Video

Head Swap

AI Tools Suite

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

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