OurScent

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/identify

The 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

paramDescription
kHow many candidates (1–10, default 5)
expand=perfumeAdds the full perfume record to each candidate
langar, 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.jpg
JSON
{
  "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.

Your first key in two minutes

Sign in with your OurScent account, create a test key, send your first call.