Face consistency
for AI pipelines

import requests

API_KEY = "fs_live_a8f3..."
BASE    = "https://facesync.dev/api/v1"
headers = {"Authorization": f"Bearer {API_KEY}"}

# create character
char = requests.post(f"{BASE}/characters", headers=headers, json={
    "name": "Elena",
    "description": "Brand avatar"
}).json()

# upload reference
requests.post(f"{BASE}/characters/{char['id']}/references",
    headers=headers,
    json={"imageUrl": "https://cdn.example.com/ref.jpg"})

# check a generated image
result = requests.post(f"{BASE}/checks", headers=headers, json={
    "characterId": char["id"],
    "imageUrl": "https://cdn.example.com/gen_047.png",
    "threshold": 90
}).json()

if result["isConsistent"]:
    print(f"PASS: {result['overallSimilarity']}% match")
else:
    print(f"FAIL: {result['overallSimilarity']}%")
    for tip in result["remediation"]["suggestions"]:
        print(f"  fix: {tip}")

# check a video for face drift
video = requests.post(f"{BASE}/video/check", headers=headers, json={
    "videoUrl": "https://cdn.heygen.com/render.mp4",
    "characterId": char["id"],
    "fps": 2,
    "threshold": 88
}).json()
print(f"Video pass rate: {video['overall']['passRate']}")

const API_KEY = "fs_live_a8f3...";
const BASE = "https://facesync.dev/api/v1";
const headers = {
  "Authorization": `Bearer ${API_KEY}`,
  "Content-Type": "application/json"
};

// check a generated image
const res = await fetch(`${BASE}/checks`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    characterId: "chr_a1b2c3",
    imageUrl: "https://cdn.example.com/gen_047.png",
    threshold: 90
  })
});

const result = await res.json();
console.log(result.isConsistent
  ? `PASS: ${result.overallSimilarity}%`
  : `FAIL: ${result.overallSimilarity}% — ${result.remediation.suggestions[0]}`
);

// Option 1: OpenAI Assistants — fetch tools from the API
const tools = await fetch("https://facesync.dev/api/v1/schemas/openai")
  .then(r => r.json());

const assistant = await openai.beta.assistants.create({
  model: "gpt-4o",
  tools: tools.map(t => ({ type: "function", function: t })),
  instructions: "You verify face consistency for AI avatars using FaceSync."
});

// Option 2: Custom GPT Actions — paste the OpenAPI spec
// GET https://facesync.dev/api/v1/schemas/openapi
// Copy the JSON → GPT Builder → Actions → paste
// Set auth: API Key, header: Authorization, prefix: Bearer

// Option 3: Direct function calling
const response = await openai.chat.completions.create({
  model: "gpt-4o",
  tools: tools.map(t => ({ type: "function", function: t })),
  messages: [{
    role: "user",
    content: "Check if gen_047.png matches Elena"
  }]
});

// Option A: Claude API — tool_use
const tools = await fetch("https://facesync.dev/api/v1/schemas/claude")
  .then(r => r.json());

const msg = await anthropic.messages.create({
  model: "claude-sonnet-4-20250514",
  max_tokens: 1024,
  tools: tools,
  messages: [{ role: "user", content: "Check this face against Elena" }]
});

// Option B: MCP Server — add to claude_desktop_config.json
{
  "mcpServers": {
    "facesync": {
      "command": "node",
      "args": ["/path/to/facesync/mcp-server.js"],
      "env": {
        "MCP_API_KEY": "fs_live_xxx"
      }
    }
  }
}
// or via SSH to a remote server:
"command": "ssh",
"args": ["user@server", "node", "/opt/facesync/mcp-server.js"]

n8n / Make / Zapier — use the HTTP Request node

Method:   POST
URL:      https://facesync.dev/api/v1/checks
Auth:     Header Auth
           Name:  Authorization
           Value: Bearer fs_live_xxx
Body:     JSON
           {
             "characterId": "{{ $json.characterId }}",
             "imageUrl": "{{ $json.imageUrl }}",
             "threshold": 90
           }

Recommended n8n pipeline:

  HeyGen Webhook
       |
  Extract Frames ──> POST /video/extract-frames
       |
  Loop Over Frames
       |
  Check Face ──────> POST /checks
       |
  IF isConsistent == false
       |
  Retry with ──────> use remediation.promptSnippet
  fixed prompt       in next HeyGen generation

Import the OpenAPI spec directly:
  GET https://facesync.dev/api/v1/schemas/openapi
  Paste into n8n's HTTP node or Zapier's custom API