Skip to main content
Have a photo of a look you want to match? Point image search at a public garment image URL and it returns the visually closest items in your catalog, ranked by relevance — exactly like text search. Each result is a garment id and url you can pass into Generation.
This endpoint needs only your tenant key — send x-api-key and nothing else, with no Authorization: Bearer token. BASE_URL is the Souldi API base URL, https://api.souldi.io. See the authentication model.

Search by image

Finds garments in your catalog that are visually similar to a reference image you provide. Results are ranked by z_score, exactly like text search. Required headers Query parameter
string
required
A public URL of the reference garment image, passed in the URL query string (not the JSON body). For example ?query=https://shop.example.com/inspo.jpg.
Body parameters
integer
default:"3"
Maximum number of garments to return. Range 110.
number
default:"1.0"
Relevance floor in standard deviations above the query’s mean. Range -5.05.0. See How relevance works.
integer
default:"50"
Size of the candidate pool that defines the z_score baseline. Range 1200.
The reference image URL must be publicly reachable — Souldi fetches it server-side to compare against your catalog. URLs behind authentication or on private networks will fail.
Response fields
object[]
The matching garments, ordered most-relevant first. May be empty if nothing clears min_z_score.
string
The garment’s unique ID. Use it to reference the garment elsewhere.
string
The garment image URL — pass this into POST /try-on/generate to try it on.
number
The relevance score for this query. See How relevance works.
The response shape is identical to text search: a garments array of { id, url, z_score }. For the shared status codes and the empty-result case, see Errors.

Next steps

Search by text

Use a natural-language query when you don’t have a reference image.

Search by attributes

Switch to exact faceted filters across ten garment attributes.

Try a garment on

Pass a result url to POST /try-on/generate to render it on your user.