Skip to main content

​
Faces

A face is a named persona — a compiled character that can be used as the system personality for any chat completion. Faces are identified by a unique alias within your account.

​
Create a face

curl -X POST https://api.faces.sh/v1/faces \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "alias": "alice",
    "name": "Alice",
    "basic_facts": {"age": "30", "location": "Berlin"}
  }'

​
Alias rules

  • Lowercase letters, numbers, and dashes only: ^[a-z0-9-]+$
  • Maximum 32 characters
  • Must be unique within your account

​
basic_facts

A key:value object injected into the system prompt on every chat request. Use it for facts that should always be present regardless of compiled context: name, role, location, key relationships. 
{"age": "30", "location": "Berlin", "role": "product designer"}
Only keys from the supported attributes list are accepted. Unsupported keys are dropped and a warnings array is included in the response indicating which keys were removed.

​
List supported attributes

curl https://api.faces.sh/v1/faces/attributes
Returns the categorized list of accepted basic_facts keys. No authentication required. 
{
  "object": "list",
  "data": [
    {"name": "Age & Birth", "facts": ["age", "age_range", "birth_date", ...]},
    {"name": "Current Location", "facts": ["address", "location", "city", ...]},
    ...
  ]
}

​
List faces

curl https://api.faces.sh/v1/faces \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Get a face

curl https://api.faces.sh/v1/faces/FACE_ALIAS \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Update a face

curl -X PATCH https://api.faces.sh/v1/faces/FACE_ALIAS \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "basic_facts": {"age": "30", "location": "Berlin", "role": "senior product designer"},
    "default_model": "gpt-4o-mini"
  }'

​
default_model

Sets the LLM used when no model is specified in the chat request. Accepts any model name from the supported models list. Leave null to use the system default.

​
Delete a face

curl -X DELETE https://api.faces.sh/v1/faces/FACE_ALIAS \
  -H "Authorization: Bearer YOUR_API_KEY"
Deleting a face drops its compiled psychological primitives and removes it from the centroid index. Documents compiled exclusively for this face are also removed.

​
Upload source texts

Upload documents, transcripts, or threads to be compiled into the face. 
# Text or PDF document
curl -X POST https://api.faces.sh/v1/faces/alice/upload \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@interview.pdf" \
  -F "type=document"

# Pre-written transcript (plain text)
curl -X POST https://api.faces.sh/v1/faces/alice/upload \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@transcript.txt" \
  -F "type=thread"

​
Supported file types

TypeFormats
Document.txt, .pdf
Thread.txt (structured transcript)
Audio/Video.mp3, .mp4, .wav, .m4a, .webm, and more
Audio and video files are transcribed asynchronously — the upload returns 202 with prepare_status: "transcribing". Poll the thread or document GET endpoint until prepare_status becomes null (ready to review) or "failed". Text and PDF uploads return 200 synchronously. To get the raw transcript without creating a compile thread/document, use the /transcribe endpoint instead.

​
Import

Import a public URL — the content is fetched, transcribed if needed, and stored as a document or thread. Returns 202 immediately; transcription runs in the background. 
curl -X POST https://api.faces.sh/v1/faces/alice/import \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://www.youtube.com/watch?v=VIDEO_ID"}'
# Returns 202 with prepare_status="transcribing"
# Poll GET /v1/compile/documents/{id} or /v1/compile/threads/{id} until ready

​
Transcribe audio/video

Transcribe without compiling. Returns raw text and speaker-diarized segments: 
curl -X POST https://api.faces.sh/v1/faces/alice/transcribe \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@podcast.mp3"

{
  "data": {
    "text": "Full transcript text...",
    "segments": [
      { "speaker": "A", "start": 0.0, "end": 4.2, "text": "Welcome to the show." },
      { "speaker": "B", "start": 4.5, "end": 8.1, "text": "Thanks for having me." }
    ]
  }
}
Transcription is billed separately from compile quota. See Billing guide.

​
Plan limits

The number of faces you can create depends on your subscription plan:
PlanFace limit
FreeUnlimited
ConnectUnlimited
Faces are unlimited on all plans.