VisageDB

API access

Search from AI assistants, scripts, and apps using your existing credits.

Buy credits to enable API access. The free signup credit does not include API access.

Routes

All routes require Authorization: Bearer YOUR_API_KEY.

POST /api/v1/searches

Search an image. Allow at least 30 seconds for the response.

Parameters

Image (required, choose one)
  • image_url: public HTTP or HTTPS image URL, sent in JSON
  • image: file uploaded as multipart form data
  • image_base64: raw base64 string in JSON, without a data: prefix

JPEG, PNG, WebP, HEIC, or HEIF. Up to 14 MiB decoded and 25 megapixels.

Request example

Image URL:

curl https://visagedb.com/api/v1/searches \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"image_url":"https://example.com/photo.jpg"}'

File upload:

curl https://visagedb.com/api/v1/searches \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -F '[email protected]'

For base64, replace the image URL example’s JSON body:

{"image_base64":"BASE64_ENCODED_IMAGE"}

Response example (200 OK)

Always includes results.sfw and results.nsfw. Both lists use the fields shown below; a list is empty when it has no matches.

{
  "id": "SEARCH_ID",
  "results": {
    "sfw": [
      {
        "group_id": 123,
        "similarity": 0.92,
        "thumbnail_url": "https://example.com/thumbnail.webp",
        "thumbnail_crop": { "x": 12, "y": 0, "size": 420, "side": 432 },
        "image_url": "https://example.com/photo.jpg",
        "page_url": "https://example.com/source",
        "page_title": "Example page",
        "platform": "Example",
        "created_at": "2026-09-28T00:00:00Z"
      }
    ],
    "nsfw": []
  },
  "credits_charged": 1,
  "credits_remaining": 49
}

Within a search, results with the same group_id are likely copies or variations of the same image.

When thumbnail_crop is set and the thumbnail is side pixels square, show only the square of size pixels at x, y. It is null when the thumbnail needs no cropping.

Similarity ranks matches; it is not a probability of identity. created_at is when the face was indexed.

credits_charged is the original search cost, including on retries and lookups. credits_remaining is your current balance.

GET /api/v1/searches/:id

Retrieve your search results for free.

Parameters

id (required): the search ID returned by POST, in the URL. No body or query parameters.

Request example

curl https://visagedb.com/api/v1/searches/SEARCH_ID \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response example (200 OK)

Both result lists, the original search charge, and your current balance. This lookup does not charge again.

{
  "id": "SEARCH_ID",
  "results": {
    "sfw": [
      {
        "group_id": 123,
        "similarity": 0.92,
        "thumbnail_url": "https://example.com/thumbnail.webp",
        "thumbnail_crop": { "x": 12, "y": 0, "size": 420, "side": 432 },
        "image_url": "https://example.com/photo.jpg",
        "page_url": "https://example.com/source",
        "page_title": "Example page",
        "platform": "Example",
        "created_at": "2026-09-28T00:00:00Z"
      }
    ],
    "nsfw": []
  },
  "credits_charged": 1,
  "credits_remaining": 49
}

GET /api/v1/account

Check your balance for free.

Parameters

None.

Request example

curl https://visagedb.com/api/v1/account \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response example (200 OK)

{
  "credits_remaining": 49
}

Credits and limits

  • 1 credit per completed search, including no matches. Failed searches are free.
  • The same image within 5 minutes reuses your results for free. After that, a new POST costs 1 credit. Lookups stay free.
  • Per account: 10 new search attempts and 120 total requests per minute, one search at a time.

Errors

{"error":{"code":"insufficient_credits","message":"You need 1 credit to search."}}

Follow the error message. For rate limits, wait for Retry-After. For temporary errors or a lost response, retry the same image within 5 minutes.