Sign in

v1

latestOpenAPI 3.0.32026-07-26214565.6 KB
Face Detection

Analyze Frames for Face Swap

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
post/faceswap/analyze_frames

Request body

frame_urlsstring[] 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
timestampsnumber[]

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_rationumber 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.

Example request

{
  "frame_urls": [
    "https://example.com/image.jpg"
  ],
  "timestamps": [
    0,
    1,
    2
  ],
  "expand_ratio": 0.3
}

Response

Face analysis completed successfully

successboolean required

Whether the analysis was successful

frame_countinteger required

Number of frames that were analyzed

Example response

{
  "success": true,
  "frame_count": 3,
  "persons": [
    {
      "person_id": "person_0",
      "face_url": "https://s3.example.com/faces/face_abc123.jpg",
      "bbox": [
        100,
        50,
        200,
        180
      ],
      "confidence": 0.95,
      "appearances": [
        {
          "bbox": [
            100,
            50,
            200,
            180
          ]
        }
      ],
      "last_seen": 2
    }
  ]
}
All 21 operations