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 JSONimage: file uploaded as multipart form dataimage_base64: raw base64 string in JSON, without adata: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.