# MotionGit API

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

## 鉴权

所有请求都带上你的 Key：

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

Key 有两种：

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

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

## 额度

- 每月免费 200 点，北京时间每月 1 日重置。
- 邀请好友注册并验证邮箱，双方各得 100 点；奖励点数长期有效。
- 每把 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 万+） | 免费 |
| GET | `/api/v1/stickers/{preset}` | 下载一个 Lottie JSON | 1 点 |
| POST | `/api/v1/images` | 按文案生成配图（内测） | 10 点 |

### 检索贴纸

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

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

### 生成配图（内测）

```bash
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`，表示生图尚未对外开放，**不会扣点**。上游失败同样不扣点。

## 在模板里声明用到的能力

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

```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` | 能力尚未开放，不扣点 |