Faceplacer
Sign in

Documentation

API Reference

Search, browse, and find similar avatars — open access. Generation requires an API key.

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

Search & Similarity

Open access — no API key required.

GET/api/search?q=smiling+woman+in+blazer

Semantic text search across the avatar library. Powered by Voyage multimodal embeddings.

qNatural language query (required)
limitMax results, default 12, max 50
curl "https://faceplacer.com/api/search?q=smiling+woman"

# Response:
# { "results": [{ "key": "abc.png", "similarity": 0.65, "url": "https://faceplacer.stow.sh/abc.png" }] }
GET/api/similar?key=ZoUz8Wl9GzXQ.png

Find avatars that are visually similar to a reference avatar using vector similarity search.

keyStow file key of reference avatar (required)
limitMax results, default 12, max 50
curl "https://faceplacer.com/api/similar?key=ZoUz8Wl9GzXQ.png&limit=6"

# Response:
# { "results": [{ "key": "def.png", "similarity": 0.93, "url": "https://faceplacer.stow.sh/def.png" }] }

CLI

Agent-first command-line interface. NDJSON output, field masks, schema introspection.

# Generate an avatar
fp generate --gender female --expression smiling

# Semantic text search
fp search "formal portrait, dark background"

# Find visually similar
fp similar --key ZoUz8Wl9GzXQ.png --limit 6

# Browse avatars with field masks
fp avatars list --fields id,gender,url --limit 10

# Schema introspection (for agents)
fp schema generate
fp schema similar

All commands support --json, --fields, and --dry-run. Output is NDJSON when piped.

Accepts JSON via stdin: echo '{"gender":"female"}' | fp generate

OpenAPI Specification

Import into Postman, Insomnia, or any API client.

Download OpenAPI 3.0