# deepface.dev integration guide

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

## 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. Authenticate MCP compute requests with `Authorization: Bearer YOUR_MCP_KEY`.
3. Use standard API keys only for the direct REST API surface at
   `https://api.deepface.dev`.
4. Use:
   - `POST /verify` for image-to-image verification
   - `POST /represent` for embedding generation
   - `POST /compare` for image/vector and vector/vector comparison
5. 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.