API

For using the API you need the UI Faces key.

We’re not issuing new API keys at this moment. Join the newsletter if you want to be notified when API keys become available again.

URL
https://api.uifaces.co
The old API url https://uifaces.co/api will be deprecated soon
Authentication parameterUsage exampleDescription
X-API-KEYX-API-KEY: [YOUR-UIFACES-KEY]’Add your API key via the HTTP headers
Query string parameterUsage exampleDescription
limit?limit=10Number of avatars (30 max per call, default is 10)
gender[]?gender[]=male
?gender[]=female		Filter by gender: male or female
from_age?from_age=18Set minimum age
to_age?to_age=40Set maximum age
hairColor[]?hairColor[]=black
?hairColor[]=brown
?hairColor[]=blond
?hairColor[]=red		Filter by hair color
emotion[]?emotion[]=happiness
?emotion[]=neutral		Filter by emotion
provider[]?provider[]=9 (Unsplash.com)
?provider[]=7 (Pexels.com)
?provider[]=5 (RandomUser.me)
?provider[]=13 (Generated.photos)
?provider[]=8 (Donated)		Premium Get avatars by provider ID
popular?popularPremium Order avatars by popularity
offset?offset=10Premium Skip number of avatars from the result
random?randomDeprecated (results are random by default)

Fetch() API Example

fetch('https://uifaces.co/api', {
	method: 'GET',
	headers: {
	  'X-API-KEY': [YOUR-UIFACES-KEY],
	  'Accept': 'application/json',
	  'Cache-Control': 'no-cache'
	}
})

cURL Example

curl 
	--header Cache-Control: no-cache 
	--header Accept: application/json 
	--header X-API-KEY: [YOUR-UIFACES-KEY] 
	https://uifaces.co/api

Error Response Example

{ "error" : "Maximum allowed number of results exceeded." }