Face analysis API documentation

Send an image and receive a JSON faces array. Each face contains the features you requested. A valid image without detected faces returns an empty array.

Make your first request

Use your API token and a local image file. These examples request only face bounding boxes, so you can verify the integration with any supported image.

Sign in to see your own token in the examples. Otherwise replace TOKEN with the token from your dashboard.

cURL

curl --request POST 'https://www.rosto.io/api/v1/features' \
  --header 'Authorization: Bearer TOKEN' \
  --form 'features=bounds' \
  --form 'image=@photo.jpg'

Python 3

import requests

with open("photo.jpg", "rb") as image_file:
    response = requests.post(
        "https://www.rosto.io/api/v1/features",
        headers={"Authorization": "Bearer TOKEN"},
        data={"features": "bounds"},
        files={"image": image_file},
        timeout=90,
    )
response.raise_for_status()
print(response.json())

Ruby

require 'json'
require 'faraday'

connection = Faraday.new('https://www.rosto.io') do |http|
  http.request :multipart
  http.adapter Faraday.default_adapter
end
response = connection.post('/api/v1/features') do |request|
  request.headers['Authorization'] = 'Bearer TOKEN'
  request.body = {
    features: 'bounds',
    image: Faraday::UploadIO.new('photo.jpg', 'image/jpeg')
  }
end
puts JSON.parse(response.body)

Understand the response

This illustrative response has one detected face. Coordinates and predictions depend on the uploaded image; example values are not guaranteed results.

{
  "faces": [
    {"bounds": {"left": 35, "top": 77, "right": 221, "bottom": 263}}
  ]
}

Send a public image URL

Instead of uploading a file, send url pointing to a publicly accessible HTTPS image. Private network addresses and unsupported images are rejected.

curl --request POST 'https://www.rosto.io/api/v1/features' \
  --header 'Authorization: Bearer TOKEN' \
  --data-urlencode 'features=bounds,landmarks' \
  --data-urlencode 'url=https://example.com/photo.jpg'

Choose features

Send comma-separated feature names with form data, or a features array with JSON. Omit features to request them all. Requesting only what you need reduces model work.

bounds · Face detection

Locate faces and return their bounding boxes.

{
  "faces": [
    {
      "bounds": {
        "left": 35,
        "top": 77,
        "right": 221,
        "bottom": 263
      }
    }
  ]
}

landmarks · Facial landmarks

Get contour points for the eyes, nose, mouth and jaw.

{
  "faces": [
    {
      "landmarks": {
        "left_eye_center": {
          "x": 160,
          "y": 132
        },
        "right_eye_center": {
          "x": 99,
          "y": 132
        },
        "mouth_center": {
          "x": 129,
          "y": 203
        }
      }
    }
  ]
}

age · Age estimate

Return the model’s age estimate for each face.

{
  "faces": [
    {
      "age": 20
    }
  ]
}

gender · Visual presentation

Legacy man/woman scores describe visual presentation, not gender identity.

{
  "faces": [
    {
      "gender": {
        "value": "man",
        "probability": 0.84,
        "classes": {
          "man": 0.84,
          "woman": 0.16
        }
      }
    }
  ]
}

emotion · Expression scores

Return model scores for seven facial-expression categories.

{
  "faces": [
    {
      "emotion": {
        "value": "neutral",
        "probability": 0.71,
        "classes": {
          "angry": 0.08,
          "disgust": 0.0,
          "fear": 0.02,
          "happy": 0.02,
          "neutral": 0.71,
          "sad": 0.16,
          "surprise": 0.0
        }
      }
    }
  ]
}

ethnicity · Legacy class scores

The ethnicity field exposes the existing model’s class scores.

{
  "faces": [
    {
      "ethnicity": {
        "value": "white",
        "probability": 0.9,
        "classes": {
          "asian": 0.03,
          "black": 0.02,
          "indian": 0.05,
          "white": 0.9
        }
      }
    }
  ]
}

glasses · Glasses detection

Distinguish glasses, swimming goggles and no glasses.

{
  "faces": [
    {
      "glasses": {
        "value": "not-using-glasses",
        "probability": 0.95,
        "classes": {
          "not-using-glasses": 0.95,
          "using-glasses": 0.04,
          "swimming-goggles": 0.01
        }
      }
    }
  ]
}

smile · Smile detection

Return a smile prediction and its probability.

{
  "faces": [
    {
      "smile": {
        "is_smiling": false,
        "probability": 0.2
      }
    }
  ]
}

hair · Hair segmentation

Get scalp-hair contours and the dominant hair color.

{
  "faces": [
    {
      "hair": {
        "polygons": [
          [
            {
              "x": 40,
              "y": 30
            },
            {
              "x": 75,
              "y": 10
            },
            {
              "x": 110,
              "y": 35
            }
          ]
        ],
        "color": {
          "name": "black",
          "hex": "#131218"
        }
      }
    }
  ]
}

pose · Head pose

Measure yaw, roll and pitch angles.

{
  "faces": [
    {
      "pose": {
        "x_roll": -5,
        "y_pitch": -5,
        "z_yaw": 6
      }
    }
  ]
}

quality · Image quality

Check blur and exposure before using an image.

{
  "faces": [
    {
      "blur": {
        "is_blurry": false
      },
      "exposure": {
        "level": "balanced"
      }
    }
  ]
}

Model outputs are estimates. Class labels are part of the legacy API contract and do not establish a person’s identity.

Formats, limits and errors

JPEG, PNG, WebP and BMP images are supported, up to 4 MiB. JSON requests may contain a base64 image string. Use your own account token; the anonymous website demo has separate rate limits.

HTTP statusMeaning
200Successful analysis. A valid image can contain zero faces.
400Invalid image, feature selection or URL. Read the JSON message.
401Missing or invalid API token.
429Monthly quota or request rate exceeded. Check the response headers.
502 / 503 / 504Service temporarily unavailable. Retry later.

Successful requests count once, including images with no detected faces. Failed requests do not count. Monthly quotas reset in UTC; X-Quota-Limit, X-Quota-Remaining and X-Quota-Reset describe the current allowance.