Send the image as the multipart field image or as image_base64 (raw base64 or a data URI), not both. The maximum size is 10 MB. JPEG, PNG, WebP, GIF and AVIF are accepted. The image is resized to at most 1600 px, converted to JPEG and stripped of EXIF data. It is kept at most 15 minutes and deleted right after the search. The response has the same visual_matches, exact_matches, and related_content arrays as the URL search. search_parameters.url is null and search_parameters.image is upload.
Run this endpoint
Endpoint
Parameters
Start with the required fields, then add optional filters only when your use case needs them.
Runnable path
This endpoint has no required query parameters.
4 optional filters available.
file
Optional
Image file as a multipart form field. Send this or image_base64.
example
string
Optional
Base64 encoded image or a data:image/...;base64, URI. Send this or image.
example
string
Optional
Optional text used to refine visual or product matches.
coffee shops
string
Optional
One of all, products, exact_matches, or visual_matches.
example
Response Schema
Example response fields are illustrative; inspect the JSON before integrating.
Example response fields
Scan these fields before integrating.
search_parameters
visual_matches
exact_matches
related_content
Common visual_matches fields
source
title
link
thumbnail
{
"search_parameters": {
"url": null,
"image": "upload",
"q": null,
"type": "visual_matches"
},
"visual_matches": [
{
"source": "Wikipedia",
"title": "Coffee cup",
"link": "https://en.wikipedia.org/wiki/Coffee",
"thumbnail": "https://encrypted-tbn0.gstatic.com/images?q=tbn:example",
"price": null,
"position": 1
}
],
"exact_matches": [],
"related_content": []
}
Errors
Handle these documented responses before retrying or showing customer-facing failures.
HTTP 422
Upload only (POST). The file is not a JPEG, PNG, WebP, GIF or AVIF image that can be decoded. Not billed. Retrying the same file does not help.
{
"error": "The uploaded file is not a valid JPEG, PNG, WebP, GIF or AVIF image.",
"retryable": false,
"error_code": "INVALID_IMAGE_UPLOAD"
}HTTP 422
Google Lens reported that it could not load the image. Not billed. Retrying the same URL does not help.
{
"error": "Google Lens could not load a valid image from the supplied URL.",
"retryable": false,
"error_code": "INVALID_IMAGE"
}HTTP 422
Google Lens returned an empty result page. This usually means Google could not download the image (HTTP error, hotlink or bot protection, or an expired signed URL). Not billed. Retrying the same URL does not help; use a URL that loads publicly.
{
"error": "Google Lens returned no matches for this image. Google usually shows this when it cannot download the image (HTTP error, hotlink or bot protection, or an expired signed URL). Check that the URL loads publicly, or use a different image URL.",
"retryable": false,
"error_code": "IMAGE_NOT_PROCESSED"
}HTTP 503
Google blocked the request. Not billed and retryable.
{
"error": "Google Lens blocked the visual search request.",
"retryable": true,
"error_code": "GOOGLE_LENS_BLOCKED"
}HTTP 503
Google returned an unexpected result layout. Not billed and retryable.
{
"error": "Google Lens returned an unexpected result layout.",
"retryable": true,
"error_code": "PARSE_DRIFT"
}HTTP 503
The upstream service is temporarily unavailable. Please retry shortly.
{
"error": "The upstream service is temporarily unavailable. Please retry shortly.",
"retryable": true,
"error_code": "upstream_unavailable"
}Generate Code with AI
Copy a ready-made prompt with all the endpoint details, parameters, and example responses. Paste it into ChatGPT, Claude, or any AI assistant to instantly generate working code.
Try It Live
Test this endpoint in our interactive playground with real data.