# MotionGit .motion 模板素材 API 调用说明

更新时间：2026-10-19。正式站入口 `https://motiongit.com`。先读取在线能力目录与本人权限，只有 `status=ready` 且 `available=true` 的模型才可使用。服务开放状态不等于一次调用已经真实成功。

## 在 .motion 模板制作中使用

这些接口用于为 `.motion` 模板准备本期图片、视频、贴纸、配乐和配音。读取包内 `00-START-HERE.md`、`assistant/guide.json`，校验工具后从原包调用，素材下载到独立制作实例，按模板公开 guide/schema 绑定，再检查预览和成片。适用于具备文件、命令、网络与渲染能力的助手；没有特定助手依赖。

```sh
node assistant/motion.mjs start /原始个人模板.motion
node assistant/motion.mjs api /原始个人模板.motion usage
```

`usage` 的 `template_api_guide` 和新包 `assistant/guide.json` 的 `templateApi` 返回相同制作指引；因此旧包也能从在线用量结果获得当前引导。读取说明本身不要求启动在线服务，只有制作需要素材时再检查接口。

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

```sh
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
```

查找、选用、下载是分别计数的请求。下载后使用模板实际声明的图片槽；视频使用 kind=video 及视频槽。配乐使用 `music-prepare`，配音使用 `voices → quote → submit → task → receipt → download`。素材接口成功不等于模板成片已完成。权限不足时说明原 Key 缺少的权限，不手拆包内凭据、不自动扩权、不将免费搜索改成付费生图。

## 免费请求与付费积分

免费素材接口不扣积分，仅设每日请求上限和短时限流，用于控制负载、防止滥用。只有需要向第三方支付费用的接口才扣积分。每日请求额度与积分余额独立计算；免费接口不会因积分不足而停用，调用仍需有效 Key 和对应权限。

- 免费：现有图片/视频查找与选用、贴纸搜索/匹配/下载、音乐库检索/推荐/试听/选用/下载。查询能力、报价、余额、用量与任务进度也不扣积分。
- 第三方付费：AI 生图、TTS 配音及已开放的生成类服务。先查看报价，再按用户预算确认提交。
- 免费素材请求按账户共用每日次数，不因换 Key 而增加。默认每天 30 次，服务端可通过 `CREATOR_FREE_MATERIAL_DAILY_REQUESTS` 调整，Asia/Shanghai 00:00 重置；短时网关和供应商限流同时生效。
- `GET /api/v1/usage` 的 `free_material_requests` 返回 `daily_limit`、`used_today`、`remaining_today`、`resets_at`、`timezone`，单位为请求次数；与 `credits.remaining` 分别读取。免费素材的搜索、匹配、推荐、目录、选用、音乐元数据/试听/下载及素材文件下载计入请求次数；查询用量不占用这份额度。
- 达到每日上限：HTTP 429 / `daily_request_limit_exceeded`，按 `Retry-After` 和重置时间等待，不提示充值。HTTP 403 / `scope_denied` 表示 Key 未授权，不表示接口不存在，也不表示积分不足。

## 用户 Key 与权限

私有请求一律使用 `Authorization: Bearer <用户 MotionGit 平台 Key>`。Key 从 [网站 API 设置](https://motiongit.com/settings/api) 创建；供应商密钥由服务器持有，助手不用索取或传入。Key 不放 URL、聊天、日志或 Git。新版个人 `.motion` 包已绑定下载者本人账户的原 Key。助手校验随包工具后，直接使用 `node assistant/motion.mjs api <原始.motion> <操作>` 调用；不手动展开 `personal/`，不打印或转存包内凭据。普通 HTTP 客户端使用用户自己的平台 Key。

每种生成权限还需 `usage.read` 查询任务、`assets.read` 下载；语音识别需 `assets.read`，上传需 `assets.write`。模型白名单必须含目标模型。现有 TTS Key 和音乐检索 Key 不自动扩权，生成其他素材应创建独立受限 Key。

## 先获取状态与剩余额度

`GET /api/v1/capabilities` 是公开目录，返回 `models[].id, capability, status, reason, limits, price_options`。

`GET /api/v1/usage` 需要 `usage.read`，主要字段：

| 字段 | 含义 |
|---|---|
| `free_material_requests` | 免费素材的每日请求额度，独立于积分；含当日剩余次数和重置时间 |
| `credits.remaining` | 账户可用平台点数，已扣除预占 |
| `credits.held` | 正在处理任务预占的点数 |
| `key_limits.daily_remaining/monthly_remaining` | 当前 Key 的日/月可用额度，null 或缺失表示未设置该上限 |
| `account_limits` | 账户级别日/月与单次上限 |
| `effective_credits_remaining` | 账户余额、Key 日/月、账户日/月共同限制后的平台额度 |
| `max_request_credits` | 在上述额度基础上再计入单次上限 |
| `models[].key_permitted` | 当前 Key 是否有该能力及模型权限 |
| `models[].available` | 服务已开放且当前 Key 允许调用；不保证供应商实时可用 |
| `models[].platform_provider_daily_credits_remaining` | 网站对该供应商设置的共享日预算，单位为平台点数 |
| `models[].capacities[].remaining_units` | 按当前单价能使用的剩余计费单位；各模型共享同一余额，不能相加 |
| `models[].capacities[].max_units_per_request` | 单次最多可报价的计费单位；实际还受 `limits` 的长度/时长上限限制 |
| `models[].unit` | `image` 张、`video` 段、`second` 秒、`minute` 分钟、`100_codepoints` 每100字计费块 |
| `models[].provider_quota.known` | 当前为 false；网站不推测供应商账户剩余次数、时长或余额 |
| `concurrency` | 当前账户运行任务数与同时任务上限4 |

免费模型的 `remaining_units=null, free=true` 表示不按点计费，不代表无限请求；仍受频率、授权与服务状态限制。`minimum_units` 应结合 `limits` 判断是否足够制作一次素材。TTS 按 Unicode 码点每100字向上取整；ASR 按上传音频实际时长每分钟向上取整。点数是网站额度，不能当人民币或供应商余额。

## 模型与输入

下表描述调用合同，是否已开放必须读在线目录。

| 能力 / model | input 示例 | 输出 |
|---|---|---|
| `tts.speak` / `volc-tts-2.0` | `{"text":"口播文字","voice":"从 /api/v1/tts/voices 查询的ID","sample_rate":48000}` | 高品质配音WAV，实际毫秒时长 |
| `tts.speak` / `volc-tts`（旧版兼容） | `{"text":"口播文字","voice":"zh_female_shuangkuaisisi_moon_bigtts","sample_rate":24000}` | 24kHz 单声道 PCM WAV，实际毫秒时长 |
| `images.generate` / `native-image` | `{"prompt":"图片描述","size":"1024x1024","count":1}` | 图片资产；支持尺寸以目录为准 |
| `music.generate` / `fal-music` | `{"prompt":"适合科技讲解的安静钢琴配乐","duration":8}` | 原创 WAV；8–120整数秒，实际时长以输出为准 |
| `sfx.generate` / `fal-sfx` | `{"prompt":"轻盈转场呼啸声","duration":3,"loop":false}` | MP3；1–22整数秒 |
| `asr.transcribe` / `fal-asr` | `{"asset_id":"ast_本人音频ID"}` | `transcription.text, language_code, words`；字词时间单位秒 |
| `videos.generate` / `fal-wan` | `{"prompt":"镜头描述","resolution":"480p","ratio":"16:9"}` | MP4 固定短片；实际时长、画幅、帧率在资产规格中 |

音乐生成使用纯音乐提示词，但供应商未保证永远无声乐，最终应试听。Wan 只开放480p，不接收 `duration` 或 `generate_audio`；不能承诺精确目标时长或音轨。


ASR 只接受本人已校验且未过期的 `audio/wav` 或 `audio/mpeg` 音频资产，最长120秒；不接受其他用户资产或任意外部 URL。调用时不用伪造 `duration`，服务器读取文件规格。结果文字与字词时间轴保留7天，需及时保存；`words.type` 可能为 word、spacing 或 audio_event，时间为空时不要强行作为字幕词。

## 统一报价、提交、取结果

1. `POST /api/v1/quotes`：正文 `{"capability":"music.generate","model":"fal-music","input":{"prompt":"安静钢琴背景","duration":8}}`。只报价，不生成、不扣点。核对返回 `estimated_credits, max_credits, price_version, input, expires_at`。
2. **提交前将操作 UUID、完整报价和正文写入当前工程的持久状态文件**。`POST /api/v1/generations`，带 `Idempotency-Key: <本次操作UUID>`，正文原样使用报价返回的 `quote_id, capability, model, input, max_credits`。`max_credits` 是平台点数；不能填人民币。返回202、`task_id, status_url`。
3. `GET /api/v1/tasks/{task_id}` 每2–5秒查询。`queued/dispatching/running` 等待；`reconciling` 保留原操作与任务，等待核对，不能新建收费请求试错。`failed/cancelled` 查看错误与收据，不自动换模型重试。
4. `succeeded` 或 `partially_succeeded` 检查 `result_assets`，逐个 `GET /api/v1/assets/{id}/download` 带同一用户 Key。支持 Range；重复下载不会重新生成。ASR 从任务的 `transcription` 取文字与时间轴，不存在音频输出资产。
5. `GET /api/v1/tasks/{id}/receipt` 核对预占、扣点、释放及版本。下载后的实际文件规格优先于希望生成的规格。
6. 明确不再需要的私有素材可 `DELETE /api/v1/assets/{id}`。删除不能撤销已完成生成费用。

提交连接断开时重发**同一 UUID、同一正文**；收到 task_id 后只查询该任务。不要因响应超时、报价过期、结果暂时为空而换 UUID。已提交任务的重放会先返回原任务。需要制作新的内容、换声或换模型时才创建新的操作，并重新核对预算。

## 免费音乐及图片、视频素材

授权背景音乐以 `/api/v1/music/categories` 返回的实时数量为准，目前验收目录186首，按类型筛选：

- `GET /api/v1/music/categories`：可选类型、情绪、风格与数量。
- `GET /api/v1/search?provider=licensed&kind=music&type=technology&mood=calm&limit=6`：参数值以分类接口返回为准；也支持 q、genre、energy、voiceover、instrument、min_duration、max_duration、exclude、page。
- 音乐详情及试听地址从搜索响应读取；选用 `POST /api/v1/assets/select`，正文 `{"source_ref":"搜索原样返回值","purpose":"local_creation"}`，再下载本人资产。
- 图片/视频检索 `provider=pexels|pixabay|unsplash, kind=image|video`；Unsplash仅图片，下载返回 hotlink JSON，按 `external_url` 使用，不能把它当图片二进制。

检索需对应 `music.search/images.search/videos.search`，选用需 `assets.write`，下载需 `assets.read`。

### TTS 2.0 全部音色

TTS 2.0模型 `volc-tts-2.0`，正式音色目录 `GET /api/v1/tts/voices`（公开、0点）。支持q/gender/category/language/page/limit筛选与分页；默认50条、最大100条。`items[].id`用于报价input.voice，名称、性别、场景、语种及单音色真实验收标志一并返回。2026-10-10接入445个官方公共音色及1个已验收兼容ID。不能将模型ready解读为全部音色已逐一实测。新增可选input.explicit_language与input.enable_auto_language_recognition，旧调用保持兼容。详细说明见[高品质配音2.0](https://motiongit.com/developers/media)。个人 `.motion` 制作使用已验签包内的原账号 Key，通过随包入口调用，不需要本机测试配置。作者上传源包不含凭据；官网下载的个人包由平台绑定下载者原 Key。