# Faceplacer API documentation

Faceplacer provides fictional AI-generated headshots for apps, prototypes, persona cards, and profile-picture placeholders. Browse completed portraits, combine appearance filters, or integrate the public API. These images do not identify real people; Faceplacer is not an identity verification or person lookup service.

## 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.

```sh
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.

```sh
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.

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

## Authentication and side effects

[Create a Faceplacer account](https://www.faceplacer.com/sign-up), 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.

```sh
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](https://www.npmjs.com/package/@howells/faceplacer) 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](https://www.npmjs.com/package/@howells/faceplacer) for current published exports and runtime support.

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

## Discovery and support

[OpenAPI specification](https://www.faceplacer.com/api/openapi) · [OpenAPI alias](https://www.faceplacer.com/openapi.json) · [API catalog](https://www.faceplacer.com/.well-known/api-catalog) · [Agent guidance](https://www.faceplacer.com/llms.txt) · [Sitemap](https://www.faceplacer.com/sitemap.xml) · [About](https://www.faceplacer.com/about) · [Contact](https://www.faceplacer.com/contact) · [Privacy](https://www.faceplacer.com/privacy)