Jump to content

FaceHub API


Welcome to the FaceHub API Reference. If you're new to FaceHub, create an account and follow this guide to get started.

Endpoints

All calls to the API need to start with the appropriate base URL:

GET or POST https://facehub.net/api

For Enterprise accounts with their own endpoint, please contact your account manager for more information.

Authentication

To access the API, you need to get the API Key. It is issued free of charge after consideration of the application. Write an email to api@facehub.net

Scoring by Scout AI

POST https://facehub.net/api/data/tools/scoring


Send a photo of the person to get a rating from a Scout AI. The more points you get, the more chances you have to build a career in modeling. For a more accurate assessment, send up to 5 photos of one person.

Name Type Description
key string Authorization API key
images[] file Up to 5 image files (.png or .jpg)

Response:

Name Type Description
status int 0 — failure or 1 — success
faces int Number of faces found
age int Age of face in the photo
gender int Gender of face in the photo
score int Model scores from 0 to 1000

Search by Photo

POST https://facehub.net/api/data/tools/similar


Send a face photo and get a list of the most similar models or photos.

Name Type Description
key string Authorization API key
images[] file 1 image file (.png or .jpg)

Response:

Name Type Description
status int 0 — failure or 1 — success
faces int Number of faces found
faces int Most similar faces
photos int Most similar photos

Faces

GET https://facehub.net/api/data/faces


Get information on the faces using filter by parameters.

Name Type Description
key string Authorization API key
perPage int Faces per page
sortDir string asc — ascending, desc — descending
agency_id int ID of agency that the face belongs to
gender int 0 — female, 1 — male
height int Required height (in centimeters) of faces
bust int Required bust (in centimeters) of faces
waist int Required waist (in centimeters) of faces
hips int Required hips (in centimeters) of faces
shoes int Required shoes size of faces
eyes string Required eye color
hair string Required hair color

Response:

Name Type Description
page int Current page number
perPage int Number of faces per page
totalResults int How many faces match the request parameters
totalPages int How many pages do all the results take up

Agencies

GET https://facehub.net/api/data/agencies


Get information on agencies using filter by parameters

Name Type Description
key string Authorization API key
perPage int Agencies per page
page int Current page number
sortDir string asc — ascending, desc — descending
title string Required title of agency
type int 1 — for get only mother agency
genders int 0 — only female, 1 — only male
language string Required work language
male_count int Required number of male faces
female_count int Required number of female faces

Reviews

GET https://facehub.net/api/data/reviews


Get list of reviews

Name Type Description
key string Authorization API key
perPage int Agencies per page
page int Current page number
sortDir string asc — ascending, desc — descending
agency_id string Required title of agency
author string Agent or face
type string neutral, positive, negative

Errors

Code Description
1S290/A The IP address that is sending the request has been banned from the community. This may happen automatically if the IP Address has repeatedly sent many requests with invalid API keys.
1S290/D The IP address that is sending the request has sent multiple requests with an invalid API key and so is prevented from sending any more requests for several minutes.
2S290/6 No API key or OAuth access token was sent in the request.
2S290/8 The API key was valid, but is configured to only be valid for requests coming from certain IP addresses and IP address the request was sent from is not in the allowed list.
2S290/B The API key was valid, but it is not configured to be used as URL authentication and must be used in AUTHORIZATION headers.
3S290/7 The API key was valid, but it is not configured to be used as URL authentication and must be used in AUTHORIZATION headers.
2S290/9 The API key sent in the request is not valid.
3S290/3 An X-IPS-Language header was sent in the request (which can be used to specify a language ID for the response), but its value was not valid.
3S290/4 The endpoint the request was sent to does not exist (the first level contains an invalid character, only alphanumerics are acceptable).
2S290/1 The endpoint the request was sent to does not exist (the first level contains an invalid character, only alphanumerics are acceptable).
2S291/1 The endpoint the request was sent to does not exist (the URL contains too many levels).
2S291/3 The API key does not have permission to access the requested endpoint.
3S291/2 The endpoint the request was sent to does not exist - the HTTP request method may be incorrect (for example, sending a GET rather than a POST).
3S290/9 The OAuth access token sent in the request is not valid.
1S290/E The OAuth access token sent in the request was valid but has expired.
3S290/B The OAuth access token has not been authorised to access any scopes.

Conventions

These are principles that describe how all API methods work.

  • Trailing slashes are ignored: /transmissions is equivalent to /transmissions/.
  • URL paths, query parameter names and field names are case sensitive.
  • URL paths use lower case, with dashes separating words.
  • Query parameters and JSON fields use lower case.
  • The HTTP status indicates whether an operation failed or succeeded.
  • All APIs return standard HTTP error code formats.
  • Unexpected query parameters and request body fields are ignored.
  • Our JSON number type is bounded to a signed 32-bit integer.
×