​

No-face compatibility hold (6 October 2026)

The public API retains HTTP 422 with error: "no_face_detected" and detail for completed no-face detections while clients prepare for a coordinated change. These detections remain billable; genuine processing failures are not billed. The HTTP 200 rollout described below is superseded by this compatibility hold.

​

16 October 2026

Self-serve billing now uses the published image and vector rates with smooth volume discounts and final floors. Photo-to-vector checks count as one image call. Existing monthly invoice contracts keep their agreed prices.

​

6 October 2026 — completed no-face responses

Completed no-face detections now return HTTP 200 with outcome: "no_face_detected", faces: [] and detail, rather than HTTP 422. Check outcome before reading match or embedding fields. These completed calls remain billable; failures are uncharged. Historical usage statuses are preserved.

​

Changelog and versioning

deepface.dev ships the public API as a v1 contract.

​

2026-10-05 — Global scheduling groups

Queued eligible calls now run in strict order: enterprise with positive request priority, non-enterprise with positive priority, enterprise normal, then non-enterprise normal. Lower positive numbers still order the caller’s own waiting work within a group. The former 4:1 rotation and aging override no longer apply. Scheduling events record four_tier_v1 and the selected group. Billing rates and the optional_positive_v2 interpretation are unchanged.

​

5 October 2026: optional priority within your own account queue

X-Request-Priority now lets a call jump its own account’s normal waiting queue, across the account’s API keys on each gateway process. Any finite positive value requests priority; lower positive numbers run first. There is no upper bound of 1. Omitted, null and zero mean normal order, and zero is accepted. Other accounts’ turns and enterprise classes stay unchanged; active work is not preempted. Any explicitly positive own-queue priority doubles completed-call pricing. Negotiated request-only contracts include enterprise access at the standard rate. No-face results are billable; failures are free. Logs record own-queue priority application and scope separately from actual enterprise treatment. New receipts use optional_positive_v2; historical below_one_v1 receipts retain their earlier interpretation and charges.

​

5 October 2026: negotiated priority billing

Negotiated request-only contracts include enterprise access at the standard rate. Enterprise lane access alone adds no surcharge under this policy. Each call snapshots the contract billing policy separately from its actual scheduling conditions. Historical receipts retain their original interpretation and charges.

​

Wallet benefits — 5 October 2026

Enterprise accounts receive 300 requests/minute. Other accounts receive 15/minute by default, or 30/minute after funding a paid wallet. Lifetime USD wallet funding strictly above $10, $20, $50 and $100 raises the allowance to 60, 100, 200 and 300/minute. Verified credited live top-ups count; free credits and test payments do not. The existing limiter scope is per gateway process unless Redis is shared. Paid wallets with active auto top-up and a valid saved card receive 20% off usage prices, including priority usage. Each request records its discount; queued async jobs retain the discount agreed at enqueue. Monthly invoice contracts use their agreed tariff. See rate tiers.

​

Priority billing — 3 October 2026

Calls admitted from 21:10 UTC are charged at 2x the standard rate when they use an enterprise priority lane or a request priority below 1. Both together still cost 2x, even when the queue is idle. Failed calls remain uncharged. Existing charges and issued invoices are unchanged; historical priority is not inferred. Async compare keeps its standard service. The branded email/PDF and accounting integration were deployed on 3 October. Emails distinguish billable standard-rate and priority API calls. Period dates end on the last calendar day; Tech Local EFT details appear in the PDF only. Usage records now retain per-call priority treatment and the effective multiplier.

​

Request priority — 15 September 2026

• Synchronous /verify, /represent, and /compare accept the optional X-Request-Priority header, a finite positive number defaulting to 1. Lower numbers go first within an account’s waiting queue on each gateway process; equal effective priorities keep arrival order.
• MCP compute tools accept the equivalent numeric priority argument.
• Invalid values return 400 invalid_priority before billing reservation or inference. Experimental async compare rejects the header with 400 unsupported_priority.
• Existing requests keep their ordering when priority is omitted. Priority provides no preemption, reserved capacity, or latency guarantee. See request priority.

​

Versioning rules

• Breaking API changes require an explicit versioning decision before release.
• Non-breaking additions land in the changelog and OpenAPI spec together.
• Docs changes that alter endpoint behavior must update the canonical OpenAPI file in the same pull request.

​

Change process

• Update openapi/deepface.openapi.yaml.
• Regenerate docs-site/openapi/deepface.openapi.yaml.
• Run npm run docs:check.
• Include any customer-facing behavior changes in the pull request summary.