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.
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 status | Meaning |
|---|---|
200 | Successful analysis. A valid image can contain zero faces. |
400 | Invalid image, feature selection or URL. Read the JSON message. |
401 | Missing or invalid API token. |
429 | Monthly quota or request rate exceeded. Check the response headers. |
502 / 503 / 504 | Service 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.