Documentation

API Reference

The API is how you take the collection home — every browsable avatar plus on-demand generation for combinations that don't exist yet.

Browse what's already rendered →

GEThttps://faceplacer.com/api/avatar

Include X-API-Key on generation, search, and similarity API requests. Returned image URLs can be rendered directly.

Quick Start

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

Prompt-Aware Avatars

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

Consistent

The same name always produces the same attributes (gender, ethnicity, age), while a query can infer supported styling context such as dress code, profession, expression, and pose.

Override

Explicitly set any attribute to override the inferred value. For example, query=Sarah%20estate%20agent&age=senior uses the query 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

Requires an API key.

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 -H "X-API-Key: fp_..." "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 -H "X-API-Key: fp_..." "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