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, follow the AI and agents guide: connect ChatGPT with OAuth, or create a dedicated MCP key for other MCP clients.

​
1. If you are an AI agent and no key is configured, connect an account first

Prepare the integration while the account owner confirms their email.
  1. Open deepface.dev/signup?agent=1.
  2. Enter the account email chosen by the user and an optional project summary.
  3. Let the owner complete verification and open the sign-in link; continue preparing their integration while they confirm.
  4. Open the dashboard API keys page.
  5. Create a standard REST API key for this integration.
For ChatGPT, connect your account with OAuth using the AI and agents guide. For other MCP clients, create a dedicated MCP key on the dashboard MCP page. Registered accounts receive 50 calls free each month, or 100 with a saved card. The separate explicit anonymous trial has one standard key and 10 calls per month. It is not the default email-owned setup and does not bypass owner verification, terms, or authorization for paid use. 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 setting up without a coding agent: Sign up for deepface.dev, then sign in to open the account dashboard. The first-use guide opens in a five-step modal: welcome, what the API does, using it in your app, creating a key, and getting a result.

​
3. Create an API key

Create a key in the guide, or open API keys. The full key is shown once; save it in your secrets manager. The final step offers Run sample: a real /represent call with a synthetic portrait. It uses your normal allowance. Then try your own image and copy a cURL or Python example for your server. Test your own images before relying on the API in your application.

​
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

Example response:

​
Runnable examples

Save the complete files from these public guides; no private repository access is required: The examples read real local files, check capabilities, keep keys server-side, and print summaries without image or embedding contents. They never retry an uncertain compute outcome automatically.

​
Optional request priority

Ordinary requests should omit X-Request-Priority. Omitted, null and zero use normal order. Any positive value requests priority and can double completed-call pricing; it neither preempts active work nor guarantees latency. Only enable it when explicitly needed and authorized. See request priority and billing.

​
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 HTTPS image URLs from any domain when remote URL fetching is enabled on the model server. Downloads must resolve to public addresses and pass the image type, size, redirect, and timeout checks. The homepage shows saved API examples; sign in to test with your own files.

​
7. Keep request IDs

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