API Documentation

Everything you need to integrate Faceplacer avatars into your app.

GEThttps://faceplacer.com/api/avatar

Include your API key in the X-API-Key header with every request.

Quick Start

curl "https://faceplacer.com/api/avatar?name=Sarah+Chen" \
  -H "X-API-Key: your-api-key"

Name-Aware Avatars

Pass a name parameter and the API will deterministically select contextually appropriate attributes.

Consistent

The same name always produces the same attributes (gender, ethnicity, age) when those aren't explicitly specified.

Override

Explicitly set any attribute to override the inferred value. For example, name=Sarah&age=senior uses the name for other attributes but forces senior age.

Parameters

All parameters are optional. Omit any to get a random value, or use name for contextual inference.

Response

302

Redirects to the CDN-hosted image. Use directly as an image source.

Location: https://cdn.faceplacer.com/avatars/...

Error Codes

400

Invalid parameters

401

Invalid or missing API key

503

Service unavailable

OpenAPI Specification

Import into Postman, Insomnia, or your favorite API client.

Download OpenAPI 3.0