Este documento técnico está disponible en inglés. La interfaz sigue el idioma que seleccionaste.

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

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

在 .motion 模板制作中使用

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

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"}。

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 设置创建；供应商密钥由服务器持有，助手不用索取或传入。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，时间为空时不要强行作为字幕词。

统一报价、提交、取结果

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