Search by image

Search by image ranks your library by how closely each prop resembles a picture you provide. Use concept art for a set you are dressing, a screenshot of a scene you want to match, or a photo of a real object.

In the apps

In the desktop app or web library, click Search by image next to the search box and pick a PNG or JPEG file. The best visual matches (up to 50) appear in place of the grid, under a banner showing your image. Click Clear image search to go back to normal results.

The apps rank against the whole library and do not apply the filters you have set. To combine an image with filters, use the API or the agent tool below.

Image requirements

• PNG or JPEG. Other formats, including WebP and GIF, are refused.
• Up to 16 MB through the apps and the REST API.
• Through the MCP tool, the whole request must fit in 1 MB, so keep the image under about 500 KB before base64 encoding. A few hundred pixels across is plenty.

In the API and for agents

REST: send the image bytes as the request body.

curl -X POST "https://api.prophouse.dev/api/v1/entries/search/image?type=mesh&limit=20" \
  -H "Authorization: Bearer ph_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/octet-stream" \
  --data-binary @concept.jpg

MCP: the search_props_by_image tool with the image in image_base64.

Every filter works as a query parameter (REST) or argument (MCP). A text q (REST) or query (MCP) also works, but only as a keyword filter: results must match the words, and the ranking still comes from the image alone.

What you get back

A single page of results, best match first, up to limit (at most 200). There is no cursor: to see more, raise limit or narrow the filters. The response also includes total_ranked, the number of props that were ranked before the limit was applied.

Each result has a score for ordering only. It is not a similarity percentage.

Errors

Error	Cause
VALIDATION (422)	The file is not a PNG or JPEG, could not be read as an image, or is larger than 16 MB.
EMBEDDINGS_UNAVAILABLE (503)	Image search is temporarily unavailable. Text search is unaffected; try again later.