MotionGit API

这些接口为 .motion 模板补齐本期图片、视频、动效贴纸、配乐和旁白。素材保存在本期制作实例，按模板公开参数绑定，再检查预览和成片。无需依赖特定助手品牌。

从个人模板包调用

先读取 00-START-HERE.md 和 assistant/guide.json，按官方 HTTPS 元数据校验随包工具，再执行：

node assistant/motion.mjs start /原始个人模板.motion
node assistant/motion.mjs api /原始个人模板.motion status

新包 assistant/guide.json 的 templateApi 包含完整素材流程；旧包也能从 usage.template_api_guide 获取当前指引。包内调用复用下载者自己的原账户 Key，不用另外保存凭据、手拆 personal/ 或索取供应商 Key。不同模板与后续下载复用账号选定的原 Key，不会每次下载签发新 Key。停用、撤销、权限和预算以当前账号设置为准；模板作者的 Key 不会交给下载者。

免费请求与付费积分

免费图片/视频查找、贴纸和音乐库不扣积分。每账号每日 30次素材请求，所有 Key 与模板共用，Asia/Shanghai 00:00 重置。
查找、选用、下载分别计为一次请求。复用实例内已准备的素材，避免重复调用。查询用量和报价不占用免费素材请求次数，也不扣积分。
free_material_requests 返回每日上限、当日剩余次数及重置时间。到达上限返回429，等待重置，无需充值。
第三方付费的生图、TTS等服务另按用户预算先报价再提交；credits.remaining 为积分余额，Key日/月积分预算与免费请求次数独立。
积分为0不影响已授权的免费素材接口。scope_denied 表示原 Key 未授权，不表示平台缺少接口。

先判断本期需要什么

先读目标与已有素材，再核对所选工作流的真实输入。没有录音不等于不要旁白；需要讲解时选声报价，明确无配音、无真人、无配乐、全静音分别处理。只补必要素材，不要求所有类别，也不让用户选择技术路线。usage 无权时剩余额度标为未知，不影响其它已授权免费请求。

TTS 2.0（tts.speak / volc-tts-2.0）和生图（images.generate / 当前 native-image）均走现有 quote → submit → task → receipt → download，完整请求例子在 templateApi.examples，实际字段及可用性查实时合同。报价和余额不是消费许可；已有明确授权覆盖能力列表、单次上限与剩余总额时继续，不重复确认。

任务已受理或提交结果不确定时先用原操作对账；报价过期也不能跳过这一步新建任务。只有确认未受理后，保留旧状态并另建报价文件。当前 helper 的生成报价仍依赖可读的 usage.models；缺失时说明限制，不手工 HTTP 绕过。

获取素材并绑定到模板

图片查询JSON：{"kind":"image","provider":"pexels","q":"本镜头的场景关键词","limit":"3"}。

node assistant/motion.mjs api /原始个人模板.motion search /本期实例/image-query.json
node assistant/motion.mjs api /原始个人模板.motion select src_返回的引用
node assistant/motion.mjs api /原始个人模板.motion download ast_选用结果的编号 /本期实例/inputs/assets/photo.jpg
node assistant/motion.mjs api /原始个人模板.motion music-prepare /本期实例/music-request.json /本期实例/music-v1
node assistant/motion.mjs api /原始个人模板.motion voices zh

现成视频使用 kind=video；配乐请求中填写本期文案、风格和目标时长。配音先选声，再 quote → submit → task → receipt → download，提交只使用用户已经授权的积分预算。同一次生成断线后保留并重用状态文件，不重新创建收费操作。

图片查找与付费生图是两条不同流程；免费素材失败时，不自动转付费生成。取得素材后，读取模板实际公开 guide/schema，把返回文件绑定到对应槽，按实际音频时长核对计划、预览及导出结果。接口成功不等于模板视频已经完成。

HTTP 客户端参考

普通脚本可使用用户自行配置的 MotionGit Key，私有请求带 Authorization: Bearer <平台Key>；供应商密钥仅由服务器保管。个人包制作优先使用上述随包入口，模板子进程和成片工程不接收凭据。

方法	路径	用途	积分
GET	`/api/v1/capabilities`	公开能力、状态、参数与价格	0
GET	`/api/v1/usage`	本人权限、免费每日请求、付费积分及当前模板引导	0
GET	`/api/v1/search?kind=image&provider=pexels&q=coffee`	查找已有图片；视频用kind=video	0
POST	`/api/v1/assets/select`	选用搜索结果	0
GET	`/api/v1/assets/{id}/download`	下载本人素材或取得外链合同	0
GET	`/api/v1/stickers/search`	检索贴纸	0
POST	`/api/v1/stickers/match`	文案/关键词匹配贴纸	0
GET	`/api/v1/stickers/{preset}`	下载贴纸JSON	0
GET	`/api/v1/music/categories`	音乐分类与实时数量	0
POST	`/api/v1/music/recommend`	按文案推荐音乐	0
GET	`/api/v1/tts/voices`	查询当前TTS音色目录	0
POST	`/api/v1/quotes`	取得付费生成报价，不生成	0
POST	`/api/v1/generations`	按已确认报价提交	以报价为准
GET	`/api/v1/tasks/{id}`	查询任务	0
GET	`/api/v1/tasks/{id}/receipt`	查询扣点、释放及实际规格	0

只使用在线目录中已开放且原 Key 已授权的能力；关闭服务不提交任务、不自动换供应商。旧同步生图和历史模板声明仍作兼容入口，按完整模板素材合同和实时目录判断，不根据历史示例推测状态。

完整模板素材调用说明 · 背景音乐 · 能力与用法 · API设置 · OpenAPI

贴纸与本期文案匹配

按镜头或一句话提交 POST /api/v1/stickers/match，例如 {"text":"展示生日蛋糕，不要下雨","keywords":["生日蛋糕"],"limit":5}。需要原Key具有 stickers.search、模型 local-stickers；下载还需要 stickers.file。

返回 algorithm=metadata-keywords-v2、提取词 extracted_keywords、简单排除词 excluded_keywords 及候选 results。reasons解释匹配依据，score仅用于排序；显式keywords优先，可覆盖文案排除。不要把整段多镜头文案的一号候选套给所有镜头。has_text=false只表示元数据未识别文字，不保证没有描边或烘焙字样。核对标题、has_text及实际动画，避免自带文字与口播冲突；复杂否定、反讽仍需调用者确认。

确认缺少图像依赖的贴纸从搜索/匹配中排除，直接下载返回503 sticker_dependencies_missing，不扣积分或素材次数。已付费生成的素材、本人上传文件的下载不占免费素材库30次额度。免费库素材的查找、匹配、选用、下载按请求分别计数。

.motion调用只使用经校验随包入口当前支持的动作；旧工具缺少贴纸match/file命令时，报告工具能力缺口并按正式更新指引升级，不能提取包内Key或把缺命令说成平台无接口。HTTP客户端已有独立用户Key时可调用上面的接口。