Synth.Directory

API · 测试版 0.1.1

该 API

目录中的一切均以 JSON 形式提供：包含来源和媒体的主张、曲目、艺人、乐器、搜索，以及一种提议新条目的方式，它会进入与网站相同的审核队列。 该 API 处于测试阶段。 版本 0.1.1。随着目录逐渐完善，字段名称和结构可能会变化；变更记录列在本页底部，OpenAPI 文档始终是当前准确的契约。

获取令牌

  1. 创建账户并登录。
  2. 打开 API 令牌 在「我的」下创建一个。它只会显示一次，前缀为 sd_.
  3. 在每次请求中将其作为持有者令牌发送。
curl -H "Authorization: Bearer sd_..." "https://synth.directory/api/v1/claims?q=juno&status=verified"

限制

每个令牌每小时 200 次请求。每个响应都带有 X-RateLimit-Limit 和 X-RateLimit-Remaining；超出限制会收到带 JSON 消息的 429 错误。合作伙伴与目录自身的机器人可申请不限量层级，请联系咨询。

读取

列表分页显示：page 和 per_page（最多 100），响应体中带有 next_page。

  • GET /api/v1/claims · q, status, origin, artist, instrument, role, since, order · GET /api/v1/claims/{id}
  • GET /api/v1/records · q, artist_id, status=wanted|claimed, since, order, with=claims · GET /api/v1/records/{id}
  • GET /api/v1/artists?q= · GET /api/v1/artists/{id}
  • GET /api/v1/instruments · q, maker, kind · GET /api/v1/instruments/{id}
  • GET /api/v1/people?q= · 演奏者与制作人 · GET /api/v1/people/{id} · 及其已采纳的署名
  • GET /api/v1/search?q= · 在一次答案中同时给出艺人、曲目和乐器

状态： verified, potentially, submitted, inferred (来自知识库，尚无来源), disputed. 一条主张记录如下方导出内容中的一行所示。

预设、评分和收藏仅供网站上的用户使用，不包含在 API 中，也永远不会被导出。

提议

POST /api/v1/propose 会像网站一样将提议加入队列；发布前均由人工审核。令牌名称会记录在提议上，以便审核时能看出是机器人提交的。

{"kind": "claim", "work_id": 101, "instrument": "Minimoog", "instrument_maker": "Moog", "role": "lead",
 "source": {"grade": "A", "kind": "interview", "url": "https://...", "publication": "Sound On Sound",
            "author": "...", "published_on": "1983-06-01", "quote": "one sentence, verbatim"}}
{"kind": "source", "claim_id": 202, "source": {...}}
{"kind": "artist", "name": "Tool", "country": "US", "refs": ["https://en.wikipedia.org/...", "https://musicbrainz.org/..."]}
{"kind": "record", "artist_id": 12, "title": "Lateralus", "year": 2001, "refs": ["https://musicbrainz.org/..."]}
{"kind": "credit", "subject": "claim", "id": 202, "person": "Vince Clarke", "part": "played", "note": "on the intro only"}
{"kind": "credit", "subject": "work", "id": 101, "person": "Flood", "part": "produced"}

署名分类：主张 played, programmed · 曲目 produced, engineered, mixed, arranged. 系统会按姓名对人物进行不区分大小写的匹配，若不存在则新建。署名是事实性数据，因此与预设不同，它们会出现在 API 和导出内容中。

整个目录

GET /export/manifest.json 是公开的，说明其中包含什么。 GET /export/claims.jsonl 以每行一个 JSON 对象的形式，流式传输每条主张及其来源和已接受的媒体，支持 since 和 status 过滤。需要导出令牌，请联系咨询。

许可协议

各项事实以 CC0 发布。目录作为一个整体，以及诸如导出内容之类的任何大量摘录，均采用开放数据库许可协议（ODbL）：需为本目录署名，并将您据此衍生的数据库回馈共享。如需闭源产品的商业许可，可向 Box Of Rules 申请。

契约内容

OpenAPI 3.1 文档 · llms.txt · ai-catalog.json

变更记录

  • 0.1.1 (2026年9月10日) 人物：主张和曲目上的演奏与制作署名、人物相关接口、署名提案。
  • 0.1.0 (2026年9月10日) 首个测试版：令牌，每小时 200 次；读取主张、曲目、艺人、乐器和搜索；提议主张、来源、艺人和曲目；导出源。