---
title: "Analyze Frames for Face Swap"
method: POST
path: "/faceswap/analyze_frames"
tags: ["Face Detection"]
---

# Analyze Frames for Face Swap

`POST /faceswap/analyze_frames`

Unified face analysis endpoint for single or multiple frame images. Returns a `persons` format optimized for face swap operations.

**Key Features**:
- Supports both single image and multiple frame images
- Automatic person deduplication across frames (for multi-frame input)
- Returns cropped face image URLs ready for face swap
- Tracks person appearances across frames with timestamps

**Behavior**:
- **Single Image**: Each detected face is returned as a separate person (no deduplication)
- **Multiple Images**: Faces are matched across frames using embeddings, same person appears once with all appearances listed

**Use Cases**:
- Prepare faces for Face Swap API
- Analyze video frames for person tracking
- Extract face thumbnails from images

## Request body

- AnalyzeFramesRequest
  - `frame_urls` string[], 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
  - `timestamps` number[] — 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.
  - `expand_ratio` number, float — 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.

## Response `200`

Face analysis completed successfully

- AnalyzeFramesResponse
  - `success` boolean, required — Whether the analysis was successful
  - `frame_count` integer, required — Number of frames that were analyzed
  - `persons` PersonInfo[], 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
    - `person_id` string, required — Unique identifier for this person (e.g., "person_0", "person_1")
    - `index` integer, required — Sort index based on x-coordinate (left to right ordering)
    - `face_url` string, uri, required — URL of the cropped face image stored in cloud storage
    - `bbox` integer[], required — Face bounding box coordinates [x1, y1, x2, y2] from first appearance
    - `confidence` number, float, required — Detection confidence score (0-1)
    - `appearances` PersonAppearance[], required — List of all appearances of this person across frames
      - `timestamp` number, float, required — Timestamp when this appearance was detected (in seconds)
      - `frame_idx` integer, required — Frame index where this appearance was detected
      - `bbox` integer[], required — Bounding box coordinates [x1, y1, x2, y2]
    - `first_seen` number, float, required — Timestamp of first appearance (in seconds)
    - `last_seen` number, float, required — Timestamp of last appearance (in seconds)

## Other responses

- `400` — Bad request - Invalid input parameters
- `500` — Internal server error

---

[API](https://skmtc.dev/akool/apis/face-detection-api.md) · [All operations](https://skmtc.dev/akool/apis/face-detection-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/akool/face-detection-api/revisions/ce2ff5679949/schema)