Welcome to the Face Studio API, your portal to seamless integration of advanced face generation capabilities into your application or workflow. For a Quick Start guide, check out the introductory Face Studio - API Access page. The following a is more comprehensive manual to the Face Studio API.
The Face Studio API is designed with simplicity in mind, utilizing straightforward RESTful architecture that relies exclusively on GET parameters. We believe that simplicity is key to fostering creativity, making AI-generated faces accessible to developers of all skill levels.
Unlocking the Power of Face Generation. Depending on your plan, you'll have access to a range of parameters tailored to your needs. Basic users, our free-tier enthusiasts, can harness fundamental parameters such as gender, age, ethnicity, and image format/resolution to generate captivating faces. However, for those seeking ultimate precision and control, our Professional tier and above unlock access to the full spectrum of advanced parameters. Take a look at Usage Plans to see options that are available to you.
Secure and User-Friendly Authentication.
Security is paramount, and our API leverages robust Token authentication to ensure that your data remains protected. Each user with a verified email can request up to five API keys, granting the flexibility to manage multiple projects effortlessly. Create an account and login to request your API key; for more details, check out the instructions for requesting an API key below.
Rate Limits Tailored to Your Needs. To ensure fair usage and optimal performance, we implement rate limits that vary depending on your plan access level. We believe in providing flexibility to accommodate your specific requirements while maintaining a responsive and reliable service. For a detailed overview of rate limits, check out the Rate Limit Table below.
Ready to dive into the world of AI-generated faces? Join our community, explore our API, and unlock the potential of creative face generation with Face Studio. Get started today!
Authentication
To access the Face Studio API, it is important to authenticate your requests using an API key. This key serves as your unique identifier and provides secure access to our services.
Anonymous Requests
The Face Studio API is designed with simplicity in mind. While authentication is recommended, it is not strictly mandatory. Here are minimal examples, in CURL and python, to illustrate how simple and easy it is to access the API:
CURL
curl https://facestud.io/v1/generate -o face.jpg
Python
import requests
response = requests.get('https://facestud.io/v1/generate')
# Check if request was successful
if response.status_code == 200:
# Save the image
with open('face.jpg', 'wb') as f:
f.write(response.content)
else:
print(f'Failed to retrieve image: {response.status_code}')
As you can see, these are unauthenticated requests; therefore, they will be subjected to the highest level of throttling. The next section will show you how to authenticate your requests to access higher rate limits and advanced features.
Token Authentication
Face Studio API uses the Token Authorization scheme for HTTP-based authentication. Token Authorization allows secure API access by validating a token passed in HTTP headers. Therefore, to authenticate your requests, you simply include your API key in the HTTP Authorization request header. Here are the revised examples for both CURL and Python that illustrate how you can do this:
import requests
api_key = 'my_api_key_here'
url = 'https://facestud.io/v1/generate'
headers = {'Authorization': f'Token {api_key}'}
response = requests.get(url, headers=headers)
# Check if request was successful
if response.status_code == 200:
# Save the image
with open('face.jpg', 'wb') as f:
f.write(response.content)
else:
print(f'Failed to retrieve image: {response.status_code}')
Remember to replace my_api_key_here with your own API key. To see this example in other languages, see the Appendix. The next section will show you how to obtain API keys for authentication purposes.
Requesting API Keys
API keys can be generated through your Face Studio account. Each verified user may request up to five API keys at any one time. To generate an API key:
Log in to your Face Studio account.
Navigate to the My API Keys section in your account area.
Provide a name for your API key.
Click on the "Request API Key" button.
Your API key(s) will be generated and displayed for your use.
It is always possible to delete old API keys to make room for new ones.
Generate Endpoint
The Face Studio API features a singular GET endpoint, as demonstrated in preceding examples. To maximize simplicity and user-friendliness, parameters are designed to be optional. By not specifying any parameters, the API generates a completely random face, offering users a seamless and straightforward experience when any face will do. In this context, the parameters function primarily as a filtering tool, enabling users to refine results to a subset of face types or achieve a face tailored to specific needs. Basic users can manipulate primary parameters such as gender, age, and ethnicity, while Professional users gain additional access to a wider set of advanced parameters, including the capability to set the generation seed value.
Basic Parameters
As previously noted, Basic users have the ability to tweak specific aspects of the generated images, such as adjusting age, selecting gender, or choosing an image format, simply by adding these parameters to their GET requests. Below is a detailed overview of the “basic” GET parameters that can be used to tailor your request:
Parameter
Data Type
Required
Valid Options
Default Value
Description
gender
string
No
male
female
Random
Gender of the individual, randomly chosen if omitted.
ethnicity
string
No
european
african
west_asian
south_asian
east_asian
southeast_asian
latin_american
Random
Ethnicity of the individual, randomly chosen from valid options if omitted.
age
int
No
0—80
Random
Age of the individual, randomly chosen based on real-world age distributions if omitted.
resolution
int
No
128—1024
1024
Image resolution, defaults to 1024 if omitted.
image_format
string
No
jpeg
webp
JPEG
Format of the image, defaults to JPEG if omitted.
Ensure that your requests align with the specified parameter options and data types. Recall that if a parameter is omitted, the default value or a random choice (where specified) will be used.
Advanced Parameters
Below is a detailed overview of the “advanced” GET parameters that can be used to further refine your request:
Parameter
Data Type
Required
Valid Options
Default Value
Description
seed
int
No
1—232
Random
Seed value for randomization, random if omitted.
skintone
int
No
0—10
Random
Skin tone; higher value results in darker skin tone and complexion, random if omitted.
eyewear
string
No
auto
none
eyeglasses
sunglasses
auto
Type of eyewear, defaults to auto if omitted.
hair_length
string
No
0—10
Random
Hair length; higher value results in more hair, random if omitted.
facial_hair
string
No
0—10
Random
Facial hair; higher value results in more facial hair, random if omitted.
lighting
string
No
auto
studio
natural
artistic
auto
Lighting type; studio is associated with softer lighting that looks more professional. natural immitates natural and directional sunlight. artistic is usually (but not always) associated with higher contrast with a dramatic flair.
zoom_level
string
No
standard
closeup
standard
Zoom level for image; use closeup with a high resolution to obtain a more detailed face rendering. Defaults to standard if omitted.
Choice of mood expressed, defaults to auto if omitted.
view_profile
int
No
-60—60
Random
Degrees in angle where 0 corresponds to a frontal view. Currently very unstable, especially at the far angles, but expected to improve in future.
Response Codes
Face Studio API uses standard HTTP response codes to indicate the status of your requests. Below are the primary response codes you may encounter:
Status Code
Description
Response Format
200 OK
The request was successful, and the response contains the generated image.
image/jpeg or image/webp depending on the format.
400 Bad Request
The request contains invalid parameters or incorrect input for a particular parameter. The response will be in JSON format, providing details about the error.
JSON
429 Rate Limit Reached
Your request exceeded the rate limit for your current access level. The response will be in JSON format and include a countdown indicating when you can make additional requests.
JSON
Please refer to the specific error messages in the JSON response to identify the nature of the issue when you encounter a 400 Bad Request error.
Rate Limits
The Face Studio API implements rate limits to ensure fair usage and maintain service quality. The rate limits may vary based on your access level, which is determined by your subscription plan. You can check the X-User-Class header in the API response to determine your current access level.
Checking Your Rate Limit
You can determine your rate limit by inspecting the X-User-Class header in the API response. This header indicates your access level or subscription plan, which determines your rate limit. Cross-reference this with Rate Limit Table to determine your effective rate limits.
If you exceed your rate limit, you will receive a 429 response like the following:
{
"detail": "Request was throttled. Expected available in 25 seconds."
}
Rate Limit Table
Here's a rate limit table for each user class:
User Class
Authenticated
Burst Rate Limit
Sustained Rate Limit
Anon
No
1/minute
60/day
Basic
Yes
5/minute
120/day
Professional
Yes
30/minute
1000/day
Enterprise
Yes
120/minute
6000/day
Please note that Anon users are not authenticated, whereas Basic and Professional users are authenticated. The burst rate limit specifies the maximum number of requests allowed in a short burst, while the sustained rate limit indicates the maximum number of requests permitted over a longer duration.
Practical Examples
This section is intended to be a repository of practical examples that will be updated over time.
A Lifetime in Seconds
Here's a playful example that showcases how you can seamlessly animate a face aging from 1 to 75, providing a captivating visual experience while highlighting Face Studio's powerful capabilities. Here's what the result looks like:
Keep in mind that this example requires the ability to fix a seed value, so an API key with the Professional plan or higher is necessary. To run this code, Python 3.6+ and a few common packages are needed. To install the necessary packages, you can use pip:
pip install requests tqdm imageio
Here's the full source code. Just replace my_api_key_here with your API key and run! Experiment with other seed values and options and see what you get!
import requests
import imageio
from tqdm import tqdm
import time
api_key = 'my_api_key_here'
url = 'https://facestud.io/v1/generate'
# Keep these fixed: seed, gender, ethnicity
seed = 545972026
gender = 'female'
ethnicity = 'european'
# Delay in seconds between requests
delay = 1
# Prepare headers for the request
headers = {'Authorization': f'Token {api_key}'}
# Generate images for each age from 1 to 75
images = []
for age in tqdm(range(75), desc='Generating images', unit='image'):
params = {
'seed': seed,
'gender': gender,
'ethnicity': ethnicity,
'age': age,
'resolution': 512,
'image_format': 'jpeg',
'stampless': 'yes'
}
response = requests.get(url, headers=headers, params=params)
if response.status_code == 200:
images.append(imageio.imread(response.content))
else:
print(f"Failed to retrieve image for age {age}: {response.content}")
# Wait a bit for the next request, to avoid 429 rate limit errors
time.sleep(delay)
# Save images as an animated gif
outname = 'animated_face.gif'
print(f'Saved animated GIF to {outname}')
imageio.mimsave(outname, images, loop=0, fps=10)
Please note that your results may differ depending on the model iteration!
Appendix
This section has the original authentication example in various languages including PHP, C#, and Java. To see the original version in Python, see Token Authentication.
PHP Example
Here's the example in PHP:
$api_key = 'my_api_key_here';
$url = 'https://facestud.io/v1/generate';
// Create a stream context to add headers to the HTTP request
$options = [
"http" => [
"header" => "Authorization: Token $api_key"
]
];
$context = stream_context_create($options);
// Get the image data from the API
$image_data = file_get_contents($url, false, $context);
// Check if the request was successful
if ($image_data !== FALSE) {
// Save the image
file_put_contents('face.jpg', $image_data);
} else {
echo 'Failed to retrieve image';
}
C# Example
Here's the example in C#:
using System;
using System.IO;
using System.Net.Http;
using System.Threading.Tasks;
namespace FaceApiExample
{
class Program
{
static async Task Main(string[] args)
{
string apiKey = "my_api_key_here";
string url = "https://facestud.io/v1/generate";
using (HttpClient client = new HttpClient())
{
// Set authorization header
client.DefaultRequestHeaders.Add("Authorization", $"Token {apiKey}");
try
{
// Send GET request to API and get the response
HttpResponseMessage response = await client.GetAsync(url);
// Check if request was successful
if (response.IsSuccessStatusCode)
{
// Get the image data from the response
byte[] imageData = await response.Content.ReadAsByteArrayAsync();
// Save the image
await File.WriteAllBytesAsync("face.jpg", imageData);
Console.WriteLine("Image saved successfully!");
}
else
{
Console.WriteLine($"Failed to retrieve image: {response.StatusCode.ToString()}");
}
}
catch (HttpRequestException e)
{
Console.WriteLine($"Request error: {e.Message}");
}
}
}
}
}