Documentação da API de análise facial

Envie uma imagem e receba um array faces em JSON. Cada rosto contém os recursos solicitados. Uma imagem válida sem rostos detectados retorna um array vazio.

Faça sua primeira requisição

Use seu token da API e uma imagem local. Estes exemplos solicitam apenas as caixas dos rostos, para verificar a integração com qualquer imagem compatível.

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)

Entenda a resposta

Esta resposta ilustrativa contém um rosto detectado. As coordenadas e previsões dependem da imagem; os valores de exemplo não são resultados garantidos.

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

Envie uma URL pública de imagem

Em vez de enviar um arquivo, envie url com uma imagem HTTPS pública. Endereços de rede privada e imagens não compatíveis são rejeitados.

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'

Escolha os recursos

Envie nomes separados por vírgulas em um formulário ou um array features em JSON. Omita features para solicitar todos. Pedir apenas o necessário reduz o processamento.

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

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

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

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

{
  "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
        }
      }
    }
  ]
}

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

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

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

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

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

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

As saídas dos modelos são estimativas. As classes fazem parte do contrato legado da API e não estabelecem a identidade de uma pessoa.

Formatos, limites e erros

São aceitas imagens JPEG, PNG, WebP e BMP de até 4 MiB. Requisições JSON podem conter uma imagem em base64. Use o token da sua conta; a demonstração anônima possui limites próprios.

Requisições bem-sucedidas contam uma vez, inclusive imagens sem rostos. Falhas não contam. Os limites mensais reiniciam em UTC; X-Quota-Limit, X-Quota-Remaining e X-Quota-Reset indicam a cota atual.