Vision: identify a perfume from a photo
POST /v1/vision/identify: send a bottle photo and get the exact perfume and its five closest candidates. Parameters, response and best practice.
POST https://api.ourscent.online/v1/vision/identifyThe image
- A raw body with Content-Type image/jpeg, image/png or image/webp;
- or multipart with an image field;
- or JSON: {"image_url": "https://…"} or {"image_base64": "…"}.
- Up to 10 MB.
Parameters
| param | Description |
|---|---|
k | How many candidates (1–10, default 5) |
expand=perfume | Adds the full perfume record to each candidate |
lang | ar, en or fr for note names and descriptions |
curl -X POST "https://api.ourscent.online/v1/vision/identify?k=5" \
-H "Authorization: Bearer os_live_…" \
-H "Content-Type: image/jpeg" \
--data-binary @bottle.jpgJSON
{
"model": "c-20261122",
"candidates": [
{
"perfume_id": "Khamrah-Lattafa-Perfumes-Lattafa-Perfumes",
"score": 0.91,
"name": "Khamrah",
"name_ar": "خمرة",
"brand": { "id": "lattafa", "name": "Lattafa", "name_ar": "لطافة" },
"thumbnail_url": "https://ourscent.online/perfume-images/…/w400.webp"
},
{ "perfume_id": "Khamrah-Qahwa-Lattafa-Perfumes-Lattafa-Perfumes", "score": 0.06, "…": "…" }
],
"request_id": "req_8f2c…"
}Best practice
- Show the user the top three: accuracy is 93.2% in the top 3 against 77.6% for the first.
- One bottle in the middle of the frame, well lit.
- Send corrections to POST /v1/vision/feedback when a user corrects the answer.
Barcode
POST /v1/barcode/lookup with {"ean": "…"} returns the perfume and size (0.2 credit). Coverage grows as shops’ barcode data arrives.