Skip to main content

​
Quickstart

This guide walks you through the full workflow: register an account, create a face, upload a source document, compile it, and run a chat completion.

​
Prerequisites

  • API base URL: https://api.faces.sh
  • Replace YOUR_API_KEY with a real key obtained in step 2.

​
1. Register

If you already have an account, skip to step 2.
Register with email and password: 
curl -X POST https://api.faces.sh/auth/register-email \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Alice",
    "email": "alice@example.com",
    "password": "your-secure-password",
    "username": "alice"
  }'
The response contains a JWT token and a user_id. Use the JWT as a Bearer token for subsequent requests, or create an API key (step 2).

​
2. Create an API key

curl -X POST https://api.faces.sh/v1/auth/api-keys \
  -H "Authorization: Bearer YOUR_JWT" \
  -H "Content-Type: application/json" \
  -d '{"name": "my-app"}'

{
  "id": "a1b2c3d4-...",
  "key": "sk-faces-...",
  "key_prefix": "sk-faces-abc12345",
  "name": "my-app"
}
Store this key. All examples below use YOUR_API_KEY.

​
3. 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": "alice",
  "object": "face",
  "name": "Alice",
  "basic_facts": {
    "age": {"value": "30", "status": "stated", "identification": "user-provided"},
    "location": {"value": "Berlin", "status": "stated", "identification": "user-provided"}
  },
  "component_counts": null
}

​
4. Upload a source document

Upload a plain-text file that describes or characterizes the face: 
curl -X POST https://api.faces.sh/v1/faces/alice/upload \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@alice_journal.txt" \
  -F "type=document"

{
  "data": {
    "document_id": "doc_abc123"
  }
}
You can also upload PDF files, audio, or video — see Faces guide.

​
5. Compile

Trigger compilation of the uploaded document: 
curl -X POST https://api.faces.sh/v1/compile/documents/doc_abc123/make \
  -H "Authorization: Bearer YOUR_API_KEY"
Compilation is asynchronous (returns 202). Poll the document status until it completes: 
curl https://api.faces.sh/v1/compile/documents/doc_abc123 \
  -H "Authorization: Bearer YOUR_API_KEY"
When prepare_status is "synced", the face is ready.

​
6. Chat

Use the OpenAI-compatible endpoint. Pass the face alias in the model field: 
curl -X POST https://api.faces.sh/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "alice",
    "messages": [
      {"role": "user", "content": "What do you think about Berlin?"}
    ]
  }'

{
  "id": "chatcmpl-...",
  "object": "chat.completion",
  "choices": [{
    "message": {
      "role": "assistant",
      "content": "Berlin has this incredible energy — it rewards people who are comfortable with ambiguity..."
    },
    "finish_reason": "stop"
  }],
  "usage": { "prompt_tokens": 312, "completion_tokens": 87, "total_tokens": 399 }
}
To specify a particular LLM backend, use "model": "alice@gpt-4o-mini" syntax. See Chat guide.

​
Next steps