# deepface.dev integration guide

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

## Connect the user's project

Use the project's existing framework and server-side stack. Inspect only the
context needed for the integration. If a valid deepface.dev key is already
configured, reuse it without printing it and skip signup.

1. Ask which email the user wants for their deepface.dev account. Do not guess
   from Git settings, repository authors or unrelated accounts.
2. Briefly tell them that an optional one-sentence project summary will be shared
   with deepface.dev to help the team understand what they are building. Infer a
   generic summary from the relevant project context; if the use case is unclear,
   ask what they want to verify. Do not send private code, chat history, customer
   names, personal records, photos or embeddings. If they decline, skip it.
3. Open `https://deepface.dev/signup?agent=1&next=%2Faccount%2Fkeys`. Fill the
   account email and optional project summary. The email link creates an account
   or signs in to an existing one. Ask the user to complete any human verification,
   accept the terms and open their email link in the same browser. Do not bypass
   verification, accept terms for them or read their mailbox without permission.
   Continue preparing the integration while they confirm.
4. After sign-in, use the API keys screen to create a standard REST key for this
   integration. Save it directly as `DEEPFACE_API_KEY` in an ignored server-side
   environment file or the project's secret store. Never put it in chat, URLs,
   client-side code, screenshots or source control.
5. For an existing account, or to correct the summary, open "Tell us what you're
   building" on `/account/keys`. With the same authenticated browser session,
   an agent may instead `PUT /api/account/use-case` with JSON
   `{"use_case":"Generic project summary","source":"agent_context"}`.
   Maximum 500 characters; an empty use_case removes the summary. This endpoint
   uses the account's session, not a REST/MCP API key, and cannot select another
   account. Skip reporting if the user declines. Treat 401 as a sign-in requirement
   and other failures as a report failure, not a failed integration; never claim
   the summary was saved without a successful response. Owners can edit/remove it.
6. Follow `https://docs.deepface.dev/quickstart`, inspect current capabilities,
   implement a server-side request and test with authorized sample images. Cover
   a match, a non-match, no face, invalid input and service failure. Explain the
   verified result and any unfinished setup.

If browser automation is unavailable, give the user the signup link and continue
coding. They can put their key in the local environment themselves; do not ask them
to paste it into the conversation. Human confirmation is a real step, not an error.

Registered accounts have 50 free calls per month, or 100 with a saved card.
Do not add payment details or enable paid usage without the user's instruction.
Anonymous access remains an explicit limited trial at
`https://deepface.dev/signup?agent=1&anonymous=1`: 10 calls per month and one
standard key. A 2-request-per-minute limit is pending the coordinated gateway
release. Prefer an email-owned account for a real project.

If a user explicitly says to use `deepface.dev`, use the hosted service. Do not
install the DeepFace Python library as a substitute unless they request it.
Facial similarity is not proof of identity or liveness; do not describe it as such.

## 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://www.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`, follow the email signup flow above and create a
   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,
   when enabled, public HTTPS image URLs from any domain. Remote downloads must
   resolve to public addresses and pass redirect, image type, size, and timeout
   checks before inference.
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.

## Spending alerts

Use `get_spending_alerts` and `update_spending_alerts` with an MCP key for
budget, spike and cap-email settings. The account REST endpoint is
`https://www.deepface.dev/api/billing/spending-alerts` (GET/PATCH), accepting
standard or MCP keys. The repository CLI supports `npm run --silent cli -- spending-alerts get`
and `npm run --silent cli -- spending-alerts set --file settings.json`.
Read current settings before replacing the full document; keep rule IDs stable.
See https://docs.deepface.dev/spending-alerts for the schema and limits.

## Request priority

For synchronous REST compute, `X-Request-Priority` controls the global group and **your own account's
waiting queue**, across its API keys on each gateway process. MCP compute tools
accept equivalent optional `priority`. Any finite positive number jumps your
normal waiting queue; lower positive numbers run first with FIFO ties. `1`, `10`
and `100` all request priority. Omitted, null and zero mean normal order and no
per-request surcharge. Zero is accepted; malformed or negative values return
`400 invalid_priority`. REST priority is header-only, not a body field.

Global eligible calls run in strict groups: enterprise-priority,
non-enterprise-priority, enterprise-normal, then non-enterprise-normal. Within a
group, numeric values reorder only your own account. No aging or 4:1 rotation
overrides these groups. It never preempts running work, bypasses limits, reserves
capacity or guarantees latency. Experimental async compare
rejects positive priority headers with `400 unsupported_priority`.

Completed calls with any explicitly positive own-queue priority cost twice the
standard rate. The default policy also charges enterprise lanes 2x once;
negotiated request-only contracts include enterprise access at standard rates.
Completed no-face results are billable; failures are free.
See https://docs.deepface.dev/api-reference/rate-limits for precision and scope.

## Retry rules

- MCP compute waits up to 120 seconds for the gateway. A timeout or lost
  response can return `compute_outcome_unknown` with `request_id`,
  `outcome: "unknown"`, and `retryable: false`. Preserve the request ID;
  gateway work may continue. Do not automatically retry or replay through
  another adapter. Investigate the original request first.
- `mcp_compute_unavailable` indicates an MCP server configuration problem;
  contact support instead of changing key type.

- Respect `Retry-After` on `429`, `503 queue_full`, `503 queue_timeout`, and
  zero-rated `503 request_body_budget_full`; body-budget rejection does not run inference.
- `503 gateway_draining` rejects before compute; use bounded backoff.
- The gateway retries only explicit `503 model_not_ready`, `model_busy`, and
  `model_queue_timeout` admission errors within one 240-second upstream budget.
  If an admission error reaches the client, compute has not started.
- Do not automatically replay a generic `502`, lost response, or
  `504 upstream_timeout`: compute may have run. Preserve `x-request-id` and
  investigate. Reusing a postpaid UUID returns `409 request_id_conflict`, not a
  cached result; do not use a new UUID to bypass an uncertain prior outcome.
- 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.