Skip to main content

​
Quickstart

The public API is served by the gateway at https://api.deepface.dev. This quickstart is for direct REST integrations. If you are wiring an MCP client, use the AI and agents guide and create an MCP key instead of a standard REST API key.

​
1. If you are an AI agent and no key is configured, create your own account session first

You do not need to wait for a human to hand you a key.
  1. Open deepface.dev/signup?agent=1.
  2. Sign up anonymously.
  3. Open the dashboard API keys page.
  4. Create a standard REST API key for your own session.
If you are wiring MCP instead of direct REST, create a dedicated MCP key on the dashboard MCP page and follow the AI and agents guide. 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.

​
2. Create your account

If you are not using the anonymous AI flow, or you want a persistent account: Sign up for deepface.dev, then sign in to open the account dashboard.

​
3. Create an API key

Open the API keys section in the dashboard and create a key for your app or environment. deepface.dev shows the full key once, so copy it into your secrets manager immediately.

​
4. Pick a supported model

Start with Facenet unless you have a compatibility reason to choose another approved model. Review the full models and licensing guide before production use.

​
5. Call /verify

curl --request POST \
  --url https://api.deepface.dev/verify \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --form 'img1=@./person-a.jpg' \
  --form 'img2=@./person-b.jpg' \
  --form 'model_name=Facenet'
Example response: 
{
  "verified": true,
  "distance": 0.19,
  "threshold": 0.4,
  "model": "Facenet"
}

​
Runnable examples

​
6. Inspect capabilities

Use GET /capabilities to read the active model and detector allowlists before rolling requests into production. Authenticated API integrations can also use public http(s) image URLs if remote URL fetching is enabled on the model server. The public tester remains limited to file and base64 inputs.

​
7. Keep request IDs

Every compute response includes x-request-id. Log it on your side for support handoffs and incident debugging.