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.
Registration via wallet (EIP-191 signing) or invite code: 
# Step 1: get a nonce for your wallet address
curl https://api.faces.sh/auth/nonce/0xYOUR_WALLET_ADDRESS

# Step 2: sign the nonce with your wallet and verify
curl -X POST https://api.faces.sh/auth/verify \
  -H "Content-Type: application/json" \
  -d '{
    "address": "0xYOUR_WALLET_ADDRESS",
    "signature": "0xYOUR_SIGNATURE",
    "nonce": "NONCE_FROM_STEP_1"
  }'
The response contains a JWT access_token. Use it 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/api-keys \
  -H "Authorization: Bearer YOUR_JWT" \
  -H "Content-Type: application/json" \
  -d '{"name": "my-app"}'

{
  "data": {
    "key": "sk-faces-...",
    "name": "my-app",
    "created_at": "2026-03-05T00:00:00Z"
  }
}
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 '{
    "username": "alice",
    "basic_facts": "Alice is a product designer in her 30s based in Berlin."
  }'

{
  "data": {
    "id": "face_abc123",
    "username": "alice",
    "basic_facts": "Alice is a product designer in her 30s based in Berlin.",
    "default_model": null,
    "created_at": "2026-03-05T00:00:00Z"
  }
}

​
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/face_abc123/upload \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@alice_journal.txt" \
  -F "type=document"
You can also upload PDF files, audio, or video — see Faces guide.

​
5. Compile (sync)

Trigger compilation of all pending source texts: 
curl -X POST https://api.faces.sh/v1/faces/face_abc123/sync \
  -H "Authorization: Bearer YOUR_API_KEY"
Compilation is asynchronous. Poll the face status or wait a few seconds before chatting: 
curl https://api.faces.sh/v1/faces/face_abc123 \
  -H "Authorization: Bearer YOUR_API_KEY"
When sync_status is "synced", the face is ready.

​
6. Chat

Use the OpenAI-compatible endpoint. Pass the face username 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