MotionGit .motion 模板背景音乐 API

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

在模板内准备本期配乐

新包先读 assistant/guide.json 的 templateApi。校验随包入口后，直接用原包调用，不另存 Key：

node assistant/motion.mjs api /原始个人模板.motion usage
node assistant/motion.mjs api /原始个人模板.motion music-prepare /本期实例/music-request.json /本期实例/music-v1

音乐请求填写本期文案、模板风格、目标时长。工具完成推荐、下载、校验和时长适配后，按模板公开参数绑定返回的 background.wav，再检查预览和成片。音乐库与其他免费素材共享每日30次/账号，各 Key 和模板共用；查找、推荐、信息读取和下载等分别计请求。用量结果的 free_material_requests 返回剩余次数和重置时间，Asia/Shanghai 00:00 重置；与付费积分独立。旧包可从 usage.template_api_guide 获取当前指引。站方新导入音乐由官方工具 1.0.0-rc.51 起支持；旧版本保持兼容的原曲库推荐。已有个人包按官方工具刷新流程更新，不手工替换受保护文件。

以下为普通 HTTP 客户端的底层参考，模板制作优先使用随包入口。

用户 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。

普通 HTTP 客户端从用户自己的私有配置读取平台 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 是兼容字段；当前应读取 free_material_requests 的每日共享请求额度（默认30次/账号），不能解释为无限调用或供应商余额。当前限速：搜索每账号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 / lofi / jazz / funk / folk / classical
energy	low / medium / high
voiceover	preferred / possible / avoid
instrument	从分类接口 instruments 选择
min_duration / max_duration	实际完整文件时长，单位秒；0–3600，支持小数；上下界都包含
exclude	排除已使用的曲目 ID，英文逗号分隔，最多30个
page / limit	从1开始；默认每页12首，最多30首

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

curl --get 'https://motiongit.cn/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 编码延迟可能影响循环。

当前曲库与运行方式

曲库由后台维护，包含原有曲目与站方导入音乐；当前数量从 /music/categories 返回的 total 获取。

服务端保存原始及交付文件 SHA-256、逐曲元数据和真实探测规格。许可核验信息仅在有依据时填写。导入音频保留各自可播放规格，修复副本另存；采样率、声道与实际时长读取 actual_specs，不能假定全库统一码率。每首提供最多30秒的试听，不代替完整文件；未做自动配音压低或响度混音。曲库文件保存在 R2，并在服务端保留校验后的交付缓存；用户选用副本沿网站现有私有存储流程保存。

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

原曲库的历史扩充包含作者发布的安静音乐包、中世纪民谣、吉他爵士及舒缓氛围等。已知的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：固定源文件哈希，验证完整解码和非静音，生成音乐及试听文件，再以版本化清单部署。站方导入曲目使用 rights_policy=operator-provided；原有曲目的元数据保持不变。

自动匹配标签（2026-10-14）

每首曲目的 music 包含用途 types、情绪 moods、风格 genres 和中英文 tags。新版还返回：

字段	可选值或含义
energy	low 柔和、medium 适中、high 强烈，按编辑分类标记
voiceover	preferred 优先口播、possible 可选、avoid 不适合口播
instruments	已识别的乐器类别，例如 piano、guitar、orchestra
rhythm	beat-driven 节拍主导、ambient 氛围、melodic 旋律、unknown 未确定
vocals	none 已有纯器乐标记、present 有人声、unknown 未确认
bpm	已有依据的 BPM；未知为 null，不以情绪猜数字
loopable	true / false / null；未知不能当作可无缝循环
audio_analysis	FFmpeg 30 秒内采样的平均音量、峰值和采样位置，供混音参考；不是全曲 LUFS
annotation_version	motiongit.music-tags/2

查询可组合 energy、voiceover、instrument，其它类型、情绪、风格、时长及排除条件仍可同时使用。例如：

GET /api/v1/music/search?genre=lofi&energy=low&voiceover=preferred&limit=6
GET /api/v1/music/search?instrument=piano&type=talking-head&min_duration=60

genres 增加 lofi、jazz、funk、folk、classical。当前枚举从 /api/v1/music/categories 读取。

POST /api/v1/music/recommend 会同时读取正文和模板提示中的情绪、风格，结合口播适配、乐器、强度、实际时长及排除列表排序。matching.instruments 返回本次匹配的乐器；例如“贝斯伴奏”或“bass accompaniment”会优先选择标记 bass 的曲目。推荐结果沿用原合同，仍为 0 点。明确标记人声的曲目不会自动作为背景曲推荐。

最新27首的重建来源为 scripts/ops/music-library-more-20261014.manifest.json，按固定源摘要导入后以 annotate-music-library.py 配合实际音量测量生成标记，合并旧130首清单；MP3/OGG同曲副本和慢速替代版本不重复入库。