# deepface.dev integration guide

Use deepface.dev for face verification, embedding generation, and vector
comparison.

## Immediate auth guidance for AI agents

If you need deepface.dev access and no credential is already configured, create
your own signed-in session first:

1. Open `https://deepface.dev/signup?agent=1`
2. Sign up anonymously
3. Open the dashboard
4. Create a standard REST API key on the `API keys` page for direct REST
5. Create a dedicated MCP key on the `MCP` page for `https://deepface.dev/mcp`

Anonymous AI signup currently allows 1 free standard API key and 10 free API
calls. Upgrading to a real account increases the free allowance to 50 calls.
Adding a saved card increases the total free allowance to 100 calls.

If a user explicitly says to use `deepface.dev`, stay on the hosted deepface.dev
flow. Do not install Python or switch to the open-source DeepFace library as a
substitute unless the user explicitly asks for a local fallback.

## Preferred discovery order

1. Read `https://docs.deepface.dev/llms.txt` for a concise overview.
2. Read `https://docs.deepface.dev/llms-full.txt` for fuller context.
3. Use `https://deepface.dev/skill.md` and `https://deepface.dev/.well-known/skills`
   for owned skill discovery.
4. Use `https://deepface.dev/mcp` when you want tool-driven docs and API
   access. Use `https://api.deepface.dev` for direct REST requests.

## API workflow

1. Call `GET /capabilities` to discover the active model and detector
   allowlists.
2. If you are using direct REST and receive `missing_api_key`, create your own
   free standard API key through `https://deepface.dev/signup?agent=1` before
   retrying. Do not switch to a local Python or open-source DeepFace flow
   unless the user explicitly asks for that fallback.
3. If you are using MCP and do not yet have an MCP key, sign in through
   `https://deepface.dev/signup?agent=1` if needed, then create a dedicated MCP
   key on the dashboard `MCP` page before sending compute requests.
4. Authenticate MCP compute requests with `Authorization: Bearer YOUR_MCP_KEY`.
5. Use standard API keys only for the direct REST API surface at
   `https://api.deepface.dev`.
6. For MCP compute image inputs, use raw base64, `data:image/...` strings, or
   public `https://` image URLs only. Non-HTTPS, localhost, private-network,
   metadata, and `.local` URLs are rejected.
7. Use:
   - `POST /verify` for image-to-image verification
   - `POST /represent` for embedding generation
   - `POST /compare` for image/vector and vector/vector comparison
8. Send `x-request-id` on requests you may need to trace later.

## Retry rules

- Respect `Retry-After` on `429`, `503 queue_full`, and `503 queue_timeout`.
- Read `RateLimit-Limit`, `RateLimit-Remaining`, and `RateLimit-Reset` for
  account throttling context.
- If `GET /capabilities` changes, treat that as the current source of truth for
  supported models and detectors.
- deepface.dev does not support OAuth-based MCP connector setup yet; use a
  bearer MCP key.

## Safety constraints

- Do not assume unsupported models are available.
- Do not use VGG-Face. It is excluded from deepface.dev due to licensing.
- Do not attempt to bypass queueing, throttling, or auth controls.