Introduction Last updated: 2023-10-19

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:

CURL
curl -H "Authorization: Token my_api_key_here" https://facestud.io/v1/generate -o face.jpg
Python
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:

  1. Log in to your Face Studio account.
  2. Navigate to the My API Keys section in your account area.
  3. Provide a name for your API key.
  4. Click on the "Request API Key" button.
  5. 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.
stampless string No
  • yes
  • no
no Whether to include invisible watermarks, defaults to no if omitted.
mood string No
  • auto
  • joyous
  • composed
no 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:

Example output using seed 545972026
Figure 1. Example output using seed 545972026

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}");
                }
            }
        }
    }
}

Java Example

Here's the example in Java:

import org.apache.http.client.methods.CloseableHttpResponse;
import org.apache.http.client.methods.HttpGet;
import org.apache.http.impl.client.CloseableHttpClient;
import org.apache.http.impl.client.HttpClients;
import org.apache.http.util.EntityUtils;
import java.io.File;
import java.io.FileOutputStream;
import java.io.IOException;

public class FaceApiExample {
    public static void main(String[] args) {
        String apiKey = "my_api_key_here";
        String url = "https://facestud.io/v1/generate";
        
        try (CloseableHttpClient client = HttpClients.createDefault()) {
            HttpGet request = new HttpGet(url);
            request.addHeader("Authorization", "Token " + apiKey);

            try (CloseableHttpResponse response = client.execute(request)) {
                if (response.getStatusLine().getStatusCode() == 200) {
                    byte[] imageBytes = EntityUtils.toByteArray(response.getEntity());

                    try (FileOutputStream fos = new FileOutputStream(new File("face.jpg"))) {
                        fos.write(imageBytes);
                        System.out.println("Image saved successfully!");
                    }
                } else {
                    System.out.println("Failed to retrieve image: " + response.getStatusLine().getStatusCode());
                }
            }
        } catch (IOException e) {
            System.out.println("An error occurred: " + e.getMessage());
        }
    }
}