开发者 API

API 文档

免费REST API，提供结构化JSON响应。需要API密钥（免费）。已启用CORS。非常适合构建应用程序、推荐引擎或为LLM提供香水数据。

需要API密钥CORS 已启用JSON 响应

基础 URL

https://fraganty.ai

Image formats

Every perfume response includes two image URLs:

image — JPEG with background, ~20-30 KB, always available.
imageTransparent — WebP with transparent background, ~15-50 KB. Returns 404 with header X-Fraganty-Nobg-Status: not-processed for perfumes not yet pre-processed — fall back to image.

Both URLs are immutable, CDN-cached for 1 year, and CORS-enabled for direct use in browsers and native apps.

身份验证

所有API端点都需要免费的API密钥。通过X-API-Key请求头或api_key查询参数在每个请求中包含它。

请求头

X-API-Key: YOUR_API_KEY

查询参数

?api_key=YOUR_API_KEY

在api@fraganty.ai申请您的免费API密钥

Playground Pricing llms.txt sitemap.xml

GET/api/perfumes

列出和搜索香水

参数

名称	类型	描述
q	string	按名称搜索
brand	string	按品牌 slug 筛选
page	number	页码（默认：1）
limit	number	每页结果数（默认：20，最大：100）

示例请求

curl -H "X-API-Key: YOUR_KEY" https://fraganty.ai/api/perfumes?q=rose&limit=5

响应

{
  "data": [
    {
      "id": "rose-goldea-kathleen-kye-edition",
      "name": "Rose Goldea Kathleen Kye Edition",
      "brand": "Bvlgari",
      "year": 2021,
      "rating": 4.62,
      "concentration": null,
      "image": "https://img.fraganty.ai/perfume/64818.jpg",
      "imageTransparent": "https://img.fraganty.ai/perfume-nobg/64818.webp",
      "buyUrl": "https://fraganty.ai/goto/rose-goldea-kathleen-kye-edition",
      "accords": [
        { "name": "Rose", "strength": 100, "color": "#C4647C" },
        { "name": "Floral", "strength": 79, "color": "#9E3B52" }
      ]
    }
  ],
  "total": 2460,
  "page": 1,
  "pages": 492
}

GET/api/perfumes/:slug

获取完整的香水详情，包括香调、主调、评分、季节和相似香水

示例请求

curl -H "X-API-Key: YOUR_KEY" https://fraganty.ai/api/perfumes/bleu-de-chanel-eau-de-parfum

响应

{
  "id": "bleu-de-chanel-eau-de-parfum",
  "name": "Bleu de Chanel Eau de Parfum",
  "brand": "Chanel",
  "year": 2014,
  "rating": 4.21,
  "concentration": "Eau de Parfum",
  "gender": "masculine",
  "description": "...",
  "image": "https://img.fraganty.ai/perfume/25967.jpg",
  "imageTransparent": "https://img.fraganty.ai/perfume-nobg/25967.webp",
  "buyUrl": "https://fraganty.ai/goto/bleu-de-chanel-eau-de-parfum",
  "notes": {
    "top": [{ "name": "Lemon", "intensity": 80 }],
    "middle": [{ "name": "Cedar", "intensity": 90 }],
    "base": [{ "name": "Sandalwood", "intensity": 85 }]
  },
  "accords": [...],
  "seasons": { "winter": 45, "spring": 60, "summer": 30, "fall": 65 },
  "dayNight": { "day": 55, "night": 70 },
  "similarPerfumes": [...],
  "perfumers": [{ "name": "Olivier Polge" }]
}

GET/api/brands

列出所有品牌及香水数量

参数

名称	类型	描述
q	string	按名称搜索品牌

示例请求

curl -H "X-API-Key: YOUR_KEY" https://fraganty.ai/api/brands

响应

{
  "data": [
    { "name": "Guerlain", "slug": "Guerlain", "count": 412 },
    { "name": "Dior", "slug": "Dior", "count": 312 },
    { "name": "Chanel", "slug": "Chanel", "count": 248 }
  ],
  "total": 6619
}

GET/api/notes

列出所有香调及出现频率

参数

名称	类型	描述
limit	number	限制结果数（默认：全部）

示例请求

curl -H "X-API-Key: YOUR_KEY" https://fraganty.ai/api/notes?limit=5

响应

{
  "data": [
    { "name": "Musk", "count": 3097 },
    { "name": "Bergamot", "count": 2498 },
    { "name": "Rose", "count": 2460 }
  ],
  "total": 981
}

GET/api/perfumers

列出所有调香师及香水数量

示例请求

curl -H "X-API-Key: YOUR_KEY" https://fraganty.ai/api/perfumers

响应

{
  "data": [
    { "name": "Alberto Morillas", "slug": "alberto-morillas", "count": 45 },
    { "name": "Olivier Polge", "slug": "olivier-polge", "count": 38 }
  ],
  "total": 358
}

GET/api/perfumers/:slug

获取调香师详情及其香水（分页）

参数

名称	类型	描述
page	number	页码（默认：1）
limit	number	每页结果数（默认：20）

示例请求

curl -H "X-API-Key: YOUR_KEY" https://fraganty.ai/api/perfumers/alberto-morillas

响应

{
  "name": "Alberto Morillas",
  "slug": "alberto-morillas",
  "perfumes": {
    "data": [...],
    "total": 45,
    "page": 1,
    "pages": 3
  }
}

GET/api/perfumes/:slug/similar

Find similar perfumes based on accord cosine similarity, note overlap, and curated data

参数

名称	类型	描述
limit	number	Max results (default 10, max 20)

示例请求

curl -H "X-API-Key: YOUR_KEY" https://fraganty.ai/api/perfumes/bleu-de-chanel-eau-de-parfum/similar?limit=5

响应

{
  "source": { "id": "bleu-de-chanel-eau-de-parfum", "name": "Bleu de Chanel EDP", "brand": "Chanel" },
  "data": [
    {
      "id": "sauvage-dior",
      "name": "Sauvage",
      "brand": "Dior",
      "matchScore": 87,
      "image": "https://img.fraganty.ai/perfume/12345.jpg",
      "imageTransparent": "https://img.fraganty.ai/perfume-nobg/12345.webp",
      "sharedAccords": [{ "name": "Woody", "strength": 95, "color": "#6B4226" }],
      "sharedNotes": ["bergamot", "cedar"],
      "accords": [...]
    }
  ],
  "total": 5
}

GET/api/perfumes/:slug/dupes

Find cheaper alternatives (dupes) to a luxury/premium perfume. Returns perfumes with matching accord/note profiles at a lower price tier.

参数

名称	类型	描述
limit	number	Max results (default 20, max 50)

示例请求

curl -H "X-API-Key: YOUR_KEY" https://fraganty.ai/api/perfumes/bleu-de-chanel-eau-de-parfum/dupes?limit=10

响应

{
  "source": {
    "id": "bleu-de-chanel-eau-de-parfum",
    "name": "Bleu de Chanel EDP",
    "brand": "Chanel",
    "image": "https://img.fraganty.ai/perfume/25967.jpg",
    "imageTransparent": "https://img.fraganty.ai/perfume-nobg/25967.webp",
    "rating": 4.21
  },
  "data": [
    {
      "id": "oakcha-eastern-bliss",
      "name": "Eastern Bliss",
      "brand": "Oakcha",
      "priceTier": "affordable",
      "matchScore": 87,
      "rating": 4.35,
      "image": "https://img.fraganty.ai/perfume/76543.jpg",
      "imageTransparent": "https://img.fraganty.ai/perfume-nobg/76543.webp",
      "sharedAccords": [{ "name": "Citrus", "strength": 100, "color": "#DAA520" }],
      "sharedNotes": ["bergamot", "cedar"],
      "accords": [...]
    }
  ],
  "total": 15
}

GET/api/perfumes/match

Match perfumes by accords, notes, gender, season, and time of day

参数

名称	类型	描述
accords	string	Comma-separated accords with optional strength (e.g. woody:80,amber:60)
notes	string	Comma-separated note names (e.g. bergamot,cedar)
gender	string	Filter by gender: masculine, feminine, unisex
season	string	Filter by best season: winter, spring, summer, fall
time	string	Filter by best time: day, night
page	number	页码（默认：1）
limit	number	Results per page (default 20, max 50)

示例请求

curl -H "X-API-Key: YOUR_KEY" https://fraganty.ai/api/perfumes/match?accords=woody:80,amber&notes=bergamot&season=winter

响应

{
  "data": [
    {
      "id": "tobacco-vanille",
      "name": "Tobacco Vanille",
      "brand": "Tom Ford",
      "matchScore": 92,
      "rating": 4.31,
      "accords": [...]
    }
  ],
  "filters": { "accords": ["woody:80", "amber"], "notes": ["bergamot"], "season": "winter" },
  "total": 145,
  "page": 1,
  "pages": 8
}

GET/api/accords

List all fragrance accords with perfume counts and colors

参数

名称	类型	描述
search	string	Filter accords by name
limit	number	Max results (default 50, max 100)

示例请求

curl -H "X-API-Key: YOUR_KEY" https://fraganty.ai/api/accords?search=woody

响应

{
  "data": [
    { "name": "Woody", "count": 42350, "color": "#6B4226" },
    { "name": "Warm Spicy", "count": 18200, "color": "#A0522D" }
  ],
  "total": 3
}

名称

类型

描述

string

按名称搜索

brand

string

按品牌 slug 筛选

page

number

页码（默认：1）

limit

number

每页结果数（默认：20，最大：100）

{ "data": [ { "id": "rose-goldea-kathleen-kye-edition", "name": "Rose Goldea Kathleen Kye Edition", "brand": "Bvlgari", "year": 2021, "rating": 4.62, "concentration": null, "image": "https://img.fraganty.ai/perfume/64818.jpg", "imageTransparent": "https://img.fraganty.ai/perfume-nobg/64818.webp", "buyUrl": "https://fraganty.ai/goto/rose-goldea-kathleen-kye-edition", "accords": [ { "name": "Rose", "strength": 100, "color": "#C4647C" }, { "name": "Floral", "strength": 79, "color": "#9E3B52" } ] } ], "total": 2460, "page": 1, "pages": 492 }

{ "id": "bleu-de-chanel-eau-de-parfum", "name": "Bleu de Chanel Eau de Parfum", "brand": "Chanel", "year": 2014, "rating": 4.21, "concentration": "Eau de Parfum", "gender": "masculine", "description": "...", "image": "https://img.fraganty.ai/perfume/25967.jpg", "imageTransparent": "https://img.fraganty.ai/perfume-nobg/25967.webp", "buyUrl": "https://fraganty.ai/goto/bleu-de-chanel-eau-de-parfum", "notes": { "top": [{ "name": "Lemon", "intensity": 80 }], "middle": [{ "name": "Cedar", "intensity": 90 }], "base": [{ "name": "Sandalwood", "intensity": 85 }] }, "accords": [...], "seasons": { "winter": 45, "spring": 60, "summer": 30, "fall": 65 }, "dayNight": { "day": 55, "night": 70 }, "similarPerfumes": [...], "perfumers": [{ "name": "Olivier Polge" }] }

名称

类型

描述

string

按名称搜索品牌

{ "data": [ { "name": "Guerlain", "slug": "Guerlain", "count": 412 }, { "name": "Dior", "slug": "Dior", "count": 312 }, { "name": "Chanel", "slug": "Chanel", "count": 248 } ], "total": 6619 }

名称

类型

描述

limit

number

限制结果数（默认：全部）

名称

类型

描述

page

number

页码（默认：1）

limit

number

每页结果数（默认：20）

名称

类型

描述

limit

number

Max results (default 10, max 20)

{ "source": { "id": "bleu-de-chanel-eau-de-parfum", "name": "Bleu de Chanel EDP", "brand": "Chanel" }, "data": [ { "id": "sauvage-dior", "name": "Sauvage", "brand": "Dior", "matchScore": 87, "image": "https://img.fraganty.ai/perfume/12345.jpg", "imageTransparent": "https://img.fraganty.ai/perfume-nobg/12345.webp", "sharedAccords": [{ "name": "Woody", "strength": 95, "color": "#6B4226" }], "sharedNotes": ["bergamot", "cedar"], "accords": [...] } ], "total": 5 }

名称

类型

描述

limit

number

Max results (default 20, max 50)

{ "source": { "id": "bleu-de-chanel-eau-de-parfum", "name": "Bleu de Chanel EDP", "brand": "Chanel", "image": "https://img.fraganty.ai/perfume/25967.jpg", "imageTransparent": "https://img.fraganty.ai/perfume-nobg/25967.webp", "rating": 4.21 }, "data": [ { "id": "oakcha-eastern-bliss", "name": "Eastern Bliss", "brand": "Oakcha", "priceTier": "affordable", "matchScore": 87, "rating": 4.35, "image": "https://img.fraganty.ai/perfume/76543.jpg", "imageTransparent": "https://img.fraganty.ai/perfume-nobg/76543.webp", "sharedAccords": [{ "name": "Citrus", "strength": 100, "color": "#DAA520" }], "sharedNotes": ["bergamot", "cedar"], "accords": [...] } ], "total": 15 }

名称

类型

描述

accords

string

Comma-separated accords with optional strength (e.g. woody:80,amber:60)

notes

string

Comma-separated note names (e.g. bergamot,cedar)

gender

string

Filter by gender: masculine, feminine, unisex

season

string

Filter by best season: winter, spring, summer, fall

time

string

Filter by best time: day, night

page

number

页码（默认：1）

limit

number

Results per page (default 20, max 50)

{ "data": [ { "id": "tobacco-vanille", "name": "Tobacco Vanille", "brand": "Tom Ford", "matchScore": 92, "rating": 4.31, "accords": [...] } ], "filters": { "accords": ["woody:80", "amber"], "notes": ["bergamot"], "season": "winter" }, "total": 145, "page": 1, "pages": 8 }

名称

类型

描述

string

Filter accords by name

limit

number

Max results (default 50, max 100)