MotionGit 背景音乐 API：给 AI 助手的调用说明

基础地址：https://motiongit.com/api/v1。先读取公开的 /capabilities，只有 licensed-music.status=ready 才调用。音乐库检索、试听、选用、下载目前均为 0 平台点数，不调用付费生成供应商；音乐生成接口已实现，但当前供应商账户余额耗尽，保持关闭。新接口与剩余额度见统一素材调用说明。

用户 Key 与权限

使用用户自己的 MotionGit 平台 Key，放入 Authorization: Bearer mgk_...。在 API Keys 创建：

music.search：类型列表、搜索、单曲信息、试听。
assets.read：完整音乐下载、本人已选用素材下载。
assets.write：选用到私人素材库、删除自己的素材。
usage.read：核对余额与请求记录。
如果设置模型白名单，包含 licensed-music。可以设置单次、每日、每月预算为 0；这些音乐操作仍可使用。

供应商 Key 由网站保管，无需传给助手。配音专用 Key、历史 .motion 下载 Key 不一定有音乐权限；不要默认可以混用。用户 Key 不写进公共 .motion 包、源码、聊天记录或 URL。浏览器 <audio> 不便设置授权头时，使用登录后的 Playground，或由客户端带授权头取得音频再创建临时 Blob URL。

本机已配置用户可从 /Users/michael/.config/motiongit/music.env 加载 MOTIONGIT_API_KEY，不要打印文件内容。其它设备的用户应自行创建自己的 Key。

1. 取得类型与当前数量

GET /music/categories

返回 total、types[{id,label,label_en,count}]、moods、genres、费用和限速。每首可归入多个类型，分类数量之和可能大于总曲数。

type	用途
talking-head	口播讲解
technology	科技产品
upbeat	轻快日常
emotional	温暖抒情
cinematic	史诗叙事
suspense	悬疑紧张
ambient	安静氛围
game	游戏复古

quota_remaining=null 表示平台没有独立的“音乐剩余调用次数/秒数”计数，不能解释为无限调用，也不是供应商余额。当前限速：搜索每账号30次/分钟、媒体每账号60次/分钟、选用每账号10次/分钟；统一网关另有每 Key 120次/分钟、每账号240次/分钟。X-MotionGit-Credits-Remaining 仅为账号共享平台点数。不要用该余额推算音乐剩余时长。

2. 搜索多个候选

GET /music/search，也可用 /search?kind=music&provider=licensed。

参数	规则
q	可省略；最多100个 Unicode 码点，匹配中英文标题、作者、标签；多个词需全部命中
type	上表中的一个用途 ID
mood	calm / bright / warm / reflective / tense / epic / playful / mysterious
genre	ambient / piano / orchestral / rock / electronic / chiptune / acoustic
min_duration / max_duration	实际完整文件时长，单位秒；0–3600，支持小数；上下界都包含
exclude	排除已使用的曲目 ID，英文逗号分隔，最多30个
page / limit	从1开始；默认每页12首，最多30首

不同条件取交集，可能返回空结果。未支持的 BPM、energy、duration_s、voiceover_friendly 参数会被拒绝；不能把剪辑目标时长当作完整音乐时长。需要30秒成片时，可检索至少30秒音乐后在本地裁剪。编辑分类只是选择建议，请试听确认；bpm=null、loopable=null 表示未测量/未确认，不能编造节奏或无缝循环保证。

curl --get 'https://motiongit.com/api/v1/music/search' \
  -H "Authorization: Bearer $MOTIONGIT_API_KEY" \
  --data-urlencode 'type=talking-head' \
  --data-urlencode 'mood=calm' \
  --data-urlencode 'min_duration=60' \
  --data-urlencode 'limit=5'

响应包含 total（筛选后数量）、page、next_page（末页为null）、credits=0、results。每首包含：

id / source_asset_id、title、title_zh、duration_s、actual_specs（实际时长、采样率、声道）。
music：types、moods、genres、tags、bpm、loopable、classification_source。
preview、preview_duration_ms、preview_sha256：最多30秒试听及校验值。
download、sha256、bytes、mime：完整音乐及校验值。
source_url、attribution、license：作者、原始来源、许可及核验依据。
source_ref、expires_at：与当前用户绑定的十分钟选用引用；过期后重新搜索/读取单曲信息。

3. 试听、选用和下载

GET /music/{id} 返回单曲元数据及新的选用引用。

GET /music/{id}?mode=preview 返回试听音频；GET /music/{id}?mode=download 返回完整音乐。均须授权头，支持 HTTP Range（206/416），不会重新生成或扣点。预览不能替代完整文件。比较 SHA-256 时请完整下载；响应头 X-MotionGit-Media-SHA256 对应当前请求的试听或完整文件。

需要在网站私人素材库保留所选曲目时：

POST /api/v1/assets/select
Authorization: Bearer <用户 MotionGit Key>
Content-Type: application/json

{"source_ref":"<搜索返回的 source_ref>","purpose":"local_creation"}

返回201，包含 id=ast_...、实际规格、rights、source 和本人下载地址 /api/v1/assets/{id}/download。文件默认私有并保留30天；使用同一用户且有 assets.read 的 Key 下载。选用会新建素材，重复提交不保证去重；拿到成功结果后直接下载，避免重复选用。可用 DELETE /api/v1/assets/{id} 删除自己的副本。

推荐助手流程：查类型 → 按用途返回3–5首 → 让用户试听或根据已授权的选择偏好选曲 → 选用/完整下载 → 校验文件 → 本地裁剪、混音与配音避让 → 在交付清单保留来源及许可。music.loopable=true 也应在裁剪点试听接缝；MP3 编码延迟可能影响循环。

当前曲库与运行方式

当前共99首，总时长约219.16分钟，每首均有试听。新增79首涵盖安静口播、钢琴、吉他爵士、轻快民谣、电子舞曲、探索与悬疑等用途。数量以 /music/categories 实时返回为准。

当前99首，其中首批20首来自 OpenGameArt 作者发布的 Alexander Ehlers 音乐包、Zane Little 芯片音乐，以及 Yoiyami、The Cynic Project、SpringySpringo、Cleyton Kauffman 的独立作品。每首返回其原始页面。选用的 CC0 1.0 允许复制、改编和商业分发；保留作者信息便于追溯，不表示作者为使用者背书。

服务端保存源文件下载地址、原始 SHA-256、许可核验日期、交付文件 SHA-256、真实探测规格。完整曲目统一为44.1kHz双声道160kbps MP3，试听为最多30秒的128kbps MP3，并加结尾淡出；未做自动配音压低或响度混音。音乐清单是部署管理的本地只读资源，用户选用副本沿网站现有私有存储流程保存（包括R2）。

缺失、校验失败、许可过期、重复 ID、越界路径和已撤回条目不参与搜索、分类和新选用；已撤回的私人副本停止下载。错误码：401无效Key；403权限/模型不允许；404曲目或引用不存在；410来源撤回；429限速；503曲库未开放或有效曲目为空。未知过滤参数返回400，助手应按本文参数修正，不盲目重试。

新增79首采用作者发布的安静音乐包、中世纪民谣、吉他爵士及舒缓氛围等。10首电子舞曲BPM来自作者说明，其他未确认值继续返回null。

运维重建使用 scripts/ops/import-music-library.py，来源清单为 resources/music/sources-cc0-20261009.json 和 resources/music/sources-cc0-expansion-20261009.json，完整运行清单为 resources/music/catalog-cc0-expanded-20261009.json：固定源文件哈希，验证完整解码和非静音，生成音乐及试听文件，再以版本化清单部署。不要把仅允许用于成片、禁止独立再分发的素材加入这个曲库。