Skip to main content

​
AI and agents

deepface.dev publishes agent-facing docs through Mintlify, the public API contract, and a hosted MCP runtime. Agents do not need pre-provisioned credentials to get started.

​
Start with the machine-readable docs

  • https://docs.deepface.dev/llms.txt
  • https://docs.deepface.dev/llms-full.txt
  • https://deepface.dev/skill.md
  • https://deepface.dev/.well-known/skills
  • https://www.deepface.dev/mcp
Use docs.deepface.dev for the docs pages plus Mintlify-generated llms.txt and llms-full.txt. Use www.deepface.dev/mcp for the MCP runtime and the apex domain for skill discovery. The direct REST API remains on https://api.deepface.dev.

​
Start with your coding agent

Copy this into the agent working on your project:
I want to use deepface.dev for facial verification in this project. Follow the instructions at https://deepface.dev/skill.md
The guide asks the agent to use your current stack, ask which account email you want, and prepare the integration while you confirm your email. Open agent signup to receive a sign-in link. You complete human verification and accept the terms; your agent can continue once you are signed in. Existing keys can be reused without signup. An optional, brief use-case summary helps the deepface.dev team understand what you are building. Your agent can infer a generic summary from the relevant context or ask you, and should tell you before sharing it. Private code, chat history, customer details, images and embeddings do not belong in this field. You can edit or remove the summary on the API keys page; it is never required to obtain a key. Registered accounts get 50 calls free each month, or 100 with a saved card. The explicit anonymous trial has one standard key and 10 calls per month. The coordinated gateway release will additionally limit anonymous accounts to 2 calls per minute. Use a standard key for REST at https://api.deepface.dev. ChatGPT connects with OAuth; other MCP clients use a separate dashboard MCP key for https://www.deepface.dev/mcp. Keep keys in server-side environment variables, never in browser code or chat.

​
Public runnable code

Fetch the complete JavaScript examples or Python examples, including their shared client file. Use each page’s .md export when retrieving code. The application repository is private; it is not a prerequisite for these public examples. The same code is exposed through MCP resources deepface://docs/guides/javascript and deepface://docs/guides/python. Do not claim an integration is working from a docs fetch or prepared code alone. If credentials or permitted images are unavailable, report the owner action still needed instead of fabricating a compute result.
  1. Read GET /capabilities or call get_capabilities before choosing a model or detector.
  2. For MCP clients, use https://www.deepface.dev/mcp and call verify_faces, represent_face, or compare_inputs.
  3. For direct REST integrations, call POST /verify, POST /represent, or POST /compare on https://api.deepface.dev.
  4. Send x-request-id on every request you may need to debug later.
  5. Log the echoed x-request-id, status code, and retry headers.

​
Spending alert configuration

Call get_spending_alerts and update_spending_alerts with ChatGPT OAuth or an MCP key to read and replace your account’s budget alerts, spike alerts and cap-email setting. Standard API keys and MCP keys also work with GET and PATCH at https://www.deepface.dev/api/billing/spending-alerts. The repository CLI exposes spending-alerts get and spending-alerts set. See spending alerts for the full schema and examples.

​
Global and own-account priority

For verify_faces, represent_face and compare_inputs, use optional numeric priority, for example {"priority": 10}. Every positive value goes ahead of your account’s normal queued work; lower positive values run first with FIFO ties. Null, omitted and zero mean normal queue order. There is no upper bound of 1. MCP sends X-Request-Priority; REST accepts only the header, not a body field. The ordering spans your account’s API keys within one gateway process. It selects enterprise-priority, non-enterprise-priority, enterprise-normal, then non-enterprise-normal, in strict order among eligible calls. Within one group, numeric values reorder only your account; other accounts keep their positions. No aging or 4:1 rule overrides these groups. It does not interrupt running work, bypass limits or guarantee latency. A full queue can still reject the request. Any explicitly positive own-queue priority doubles the price of completed calls. The default policy also doubles enterprise lane calls once; negotiated request-only contracts include enterprise access at standard rates. No-face results are billable; failures are free. See own-queue priority.

​
Authentication for agents

  • Create an account at deepface.dev/signup.
  • AI agents can prepare email signup, then create the required key after the owner confirms their email.
  • Use the API keys page for standard REST API keys.
  • In ChatGPT, connect with OAuth. Use the MCP page for dedicated MCP keys when connecting other clients.
  • Manual clients send the MCP key with Authorization: Bearer YOUR_MCP_KEY.
  • Standard API keys remain valid for direct REST API calls to https://api.deepface.dev, but keep them separate from MCP client credentials.
  • MCP compute image inputs may be 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.
  • MCP resource and search failures return stable public error codes instead of raw provider or filesystem details. Keep x-request-id and MCP audit entries when debugging a failed client run.
  • Humans can upgrade the same account later without changing the hosted deepface.dev integration path.
  • Dashboard key create/revoke actions emit Slack lifecycle events and may include PostHog replay metadata when browser tracking is enabled.
  • ChatGPT supports OAuth-based MCP connection with the registered deepface-chatgpt client. Sign in and approve access; no API key needs to be pasted into ChatGPT. Other clients can continue using dedicated MCP keys.
  • OAuth grants cover MCP compute and account spending-alert tools only. Calls use your account allowance and may incur charges under its plan. Revoke the ChatGPT OAuth key on the dashboard MCP page to disconnect immediately.

​
Retry and backoff guidance

MCP compute tools wait up to 120 seconds for the gateway. The gateway may still be processing an accepted request after that wait ends. A timeout or lost response can return JSON-RPC error -32002 with data containing code: "compute_outcome_unknown", request_id, outcome: "unknown", and retryable: false. Preserve that request ID and investigate before submitting another attempt. Do not automatically retry or change IDs to bypass the uncertain outcome. The MCP service does not replay compute through another adapter after losing a response. An MCP configuration failure may instead return mcp_compute_unavailable. Contact support; do not substitute a standard REST key in the MCP client.
  • 429 rate_limited: back off using Retry-After and the RateLimit-* headers.
  • 503 queue_full, 503 queue_timeout, and 503 request_body_budget_full: treat as temporary capacity pressure and retry with backoff. A body-budget rejection is zero-rated and does not dispatch inference.
  • 503 gateway_draining: retry with bounded backoff; compute has not started.
  • 503 model_not_ready, model_busy, and model_queue_timeout: the gateway already retries these precompute rejections within one 240-second deadline. If one reaches the client, another attempt may use bounded backoff.
  • 502 upstream_failed, a lost connection, or 504 upstream_timeout: preserve x-request-id and investigate before replaying. Compute may have started or completed; these failures are not automatically retried by the gateway.
  • 502 upstream_response_too_large: reduce compare target count or response complexity before another attempt; the previous computation may have run.
  • Reusing a postpaid request UUID returns 409 request_id_conflict, not a saved result. Do not change request IDs to bypass an uncertain previous outcome.

​
Safe automation boundaries

  • Safe to automate: capability discovery, verification, embedding generation, vector comparison, and account-side key rotation by a signed-in user.
  • Do not automate: scraping the public tester, credential sharing, bypassing rate limits, or sending models/detectors that are not in the current allowlist.
  • Always re-check the active model and detector allowlists before switching models in production automation.