Skip to main content
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

ParameterTypeRequiredDefaultDescription
frame_urlsarrayYes-List of image URLs to analyze
timestampsarrayNo[0.0, 1.0, …]Timestamps for each frame (seconds)
expand_rationumberNo0.3Face 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

FieldTypeDescription
successbooleanWhether analysis succeeded
frame_countintegerNumber of frames analyzed
personsarrayList of detected persons

​
Person Object

FieldTypeDescription
person_idstringUnique identifier (e.g., “person_0”)
indexintegerSort index (left to right by x-coordinate)
face_urlstringCropped face image URL
bboxarrayBounding box [x1, y1, x2, y2] from first appearance
confidencenumberDetection confidence (0-1)
appearancesarrayList of frame appearances with timestamp, frame_idx, bbox
first_seennumberFirst appearance timestamp
last_seennumberLast 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

successerrorDescription
falseframe_urls is required and must not be emptyMissing frame_urls
falseFailed to download image from URLDownload 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