# MotionGit 素材 API：各助手统一调用合同

更新时间：2026-10-09。Seedream 已移除；当前 Fal 因余额耗尽关闭，Seedance专用凭据已创建并配置，鉴权检查通过；核价和真实生成验收尚未完成。新接口合同已实现，但这些模型尚不可调用；后台明确显示原因。正式站入口 `https://motiongit.com`。先读取在线能力目录与本人额度，只有 `status=ready` 且 `available=true` 的模型才可使用。代码实现不等同供应商真实验收；最新验收结果见 [本次报告](https://github.com/adunext/motiongit/blob/codex/bgm-library/docs/reviews/creator-api/completion-2026-10-09/README.md)。

## 用户 Key 与权限

私有请求一律使用 `Authorization: Bearer <用户 MotionGit 平台 Key>`。Key 从 [网站 API 设置](https://motiongit.com/settings/api) 创建；供应商密钥由服务器持有，助手不用索取或传入。Key 不放 URL、聊天、日志或 Git。`.motion` 工程只保存模型与参数合同，不包含任何密钥；运行时从用户私有配置读取。

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

- 本机已存在 TTS 配置 `/Users/michael/.config/motiongit/tts.env`，客户端 `/Users/michael/.local/share/motiongit/tts.mjs`；仅能调用 `volc-tts`。
- 本机已存在音乐配置 `/Users/michael/.config/motiongit/music.env`；用于授权音乐库检索与选用。
- 使用这些文件时直接读取，禁止打印文件内容。不存在统一生成 Key 时，应在网站创建，不能假设 TTS Key 可生成视频。

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

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

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

| 字段 | 含义 |
|---|---|
| `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` | `{"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`；不能承诺精确目标时长或音轨。Seedance 与 Wan 是不同模型，不能把替代模型的结果标记成 Seedance。

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。已提交任务的重放会先返回原任务。需要制作新的内容、换声或换模型时才创建新的操作，并重新核对预算。

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

授权背景音乐99首，按类型筛选：

- `GET /api/v1/music/categories`：可选类型、情绪、风格与数量。
- `GET /api/v1/search?provider=licensed&kind=music&type=technology&mood=calm&limit=6`：参数值以分类接口返回为准；也支持 q、genre、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)。本机2.0专用配置为 `/Users/michael/.config/motiongit/tts-premium.env`，旧tts.env仅1.0；Key不打包进.motion。