MXAPI

概述

通过一个命令行脚本调用 MXAPI 开放平台。脚本已经处理好认证、图片上传、任务轮询、结果下载和错误翻译，你只需要调用脚本，不要自己拼 HTTP 请求。

铁律

违反这几条会直接导致用户体验变差或密钥泄露，务必遵守：

1. 不要自己写 curl 或 requests 去调接口。 各能力的查询端点、参数名、结果字段

路径都不一样，手写几乎必错。一律通过 scripts/mxapi.py 调用。

1. 不要把密钥写进任何项目文件、代码或提交记录。 密钥只能存在环境变量

MXAPI_KEY 或用户主目录的 ~/.mxapi/config.json 里。用户在对话中直接贴出密钥时，用 login 命令存起来，然后提醒他这条消息里的密钥建议尽快轮换。

1. 提交任务后必须等到出结果再回话。 脚本默认会自动轮询到完成，不要中途打断，

也不要把 task_id 甩给用户让他自己查。

1. 结果必须落地到本地文件。 平台返回的链接普遍只有 1 小时有效期，脚本默认会

下载，不要加 --no-download，除非用户明确说只要链接。

1. 花钱之前先说清楚。 视频和音乐单次消耗积分较多，第一次为用户执行生成前，

先用一句话说明将要使用的模型；余额不足时不要反复重试。

每次任务开始前：检查并更新技能

每次用户发起一个新的 MXAPI 任务，先定位当前 SKILL.md 所在目录，在该目录执行：

python3 scripts/update_skill.py

Windows 使用 python -X utf8 scripts/update_skill.py。本步骤不需要 MXAPI 密钥或 SkillHub Token。脚本从腾讯 SkillHub 检查 @csd/mxapi，只在商店有更高的稳定版本时下载并更新当前技能目录。

• 返回 updated: true 时，重新读取同一目录的 SKILL.md，随后按新说明执行用户任务；本次不再重复检查。
• 返回 current 时直接继续。一个任务中的提交、轮询、下载复用本次检查，不在运行中的任务中途更新。
• 返回 unavailable、disabled 或 development 时继续使用本地版本，不循环重试，也不索要发布 Token。

用户明确关闭自动更新（MXAPI_AUTO_UPDATE=0）时遵从该设置；源码工作区不会被自动覆盖。

• 返回 repair_required 时暂停调用，说明技能文件恢复失败，需要通过宿主重新安装 @csd/mxapi。

只有具备网络和当前技能目录写入权限时才能自动更新。若宿主限制写入或仍缓存旧说明，说明需要用宿主的技能更新功能或重载技能，不能声称已更新成功。已有旧版需先升级到包含此检查入口的版本。

第一次使用：确认环境

第一次使用时先跑自检，它会一次性验证 Python、网络、密钥和余额：

python3 scripts/mxapi.py doctor

Windows 上必须改用包装脚本，否则 PowerShell 会用 GBK 解码输出，中文全变乱码、关键字也匹配不上：

.scriptsmxapi.ps1 doctor

CMD 环境用 python -X utf8 scriptsmxapi.py doctor。PowerShell 包装脚本会自动找到 Python 并切好编码，参数写法和 python3 scripts/mxapi.py 完全一致。下文所有示例在 Windows 上都把 python3 scripts/mxapi.py 换成 .scriptsmxapi.ps1 即可。

如果提示没有密钥，让用户去 <https://open.mxapi.org> 商户后台的「API密钥管理」创建一个，然后执行：

python3 scripts/mxapi.py login --key 用户给的密钥

密钥会存到 ~/.mxapi/config.json（权限 600）。用户复制时连 Bearer 一起带过来也没关系，脚本会自动剥掉。

选型：用户想做什么 → 用哪条命令

不确定用哪个模型时，直接用默认值（图片 nano2、视频 seedance2-fast、音乐 v6），这三个是效果和价格最平衡的选择。

models 列出专用命令支持的 13 个图片模型、6 个 Seedance 视频选项和 3 个 Suno 版本；其他接口通过 request 调用，完整范围见 references/全站接口.md。

常用命令

所有命令都在 scripts/mxapi.py 下。生成类命令会自动完成"提交 → 轮询 →下载"整个流程，成功后把本地文件路径打印出来。

# 画图，结果存到 mxapi-outputs/ 目录
python3 scripts/mxapi.py image --prompt "一只戴墨镜的柴犬，扁平插画风格"

# 带参考图改图，--ref 可以是本地路径，也可以是网址，本地文件会自动上传
python3 scripts/mxapi.py image --prompt "把她换成宇航服" --ref ./photo.jpg

# 指定比例和尺寸
python3 scripts/mxapi.py image --prompt "水墨山水" --ratio 16:9 --size 2K

# 文生视频
python3 scripts/mxapi.py video --prompt "小猫在花园里奔跑，阳光明媚" --duration 5

# 图生视频（让一张图动起来）
python3 scripts/mxapi.py video --prompt "镜头缓缓推近" --first-frame ./cat.png

# 生成歌曲
python3 scripts/mxapi.py music --desc "轻快的夏日流行曲，吉他和钢琴" --title "夏日微风"

# 指定音乐时长（10–360 秒；不传则自动决定）
python3 scripts/mxapi.py music --lyrics "微风吹过田野，阳光洒满大地" --tags "pop" --duration 120

# 查余额和价格
python3 scripts/mxapi.py balance
python3 scripts/mxapi.py price

# 需要机器解析结果时加 --json，只输出 JSON
python3 scripts/mxapi.py image --prompt "..." --json

所有联网命令可加 --channel <通道名> 发送 X-Channel，不传沿用服务端默认选择。Veo 接口始终使用服务端默认流程，不支持客户指定通道。

接口契约

模型注册和参数契约随分发包提供。使用高级接口前读取 [接口契约](references/接口契约.md)，确认方法、参数参考文档和任务查询协议。

高级接口

专用命令未覆盖的参数或能力使用 request，先读 references/全站接口.md 和对应能力文档。复杂 JSON 放在 UTF-8 文件中，通过 --data-file 传入。先用 --dry-run 检查，此模式不联网、不读取密钥；实际调用去掉 --dry-run。

python3 scripts/mxapi.py request --method POST --path /api/v2/music/sound 
  --data-file ./sound-request.json --dry-run

request 只返回完整 JSON，不会自动轮询或下载。拿到任务 ID 后按文档配对查询端点，等到完成并下载结果才交付给用户。查询用 --query '{"task_id":"..."}'。仅支持 JSON 请求和响应；不支持 multipart 文件上传和 SSE 流，stream 必须为 false。商品套图生成使用 async: true。通用写请求不会自动重试，超时后先核查已有任务，避免重复扣费。

关键行为说明

参考图会自动上传。 --ref、--first-frame、--last-frame 都接受本地路径，脚本会先上传到平台再拿公网地址提交，你不需要额外做上传这一步。只支持 jpg、jpeg、png、gif、webp，单张不超过 10 MB。上传的临时图片 3 天后会被清理，不能当图床用。

图片默认出 1 张。 只有 jimeng-4x 一次出四张。用户要多张备选时，要么用jimeng-4x，要么重复调用几次（每次都会扣积分）。

生成都要等，而且图片不一定比视频快。 实测耗时：图片 1~3 分钟（带参考图更久）、视频 2~3 分钟、音乐 2 分钟左右，高峰期会更长。所以用户等了两三分钟很正常，不要因此判断任务卡住了。脚本默认最多等：图片 5 分钟、音乐 10 分钟、视频 15 分钟。超时也不代表失败，脚本会打印一条继续查询的命令，照着执行即可。

音乐一次会生成两首。 Suno 的固定行为，两首都会下载下来，让用户挑。输出里的"歌曲 ID"要留好，后续做延长、翻唱、转 WAV 都需要它。

失败会自动退积分。 任务失败时平台会把预扣的积分退回，不用担心白扣钱。但主动取消视频任务不退积分，所以不要建议用户取消，等它跑完就好。

出错了怎么办

脚本的报错已经翻译成中文，并且带"怎么办"。按这个表处理：

需要更详细的排查步骤时，读 references/错误排查.md。

什么时候该引导用户联系官方

官方联系页：<https://open.mxapi.org/contact>

这个链接不要随便甩出去。 判断标准只有一条：这个问题用户自己能不能解决？能解决就直接告诉他怎么做；只有他再怎么操作都没用、必须平台介入时，才引导他联系。每次报错都让用户去找客服，既解决不了问题，也会真的打扰到平台。

不要提（用户自己能解决）

这些情况直接给操作指引就行，提客服反而显得你没能力处理：

• 没配密钥、密钥填错 → 引导创建密钥并 login
• 积分不足 → 引导去后台充值
• 参数错误、模型不支持某个尺寸或比例 → 按提示改参数
• 文件不存在、格式不支持、图片超过 10 MB → 换个文件
• 没装 Python、Windows 上找不到 python3 → 装 Python 或换命令
• 偶发的 502、超时 → 重试一次就好
• 被限流 429 → 脚本会自动退避重试，等着即可
• 生成结果不满意 → 调提示词或换模型
• 任务失败 → 平台会自动退积分，换个说法重试

应该提（用户无法自行解决）

• 403 账号被禁用 —— 立刻引导，用户完全无法自救
• 同一操作连续失败 3 次以上且都是 5xx —— 平台故障，不要让用户继续重试
• 密钥反复确认无误却一直 401 —— 后台数据可能有问题
• 充值了但余额没到账
• 扣了积分、任务失败，但 logs 里查不到对应的退款记录 —— 财务问题
• 业务确实需要更高的 QPS/RPM 额度 —— 只有官方能调整
• 脚本报"预料之外的问题" —— 脚本 bug，此时诊断信息已经自动生成好了
• 同一个提示词反复被判违规，用户认为是误判 —— 需要人工复核

引导时怎么说

1. 先说清楚你已经确认过什么，别让用户觉得是被推走。

比如"我试了三次都是服务端 500，你的密钥和余额都正常，这是平台侧的问题"。

1. 顺手把定位信息整理好，让用户直接粘贴给客服即可：出错时间、用的哪个能力、

任务 ID（如果有）、完整错误信息。绝对不要把 API 密钥写进去。

1. 同一次会话里最多提一次。 已经引导过就不要反复说，用户知道了。
2. 附上链接：<https://open.mxapi.org/contact>

需要更多细节时再读这些

不要一开始就全部读进来，按需加载：

• references/全站接口.md —— 当前对外接口清单、OpenAI 兼容模型名、通用调用方式
• references/图片生成.md —— 十三个图片模型的完整参数、尺寸比例限制、选型建议
• references/视频生成.md —— 六个视频模型的差异、首尾帧和多模态参考用法、计费规则
• references/音乐生成.md —— Suno 全流程：生成、上传图片/视频、延长、翻唱、下载 MP3、转 WAV、裁剪变速
• references/通用能力.md —— 图片上传、积分余额、积分流水、价格查询
• references/错误排查.md —— 全部错误码和排查步骤
• references/原始HTTP调用.md —— 仅在 Python 完全不可用时用这份手工调接口