Faceplacer API documentation

When to use Faceplacer

Use Faceplacer for fictional avatar headshots in application interfaces, prototypes, persona cards, and profile placeholders. Browse the existing collection first. Do not use it to find, identify, verify, or impersonate real people. Generated attributes are appearance controls, not personal information.

Start with the public collection

GET /api/collection returns completed, displayable avatars as an avatars array. No API key is required. This reads the collection without semantic search, inference, uploads, or media generation. Use returned image URLs rather than constructing storage paths.

For exact structured lookup, pass gender, age, ethnicity, background, style, profession, expression, or pose directly to /api/collection. Comma-separated values mean OR within a facet; different facets combine with AND across the entire displayable collection. Unknown or repeated parameters, empty values, and invalid facet values return 400 instead of being ignored.

curl "https://www.faceplacer.com/api/collection"

Collection pagination and caching

Without limit or cursor, the collection keeps returning every match in its existing newest-first order. Add limit=1–100 for a bounded page in ascending avatar UUID order. Read pagination.hasMore and pass pagination.nextCursor unchanged with the same filters to continue. A cursor without limit uses 50; changing the page size is allowed. nextCursor is null on the final page. Pages are live views, not snapshots: restart to include concurrent inserts before your cursor.

Responses include an ETag for the selected representation. Send it in If-None-Match to receive a bodyless 304 when unchanged; GET and HEAD support this. Filters and pages have their own validators. The CDN caches for 300 seconds and may serve stale content for up to 86400 seconds while revalidating; a matching ETag describes the served representation, not an uncached database snapshot.

curl "https://www.faceplacer.com/api/collection?ethnicity=south-asian&gender=female&limit=5"

Versioning and deprecation

The stable API uses the major version path /api/v2, matching the version 2 OpenAPI contract. Start new integrations with GET /api/v2/collection. The existing /api paths remain compatible and supported; the SDK's existing default URLs do not change. Both paths use the same authentication, responses, provider safeguards, and rate-limit budgets.

Backward-compatible fields may be added within version 2. Breaking request or response changes require a new major URL. Before retiring a supported version, we will publish a migration guide and signal the change with Deprecation and Sunset response headers, with at least 90 days notice before removal. No version or legacy URL is currently scheduled for retirement.

curl "https://www.faceplacer.com/api/v2/collection"

Authentication and side effects

Create a Faceplacer account, then open API keys in the signed-in dashboard. Avatar and keyed similarity requests require the X-API-Key header. Search accepts an optional key: 30 requests/minute/IP without one, or 60/minute/key with a valid key. Collection browsing and image URLs are public. Rate-limited responses expose X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset; honor Retry-After on a 429. These are per-instance limits, not a global quota guarantee.

GET /api/avatar generates a missing match by default. Set generate=false to retrieve only an existing displayable match; a miss returns 404. Name/query inference can still contact a model even with generation disabled. For cache-only requests without inference, use structured attributes and omit name and query. Semantic text search contacts Voyage to encode the query, then searches Faceplacer’s stored vectors. Similarity uses a stored vector directly and makes no inference request. Generation may use credits and contact FAL and storage providers; review your account before automating it.

curl -H "X-API-Key: $FACEPLACER_API_KEY" "https://www.faceplacer.com/api/avatar?gender=female&profession=tech&generate=false"

Filters and image delivery

Supported facets are gender, age, ethnicity, background, style, profession, expression, and pose. Search requires q (a nonempty text query); use /api/collection for structured-only lookup. Search accepts comma-separated OR values within a facet; different facets combine with AND. Hard filters apply to the top 50 semantic candidates, so results may be fewer than the requested limit.

Search responses retain results and add metadata: scope is semantic-candidates, candidateLimit is 50, candidatesExamined counts provider candidates, and matchingCandidates counts displayable candidates passing the filters before the response limit. collectionMatches counts every displayable collection row matching the structured filters, not semantic relevance. Empty results with collectionMatches greater than zero indicate a candidate-window miss; zero means no structured matches in that live count. Ranking and count are separate live reads, not a transactional snapshot.

The stable image endpoint is /api/image/{id}?size=256; supported sizes are 64, 128, 256, 512, and 1024. Returned CDN URLs can be embedded without authentication. Faceplacer transforms support positive w/h dimensions up to 4096, q from 5–100 rounded to the nearest 5, and f=webp|avif|jpeg|png. Defaults are quality 80 and webp with scale-down fit; no transform parameters serves the original. Do not rely on a particular CDN hostname or path.

Recovering from errors

Errors contain the legacy error message plus a stable code, message, and resolution. Correct invalid parameters (400), configure a valid key (401), respect access restrictions (403), or try a different existing resource (404/409). On 429, honor Retry-After instead of immediately repeating requests. Temporary dependency failures use a server error status. Never put credentials in logs or recovery reports.

Avatar success returns a 302 image redirect and X-Faceplacer-Source: cache or generated. Authenticated redirects and errors must not be shared between callers. With generation enabled, an occupied but unavailable exact combination returns 409 rather than starting a conflicting generation.

Official SDK and CLI

The official Node.js SDK and CLI on npm is @howells/faceplacer. Version 0.2.0 includes the faceplacer executable and supports Node.js 18 or later. Use npx as shown below, or npm install @howells/faceplacer for the SDK. Do not install the unrelated bare faceplacer package.

CLI help and version work offline. collection needs no key; use FACEPLACER_API_KEY for keyed commands, never a command-line key flag. Operations emit JSON on stdout and diagnostics on stderr, with exit codes 0 for success, 2 for invalid arguments, and 1 for request failures. avatar only retrieves existing matches from structured attributes; there is no generation or upload command. search encodes text with Voyage; similar uses Faceplacer’s stored vectors without inference. The CLI never loads repository environment files or exposes administrative commands.

The SDK supports public search without credentials. Avatar and similarity methods require a key. See the SDK reference for current published exports and runtime support.

npx @howells/faceplacer@0.2.0 --help
npx @howells/faceplacer@0.2.0 collection --json

Discovery and support

OpenAPI specification · OpenAPI alias · API catalog · Agent guidance · Sitemap · About · Contact · Privacy

GET /api/collection

Browse completed avatars

Public collection index, with no key, inference, semantic search, uploads or generation. All eight facets filter the complete displayable collection: comma-separated OR within a facet, AND across facets. Unknown/repeated parameters and invalid/empty values return400. With neither limit nor cursor, returns all matches in the existing newest-first order. Paginated requests use ascending avatarUUID keyset order and a bounded database query. Pages are live views, not snapshots: concurrent inserts before a cursor require restarting to see them. Return the cursor unchanged with the same filters; changing filters returns400. No pagination metadata is returned for unpaginated requests.

• gender: Comma-separated values: OR within this attribute and AND with other attributes.
• age: Comma-separated values: OR within this attribute and AND with other attributes.
• ethnicity: Comma-separated values: OR within this attribute and AND with other attributes.
• background: Comma-separated values: OR within this attribute and AND with other attributes.
• style: Comma-separated values: OR within this attribute and AND with other attributes.
• profession: Comma-separated values: OR within this attribute and AND with other attributes.
• expression: Comma-separated values: OR within this attribute and AND with other attributes.
• pose: Comma-separated values: OR within this attribute and AND with other attributes.
• limit: Optional page size,1–100. Omit both limit and cursor to return all matches. A cursor without limit uses50.
• cursor: Opaque pagination.nextCursor from the preceding response. Preserve the same filters (value order may differ). Null nextCursor means the last page. Paging order is ascending avatarUUID, not creation time.
• If-None-Match: ETag from the same selected representation; a match returns304 without a body. Supports comma-separated validators and *.
• 200: Completed displayable avatars.
• 304: Selected representation has not changed; no response body.
• 400: Unknown/repeated parameter, invalid facet/limit, malformed cursor or cursor/filter mismatch.
• 405: Unsupported method. Consult Allow; avatar, search, similarity, and image endpoints do not support HEAD because GET can invoke providers.
• 503: Collection unavailable

GET /api/avatar

Generate or retrieve an avatar image

Returns a matching avatar. By default, missing matches are generated. Set generate=false to return only an existing displayable match (404 if absent); name and query inference still run. When generation is enabled and the exact combination exists but is unavailable, returns 409 rather than attempting a conflicting generation. Requires an API key.

• name: Name to infer attributes from (e.g., 'Sarah Chen'). Used as seed for consistent results.
• seed: Explicit seed string for reproducibility.
• gender: Gender of the avatar. Inferred from name if omitted.
• age: Age range. Random if omitted.
• ethnicity: Ethnic appearance. Inferred from name if omitted.
• location: Location string to map to ethnicity (e.g., 'Japan', 'Brazil').
• profession: Professional context affecting attire.
• expression: Facial expression.
• pose: Head orientation. Random/seeded if omitted.
• style: Clothing style.
• background: Background color/style.
• variation: Variation number for different looks with the same attributes.
• size: Image size in pixels (square).
• query: Natural-language avatar request; explicit attributes override inferred values.
• generate: Whether a missing match may be generated. false returns 404 instead.
• excludeIds: Comma-separated avatar UUIDs to exclude.
• 302: Redirect to the stable Faceplacer image endpoint.
• 400: Invalid parameters
• 401: Missing or invalid API key
• 404: No existing displayable avatar matched generate=false.
• 405: Unsupported method. Consult Allow; avatar, search, similarity, and image endpoints do not support HEAD because GET can invoke providers.
• 409: Generation is enabled, but the exact avatar combination already exists and is unavailable.
• 429: Rate limit exceeded.
• 503: Generation service unavailable.

GET /api/search

Semantic text search across avatars

Search existing displayable avatars. API key is optional: anonymous requests are rate-limited by IP and valid keys by key. Hard collection filters apply before the response limit; filtering uses the top 50 provider candidates, so fewer results may be returned. A nonempty q is required; use /collection for structured-only lookup. metadata.collectionMatches counts all displayable rows matching the structured filters, not semantic relevance. If results is empty but collectionMatches is positive, the semantic candidate window missed those matches. Counts and ranking are separate live reads, not a transactional snapshot.

• q: Natural language search query.
• limit: Maximum number of results.
• gender: Comma-separated values: OR within this attribute and AND with other attributes.
• age: Comma-separated values: OR within this attribute and AND with other attributes.
• ethnicity: Comma-separated values: OR within this attribute and AND with other attributes.
• background: Comma-separated values: OR within this attribute and AND with other attributes.
• style: Comma-separated values: OR within this attribute and AND with other attributes.
• profession: Comma-separated values: OR within this attribute and AND with other attributes.
• expression: Comma-separated values: OR within this attribute and AND with other attributes.
• pose: Comma-separated values: OR within this attribute and AND with other attributes.
• 200: Search results ranked by similarity
• 400: Invalid query, limit, or filter value.
• 401: Invalid explicitly supplied API key.
• 405: Unsupported method. Consult Allow; avatar, search, similarity, and image endpoints do not support HEAD because GET can invoke providers.
• 429: Rate limit exceeded.
• 503: Search provider unavailable.

GET /api/similar

Find visually similar avatars

Find avatars that are visually similar to a reference avatar using vector similarity search. Requires an API key.

• key: Faceplacer file key of the reference avatar.
• limit: Maximum number of results.
• 200: Similar avatars ranked by cosine similarity
• 405: Unsupported method. Consult Allow; avatar, search, similarity, and image endpoints do not support HEAD because GET can invoke providers.

GET /api/image/{id}

Serve an avatar image

Retrieves a generated avatar image by ID. Supports dynamic resizing via CDN transforms. Image URLs returned by authenticated API calls are directly renderable.

• id: Avatar ID
• size: Desired image size in pixels. Defaults to 1024.
• download: Set to 1 or true to request an attachment download.
• 200: Avatar image
• 302: Redirect to the stable image response.
• 400: Invalid avatar id.
• 404: Avatar not found
• 405: Unsupported method. Consult Allow; avatar, search, similarity, and image endpoints do not support HEAD because GET can invoke providers.

Gender values

male, female, non-binary

Age values

early-twenties, thirties, middle-aged, senior

Ethnicity values

east-asian, south-asian, southeast-asian, black, white, latino, middle-eastern, mixed

Background values

white, dark, gray, blurred

Style values

casual, formal, business-casual

Profession values

general, tech, creative, legal, education

Expression values

neutral, smiling, laughing

Pose values

front, slight-left, slight-right

Size values

64, 128, 256, 512, 1024