faceplacer

Official Node.js SDK for the Faceplacer API — AI-generated avatar headshots.

Install

npm install @howells/faceplacer

Quick Start

import { Faceplacer } from "@howells/faceplacer";

const fp = new Faceplacer({ apiKey: "fp_..." });

// Generate an avatar from a name
const avatar = await fp.avatar({ name: "Sarah Chen" });
console.log(avatar.url);
// → https://faceplacer.com/api/image/550e8400-...

Usage

Generate avatars

// From a name (infers gender, age, ethnicity)
const avatar = await fp.avatar({ name: "Sarah Chen" });

// With explicit attributes
const avatar = await fp.avatar({
  gender: "female",
  age: "thirties",
  profession: "tech",
  expression: "smiling",
  size: 512,
});

// With a location for ethnicity inference
const avatar = await fp.avatar({
  name: "Yuki",
  location: "Tokyo",
});

// Consistent results with seeds
const avatar = await fp.avatar({ seed: "user-123" });

Build image URLs

// No network call — just URL construction
const url = fp.imageUrl(avatar.id);
// → https://faceplacer.com/api/image/550e8400-...

const thumb = fp.imageUrl(avatar.id, { size: 128 });
// → https://faceplacer.com/api/image/550e8400-...?size=128

Search avatars

// Semantic text search (no API key required)
const fp = new Faceplacer();
const { results } = await fp.search({ query: "smiling woman in blazer" });

Find similar avatars

// Visual similarity search (no API key required)
const { results } = await fp.similar({ key: "ZoUz8Wl9GzXQ.png", limit: 6 });

Error Handling

import { Faceplacer, FaceplacerError } from "@howells/faceplacer";

try {
  const avatar = await fp.avatar({ name: "Test" });
} catch (error) {
  if (error instanceof FaceplacerError) {
    console.error(error.message); // "Rate limit exceeded. Please slow down."
    console.error(error.status); // 429
    console.error(error.rateLimit); // { limit: 100, remaining: 0, reset: 1719446400 }
  }
}

Configuration

const fp = new Faceplacer({
  // API key for avatar generation (get one at https://faceplacer.com/dashboard/api-key)
  apiKey: "fp_...",

  // Override base URL (for self-hosted or development)
  baseUrl: "https://faceplacer.com",

  // Custom fetch implementation
  fetch: customFetch,
});

Avatar Options

| Option | Type | Description | | ------------ | --------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------- | | name | string | Person name — infers gender, age, ethnicity | | location | string | Location for ethnicity inference (e.g. "Japan") | | gender | "male" \| "female" \| "non-binary" | | | age | "early-twenties" \| "thirties" \| "middle-aged" \| "senior" | | | ethnicity | "east-asian" \| "south-asian" \| "southeast-asian" \| "black" \| "white" \| "latino" \| "middle-eastern" \| "mixed" | | | background | "white" \| "dark" \| "gray" \| "blurred" | | | style | "casual" \| "formal" \| "business-casual" | | | profession | "general" \| "tech" \| "creative" \| "legal" \| "education" | | | expression | "neutral" \| "smiling" \| "laughing" | | | pose | "front" \| "slight-left" \| "slight-right" | Head orientation | | variation | number | Different look with same attributes (1+) | | size | 64 \| 128 \| 256 \| 512 \| 1024 | Image size in pixels (default: 256) | | seed | string | For reproducible results | | excludeIds | string[] | Avatar IDs to exclude |

License

MIT