MotionGit API

模板负责动作与节奏，API 负责“按你的内容补齐素材”。当视频需要根据文案配图、加一个贴纸动画时，模板（或你的 AI 助手）调用 MotionGit 官方 API，结果直接放进本期工程。

鉴权

所有请求都带上你的 Key：

curl https://motiongit.com/api/v1/me -H "Authorization: Bearer mgk_你的密钥"

Key 有两种：

类型	从哪里来	用途
模板专用 Key	下载模板时自动写入包内 `motiongit.key.json`	这个模板制作时调用 API；可在后台单独停用
通用 Key	在 API 与额度手动创建	你自己的脚本、Claude Code、其他工具

请妥善保管。 下载的 .motion 文件里有只属于你的 Key，调用会扣你的额度。不要把下载的包转发给别人——想推荐模板，请分享 MotionGit 上的模板链接，这也是对创作者的尊重。发现 Key 泄露，在后台停用或撤销即可，重新下载会签发新 Key。

额度

取消每月免费、注册、邮箱验证和分享访问赠送。可用积分来自充值购买与已解锁的消费奖励。
充值或购买模板，消费本人及符合条件的邀请人各获实付金额对应积分的 5%（1 元对应 10 积分，向下取整）。支付后可见“待解锁”，满 14 天且无退款、无异常、邮箱已验证，渠道核验成功后到账；退款扣回奖励。
每把 Key 可以设置月上限，超过后这把 Key 的调用会被拒绝。
每个响应都带 X-MotionGit-Credits-Remaining 头。额度不足时返回 402。

接口

方法	路径	说明	消耗
GET	`/api/v1/me`	当前 Key 与额度	免费
GET	`/api/v1/capabilities`	全部能力与状态（无需 Key）	免费
GET	`/api/v1/stickers/search?q=增长&limit=12`	按文案检索贴纸动画（Lottie，1.1 万+）	免费
POST	`/api/v1/stickers/match`	提交整段文案或关键词，自动匹配贴纸并返回理由	免费
GET	`/api/v1/stickers/{preset}`	下载一个 Lottie JSON	1 点
POST	`/api/v1/images`	按文案生成配图（内测）	10 点
GET	`/api/v1/usage`	有效额度：账户余额、当前 Key 月上限、各能力可用次数	免费
POST	`/api/v1/productions`	制作登记（可不带 Key）：返回模板更新、已知问题、作者提示	免费

检索贴纸

curl "https://motiongit.com/api/v1/stickers/search?q=增长%20数据&limit=5" \
  -H "Authorization: Bearer $MOTIONGIT_KEY"

返回每个候选的 preset、中文标题、关键词、时长、画幅、主色和下载地址。先检索、挑选，只下载用得上的。

文案 / 关键词自动匹配贴纸

curl -X POST https://motiongit.com/api/v1/stickers/match \
  -H "Authorization: Bearer $MOTIONGIT_KEY" -H "Content-Type: application/json" \
  -d '{"text":"今天是我的生日，大家一起庆祝，点个赞吧！","keywords":["生日","点赞"],"limit":5}'

可以只提交 text 或 keywords，也可组合提交。text 最多2000字，keywords 最多20项、每项最多64字，limit 默认12、范围1–50；请求正文最大16KiB，拒绝额外字段。

返回 extracted_keywords、可用匹配数 total 与候选 results。每项提供 preset、标题、排序分值、命中词/字段/直接或同义词来源的 reasons、尺寸/时长以及已有鉴权下载接口 file。显式关键词优先，整段文案按场景词匹配；分值用于排序，不是语义概率。没有匹配返回空列表，检索免费，下载仍单独计费。文案与关键词不写入计费记录。

生成配图（内测）

curl -X POST https://motiongit.com/api/v1/images \
  -H "Authorization: Bearer $MOTIONGIT_KEY" -H "Content-Type: application/json" \
  -d '{"prompt": "清晨的城市天际线，柔和的蓝色调，留出左侧标题空间", "size": "1536x1024"}'

内测期间如果返回 503 not_enabled，表示生图尚未对外开放，不会扣点。上游失败同样不扣点。成功保存图片后才扣点。GET /api/v1/capabilities 的 enabled 表示当前部署是否启用能力；status: beta 表示仍在测试阶段。请求体上限 16KiB，prompt 最多 2000 字，size 必须使用上述三种尺寸；同一账户重复请求返回 409，服务忙时返回 429，超时返回 504。

成功响应的 size、width、height 来自实际图片，requested_size 保留请求尺寸。代理可能返回其它尺寸，这时响应附带 notices，不重复生成、不裁切图片；请按实际尺寸排版。

查看有效额度

curl https://motiongit.com/api/v1/usage -H "Authorization: Bearer $MOTIONGIT_KEY"

effective_credits_remaining 取账户余额和这把 Key 当月上限中较小的一个；capabilities[].possible_count 是按这个数算出的可用次数（planned 的能力为 null）。

制作登记

模板制作时，助手在出方案前（stage: "plan"）和成片后（stage: "done"）各调用一次。只接受以下 7 个字段，多一个字段都会返回 400：

curl -X POST https://motiongit.com/api/v1/productions -H "Content-Type: application/json" \
  -d '{"template":"continuous-performance@1.0.0","package_sha256":"<integrity.json 的 SHA256>","host":"codex-cli","layout":"landscape","duration_s":34,"materials":["video.presenter","text.subtitles"],"stage":"plan"}'

返回 production_id、latest_version、notices（新版本、已知问题）和 tips（模板作者的最新制作提示）。不带 Key 也能调用，只是不关联账号；带了 Key 就必须有效。不发送任何文件、文字、路径或用户名。离线或用户拒绝时直接跳过，不影响制作。

在模板里声明用到的能力

在 motion.json 里声明模板会调用哪些能力，模板页会展示给使用者：

"motiongit": {
  "capabilities": ["images.generate", "stickers.file"]
}

模板代码读取 Key 的顺序：环境变量 MOTIONGIT_API_KEY → 包根目录 motiongit.key.json 的 key 字段。没有 Key 或额度不足时，模板应退回到默认素材，而不是中断渲染。

规划中

能力	说明
按文案生视频	为空镜头、背景生成短视频片段
配乐匹配	按情绪与时长匹配可商用音乐
配音合成	把文案合成为配音，自动对齐字幕
字幕对齐	把口播与字幕逐字对齐
字体匹配	按风格找到可商用字体，并给出获取方式
云端渲染	没有本地环境时，在云端导出成片

错误码

HTTP	code	含义
401	`invalid_key`	缺少或无效的 Key
402	`insufficient_credits`	额度不足
403	`key_disabled`	Key 已被所有者停用
429	`rate_limited`	每把 Key 每分钟最多 120 次
503	`not_enabled`	能力尚未开放，不扣点

创作者 API：持久生成任务

能力与状态 · 报价/任务/素材指南 · Playground · 异步 Node 示例。新增服务在配置、授权、费率和真实验收完成前关闭。旧同步生图入口使用同一持久任务与收据底座。

背景音乐

背景音乐 API 调用说明：按用途、情绪、风格、时长返回多首候选，支持认证试听、完整下载和私人素材选用；用户 Key 需有 music.search，完整下载另需 assets.read，选用另需 assets.write。当前均为0点，实际开放状态见能力目录。