魔媒师AI
开始创作

魔媒师AI OPEN PLATFORM

魔媒师AI 开放 API

交流、图片、视频、数字人、音频、短剧和 Seedance 人物素材，统一使用平台模型、余额、文件与异步任务体系。

下载 SKILL.md放入 AI 编程工具 · 自动获取全部接口能力 立即下载
Beta 开放本文列出的生成、上传、人物素材、余额、价格和任务查询接口均已接入统一网关。公网地址：https://mmsai.cn/v1

注册、登录与创建密钥

  1. 前往官网注册账号并完成邮箱验证。
  2. 可在API 密钥创建密钥。
  3. 先用 GET /v1/models 获取当前账户真实可用的模型 ID，再调用交流、图片或视频接口。
安全要求禁止把密钥写入网页、客户端安装包、Git 仓库或日志。泄露后应立即重置。

浏览器本机授权（Browser Auth）

任意终端 / 桌面应用只要按本文参数打开入口，均可完成登录授权；密钥经本机 HTTP 回调回传，无需用户手工复制。安全边界是 loopback 回跳与登录态，不依赖固定客户端名单。

GET/connect/browser-auth

固定入口：

http
https://mmsai.cn/connect/browser-auth?client=my-cli&response_type=api_key&redirect_uri=http%3A%2F%2F127.0.0.1%3A54321%2Fcallback&state=RANDOM
字段类型/状态必填说明
clientstring是终端自定 ID，2～64 位字母数字，可含 . _ -（如 my-cli、uopenclaw）
response_typestring是固定 api_key
redirect_uriurl是本机回调，仅 127.0.0.1/localhost + /callback
statestring是随机串，防 CSRF；回跳须原样带回

终端适配步骤

  1. 本机监听 http://127.0.0.1:<随机端口>/callback（仅 loopback）。
  2. 自定稳定的 client（如 my-cli、uopenclaw），生成随机 state，用系统浏览器打开入口 URL。
  3. 用户在官网登录并点击「同意并回传密钥」。
  4. 浏览器跳回本机：成功带 api_key + state；拒绝带 error=access_denied。
  5. 校验 state 后写入本地密钥（如 MMS_API_KEY），再请求 GET /v1/models 验证。

官网同意后会先在品牌结果页展示「授权成功」，并静默向本机 /callback 投递密钥（密钥不进入官网地址栏）。若终端未收到，结果页提供「手动完成回传」整页跳转兜底。

成功回跳示例（本机监听收到的请求）：

http
http://127.0.0.1:54321/callback?api_key=mms_sk_xxxx&state=RANDOM

拒绝回跳示例：

http
http://127.0.0.1:54321/callback?error=access_denied&state=RANDOM
安全约束redirect_uri 仅允许 http://127.0.0.1:<port>/callback 与 http://localhost:<port>/callback；须登录；须校验 state；每个 client 对应控制台密钥名 BA:<client>，再次授权会轮换使旧 Key 失效；密钥勿写入网页或安装包。

兼容说明：旧路径 /connect/uopenclaw 会自动跳转到 /connect/browser-auth 并保留 query。

快速开始

统一基础地址：

http
https://mmsai.cn/v1

交流接口可同步或流式返回；图片、视频、数字人、短剧和音频采用异步任务协议，提交成功后通过任务 ID 查询。

请求方式与公共格式

POSThttps://mmsai.cn/v1/{resource}
字段类型/状态必填说明
AuthorizationBearer string是API Secret Key
Content-Typeapplication/jsonJSON 接口JSON 请求格式；文件上传使用 multipart/form-data
X-Client-Request-Idstring否调用方链路 ID；排障时同时保存响应 x-request-id

请求体统一使用 UTF-8 JSON。上传文件时使用 multipart/form-data。每个响应都携带 x-request-id，报障时请提供该值。

bash
curl https://mmsai.cn/v1/chat/completions -H "Authorization: Bearer $MMS_API_KEY" -H "Content-Type: application/json" -d '{"model":"mms-chat-gpt-5-6-terra","messages":[{"role":"user","content":"你好"}]}'

身份认证

所有请求都应在服务端发起。不要把 API Key 暴露在浏览器、桌面包或移动端代码中。

bash
curl https://mmsai.cn/v1/models \
  -H "Authorization: Bearer $MMS_API_KEY"

模型列表

GET/v1/models

返回账户可用的平台模型，支持使用 type、capability 和 status 查询。稳定的 id 由 MMS 分配，不暴露内部路由、执行模型和成本价格。

json
{"object":"list","data":[{"id":"mms-image-creative-hd","object":"model","name":"GPT Image 2 High","type":"image","description":"高质量商业图片生成模型","advantages":["中文理解","文字排版","风格稳定"],"scenarios":["商品海报","社交配图"],"status":"available","capabilities":["text_to_image","image_to_image"]}]}

模型详情

GET/v1/models/{model_id}

返回模型介绍、Logo、描述、优势、适用场景、能力、参数约束和当前可用状态。调用前应读取 capabilities 与 limits，不要硬编码不同模型的私有参数。

json
{"id":"mms-video-creative","object":"model","name":"Seedance 1.5 Pro","type":"video","description":"适合商业短片与运镜生成","advantages":["运动稳定","镜头语言丰富"],"scenarios":["广告短片","产品展示"],"status":"available","capabilities":["text_to_video","image_to_video"]}

模型价格

已开放 Beta
GET/v1/pricing/models

只返回当前账户实际适用的平台出售价格。价格可能按 Token、次、张、秒或分钟计费；提交媒体任务前可使用返回规则进行预估，最终以用量账单为准。

字段类型/状态必填说明
modelstring是平台逻辑模型 ID
price.configuredboolean是是否已配置客户价
price.rulesarray已配置按 meterCode、selectors、unitSize、roundingMode、minimumUnits、unitPrice 计算
price.currencystring已配置当前为 POINTS（积分）
json
{"object":"list","currency":"POINTS","data":[{"model":"mms-image-creative-hd","name":"MMS 创意绘图高清","type":"image","price":{"configured":true,"currency":"POINTS","rules":[{"meterCode":"imageCount","unitSize":1,"roundingMode":"ceil","minimumUnits":1,"unitPrice":0.18,"combineMode":"sum"}]}}]}

余额查询

已开放 Beta
GET/v1/balance

返回账户可消费余额、冻结中的预授权金额和套餐额度。金额字段均为字符串，避免浮点精度问题。

json
{"object":"balance","currency":"POINTS","available_balance":"128.500000","quotas":{"text":120000,"image":35,"video":120,"short_drama":8},"plan":{"name":"专业版","expires_at":"2026-08-13"}}

交流 / Chat Completions

POST/v1/chat/completions

使用 MMS 标准交流协议，支持非流式响应与 SSE 流式输出。

javascript
const response = await fetch("https://mmsai.cn/v1/chat/completions", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.MMS_API_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    model: "mms-chat-gpt-5-6-terra",
    messages: [{ role: "user", content: "写一个产品短片脚本" }]
  })
});

const result = await response.json();

素材上传

已开放 Beta
POST/v1/files

API Key 具有 images:write、videos:write 或 chat:write 任一生成权限即可上传。默认每账户每天 1 GiB、累计开放 API 上传 10 GiB，实际额度以平台配置为准。

字段类型/状态必填说明
filebinary是图片、音频或视频文件
purposestring是固定为 generation
bash
curl https://mmsai.cn/v1/files -H "Authorization: Bearer $MMS_API_KEY" -F "purpose=generation" -F "file=@./reference.png"

返回的 file_id 可用于生图、生视频、数字人、短剧和音频接口。禁止把本地文件路径直接写入 JSON。

图片生成

POST/v1/images/generations
字段类型/状态必填说明
modelstring是平台模型 ID
promptstring是图片描述词
sizestring否输出尺寸
ninteger否生成数量
json
{"model":"mms-image-creative-hd","prompt":"极简科技产品海报","size":"1:1","resolution":"2k","quality":"high","n":1}

视频生成

POST/v1/videos/generations
MMS Extension

视频生成采用异步任务。响应返回平台任务 ID，不直接暴露外部任务 ID。

json
{"model":"mms-video-creative","prompt":"电影感产品展示","duration":8,"aspect_ratio":"16:9","resolution":"720p","image_with_roles":[{"url":"https://example.com/ref.jpg","role":"first_frame"}]}

Seedance 人物素材与人物查询

已开放 Beta人物素材组、附件上传和状态查询均使用开放平台 API Key；返回的是 MMS 平台映射 ID，不会暴露外部服务标识。

Seedance 2 系列支持把人物图片、人物视频或音频提交为可复用素材。标准流程为：创建人物素材组、上传附件、轮询人物素材状态，待 status=active 后，在视频请求中使用 asset://<asset_id>。

第一步：创建人物素材组

POST/v1/videos/seedance-2/character-assets/groups
字段类型/状态必填说明
modelstring是从 /v1/models 取得、支持 Seedance 人物素材的视频模型 ID
namestring是人物或素材组名称
descriptionstring否人物设定与素材用途说明
json
{"model":"mms-drama-flagship-25","name":"brand-avatar-linxia","description":"品牌虚拟人物林夏，统一服装和面部特征"}

第二步：上传人物附件

POST/v1/videos/seedance-2/character-assets
字段类型/状态必填说明
group_idstring是创建人物素材组返回的 ID
asset_typeenum是image、video 或 audio
source_urlHTTPS URL是稳定、可公开拉取的附件地址
namestring否素材名称
json
{"group_id":"group_xxx","asset_type":"image","source_url":"https://cdn.example.com/linxia-front.png","name":"林夏正面定妆图"}

每次提交一个附件，支持 image、video、audio。建议把上传接口返回的 file_* 直接填入 source_url；也可传平台能够读取的稳定公网 HTTPS 地址，不能传本机路径。

第三步：人物素材查询

GET/v1/videos/seedance-2/character-assets/{asset_id}

建议每 5～10 秒查询一次。processing 表示处理中，active 表示可用于生成，failed 表示处理失败。

json
{"asset_id":"asset_xxx","group_id":"group_xxx","asset_type":"image","status":"active","asset_uri":"asset://asset_xxx","created_at":1788537600}

第四步：在 Seedance 视频中引用人物

json
{"model":"mms-drama-flagship-25","prompt":"林夏站在雨夜街口缓慢回头，镜头推进，电影感","duration":12,"aspect_ratio":"9:16","resolution":"720p","image_with_roles":[{"url":"asset://asset_xxx","role":"reference_image"}],"generate_audio":true}
临时地址任务结果中的媒体 URL 可能带有效期；返回 expires_at 时以该字段为准，未返回时也应在取得作品后立即下载保存。asset://<asset_id> 是人物素材引用，其可用性以人物查询接口的 status 为准。

数字人 / 口播生成

已开放 Beta
POST/v1/avatars/generations
MMS Extension
字段类型/状态必填说明
modelstring是数字人口播模型 ID
avatar_file_idstring是上传接口返回的人物视频 file_*
audio_file_idstring是上传接口返回的驱动音频 file_*
aspect_ratiostring否如 9:16、16:9
json
{"model":"mms-oral-lip-sync","avatar_file_id":"file_<上传人物视频后返回的ID>","audio_file_id":"file_<上传驱动音频后返回的ID>"}

短剧生成

已开放 Beta
POST/v1/dramas/generations
MMS Extension

提交单个短剧视频镜头生成任务，必填 model 和 prompt；当前 Beta 通过任务接口轮询进度，不依赖 Webhook。

json
{"model":"mms-drama-flagship-25","prompt":"雨夜街口，林夏收到一封来自十年前的信，镜头由全景缓慢推进到面部近景","duration":12,"aspect_ratio":"9:16","resolution":"720p"}

音频生成

已开放 Beta
POST/v1/audio/speech
字段类型/状态必填说明
modelstring是语音模型 ID
inputstring是待合成文本
voicestring是平台音色 ID
response_formatstring否mp3、wav、pcm
json
{"model":"mms-oral-tts","input":"欢迎使用魔媒师AI 开放平台","voice":"<平台音色ID>","response_format":"mp3","speed":1.0}

任务查询

GET/v1/tasks/{task_id}
json
{"id":"task_01J...","object":"generation.task","type":"video_model_generate","status":"succeeded","progress":100,"output":{"platformUrls":["https://mmsai.cn/..."],"mediaKind":"video"}}

Webhook 回调

暂不开放

当前 Beta 版本请通过 GET /v1/tasks/{task_id} 轮询终态。当前请求不接受 callback_url 等回调参数，正式开放 Webhook 后将补充签名与重放保护协议。

响应格式与状态码

同步接口直接返回业务对象；异步提交返回任务对象。HTTP 状态码表示请求结果，不能只根据响应正文中的字段判断成功。

字段类型/状态必填说明
200成功同步/查询请求成功，读取响应业务字段
202已接收异步提交任务已创建，继续查询任务状态
400请求错误失败字段缺失、格式错误或参数不受支持
401认证失败失败Bearer 缺失、Key 错误、已禁用或已重置
402余额不足失败充值后重新提交
403权限不足失败API Key 缺少接口所需 scope
404资源不存在失败模型或当前账户下的平台资源不存在
429请求过多失败读取 Retry-After 并指数退避
500/503服务异常失败保留 request_id；先核对任务记录再决定是否重试

交流调用成功 · HTTP 200

模型回复位于 choices[0].message.content，Token 用量位于 usage。

json
{"id":"chatcmpl-01J...","object":"chat.completion","created":1788595200,"model":"mms-chat-gpt-5-6-terra","choices":[{"index":0,"message":{"role":"assistant","content":"这是模型生成的回复内容。"},"finish_reason":"stop"}],"usage":{"prompt_tokens":18,"completion_tokens":12,"total_tokens":30}}

模型列表成功 · HTTP 200

从 data 中选择当前账户可见、状态可用且类型为交流的模型 ID，再发起交流请求。

json
{"object":"list","data":[{"id":"mms-chat-gpt-5-6-terra","object":"model","name":"GPT-5.6 Terra","type":"inference","status":"available","capabilities":["chat"]}]}

异步任务已接收 · HTTP 202

queued 只表示任务创建成功，不代表作品已经生成；应使用返回的任务 ID 查询至终态。

json
{"id":"task_01J...","object":"generation.task","status":"queued","created":1783915200,"request_id":"req_01J..."}

异步任务生成成功 · HTTP 200

取得作品后应立即下载保存；返回 expires_at 时以该字段作为准确到期时间。

json
{"id":"task_01J...","object":"generation.task","status":"succeeded","progress":100,"output":[{"type":"video","url":"https://cdn.example.com/result.mp4","thumbnail_url":"https://cdn.example.com/thumb.jpg","expires_at":1788681600}],"usage":{"total_units":12}}

错误处理

字段类型/状态必填说明
invalid_request_error400参数检查 error.param 与 message
invalid_api_key401鉴权检查 Authorization: Bearer 与完整 Key
insufficient_quota402余额使用响应中的 recharge_url 充值
insufficient_scope403权限重新创建具备对应 scope 的 Key
model_not_found404模型重新调用 /v1/models 获取可用 ID
rate_limit_error429频率按 Retry-After 退避，不要立即循环重试
api_error500/503服务记录 request_id，稍后重试或联系支持
400 · 参数错误

检查 param 指向的字段；下面表示 messages 为空。

json
{"error":{"message":"messages 不能为空","type":"invalid_request_error","code":"invalid_request_error","param":"messages"},"request_id":"req_01J..."}
401 · API Key 无效

确认请求头包含 Bearer、复制的是完整 Key，并检查密钥是否已重置或禁用。

json
{"error":{"message":"Incorrect API key provided.","type":"authentication_error","code":"invalid_api_key"},"request_id":"req_01J..."}
402 · 余额不足

打开 recharge_url 充值，到账后重新提交。

json
{"error":{"message":"账户余额不足，请充值后重试。","type":"insufficient_quota","code":"insufficient_quota","recharge_url":"https://mmsai.cn/console?menu=balance&focus=recharge"},"request_id":"req_01J..."}
403 · 权限不足

当前 Key 缺少接口权限，需要创建或更换具备对应 scope 的 Key。

json
{"error":{"message":"当前 API 密钥缺少权限：chat:write","type":"permission_error","code":"insufficient_scope"},"request_id":"req_01J..."}
404 · 模型不存在

不要猜模型 ID；重新调用 GET /v1/models 并复制返回的 id。

json
{"error":{"message":"模型不可用或无权访问","type":"invalid_request_error","code":"model_not_found","param":"model"},"request_id":"req_01J..."}
429 · 请求过多

读取 Retry-After，等待后再重试，并使用指数退避。

json
{"error":{"message":"请求过于频繁，请稍后重试。","type":"rate_limit_error","code":"rate_limit_error"},"request_id":"req_01J..."}
500/503 · 服务暂时不可用

记录 request_id；同步交流可稍后重试，异步提交先核对控制台任务记录。

json
{"error":{"message":"服务暂时不可用","type":"api_error","code":"api_error"},"request_id":"req_01J..."}
资源不存在HTTP 404 表示模型或平台资源不存在，或资源不属于当前 API Key 所属账户。请重新获取模型列表，并核对平台返回的文件、任务、素材组和人物素材 ID。

速率限制与幂等

任务及人物素材查询每账户最多 120 次/分钟、每 IP 最多 600 次/分钟；更低的全局限额仍生效。人物素材请求上游的最短间隔为 10 秒，终态直接返回已保存状态。

公开请求只使用 model 指定模型，不接受 channelId、modelConfig、providerId、baseUrl、apiKey 等内部路由与凭据字段。

响应头返回 x-request-id。触发限流时返回 HTTP 429 与 Retry-After。当前 Beta 版本尚未承诺 Idempotency-Key 去重；提交请求超时且未取得任务 ID 时，重新提交前应先在控制台核对任务记录。

常见场景与故障排查

任务一直生成中

查询 updated_at；超时后携带 request_id 联系支持，客户端应采用退避轮询。

提交超时未拿到任务 ID

当前 Beta 不承诺幂等去重；先到控制台核对任务记录，避免直接重复提交。

素材无法读取

优先使用上传接口返回的 file_id；外链必须是公网 HTTPS。

模型参数不一致

读取 /v1/models 的 capabilities，不传内部路由字段。

余额不足

在控制台检查余额与套餐额度；预授权失败会释放或退款。

等待任务完成

Webhook 暂未开放，使用任务查询接口轮询 succeeded、failed 等终态。

陕ICP备2024045939号