媒体生成 API · 使用说明

基地址：https://media.mzygz.cn
鉴权：除图片文件下载外，所有请求都要带请求头 Authorization: Bearer <你的令牌>（令牌向管理员索取）

可用模型

模型名类型说明典型耗时
image-turbo图片最快、最省约 12 秒
image-flash图片均衡约 10–20 秒
image-pro图片质量优先约 20–40 秒
video-h3视频5 秒级竖屏短片，必须给参考图约 3–4 分钟

也可以直接查询：

curl https://media.mzygz.cn/v1/models -H "Authorization: Bearer YOUR_TOKEN"

一、生成图片（OpenAI 标准接口）

这是标准 OpenAI 协议 —— 任何 OpenAI 兼容客户端都能直接用（把 Base URL 改成 https://media.mzygz.cn/v1、填上令牌即可，如 Cherry Studio、NextChat、openai 官方 SDK 等）。

curl -X POST https://media.mzygz.cn/v1/images/generations \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"model":"image-turbo","prompt":"一只紫砂茶壶，写实产品图，白色背景"}'

返回：

{"created":1791782736,"data":[{"url":"https://media.mzygz.cn/files/xxxx.png"}]}

下载图片（不需要令牌，链接长期有效）：

curl -o out.png "https://media.mzygz.cn/files/xxxx.png"

二、生成视频

视频是异步任务，三步：提交 → 轮询 → 下载。

2.1 提交任务

# 参考图转成 data URI（jpg/png/webp 都行）
IMG="data:image/jpeg;base64,$(base64 -i ref.jpg | tr -d '\n')"

curl -X POST https://media.mzygz.cn/v1/video/generations \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{
        \"model\": \"video-h3\",
        \"prompt\": \"<提示词，见下方建议>\",
        \"image\": \"$IMG\",
        \"duration\": 5,
        \"resolution\": \"768p竖\"
      }"

返回：

{"id":"task_xxxxxxxx","status":"queued","created":1791782736}

记下这个 id，后面两步都要用。

参数说明

字段必填说明
model是固定 video-h3
prompt是1–20000 字符。建议描述主体、动作、场景、镜头运动
image是参考图。data:image/jpeg;base64,…（推荐）或公网可访问的 https://… 图片地址
duration否整数 1–15 秒，默认 5
resolution否480p竖 / 768p竖 / 480p横 / 768p横 / 480p(1:1) / 768p(1:1)，默认 768p竖。注意没有 720p
seed否整数，控制随机性；同参数同 seed 结果相近

2.2 轮询状态

curl https://media.mzygz.cn/v1/video/generations/<task_id> \
  -H "Authorization: Bearer YOUR_TOKEN"
# 排队中
{"code":"success","data":{"task_id":"task_xxxx","status":"NOT_START","progress":"0%"}}
# 生成中
{"code":"success","data":{"task_id":"task_xxxx","status":"IN_PROGRESS","progress":"50%"}}
# 完成
{"code":"success","data":{"task_id":"task_xxxx","status":"SUCCESS","progress":"100%",
                          "result_url":"/v1/videos/task_xxxx/content"}}

建议每 20–30 秒查一次。FAILURE 表示生成失败（fail_reason 里有原因）。

2.3 下载视频

curl -L "https://media.mzygz.cn/v1/videos/<task_id>/content" \
  -H "Authorization: Bearer YOUR_TOKEN" -o out.mp4
下载必须带令牌（不带会返回 401）。下载链接不需要另外申请、也不会过期，随时可重新下载同一个任务。

三、常见问题

现象原因与处理
401请求头 Authorization 缺失或令牌错误
400 invalid_request参数不合法。常见：resolution 写了 720p竖（不存在）；duration 超出 1–15；视频没给 image
400 unknown model模型名不在上表内，检查拼写
图片能生成、打不开链接图片链接不需要令牌，直接下载即可；链接长期有效
视频一直 NOT_START平台排队，属正常，等 3–5 分钟；超过 15 分钟未变可重试
视频 FAILURE多为提示词或参考图问题，换一张清晰参考图重试

四、小建议