H3 Studio API

← 返回生成页 Swagger 调试台 ↗ openapi.json ↗

在一张 RTX 5090 上运行的 MiniMax-H3 视频生成服务。文生视频、图生视频（1 到 6 张图），输出 24 fps 带立体声的 mp4。任务在单卡上顺序执行，新任务自动排队。

地址与鉴权

公网	https://desktop-lp9ii17.tail97a7d2.ts.net
本机	http://127.0.0.1:8000

所有 /api/* 请求都需要口令，三种传法任选一种：

推荐	Authorization: Bearer <TOKEN> 请求头
备选	x-token: <TOKEN> 请求头
备选	?token=<TOKEN> 查询参数

口令错误或缺失返回 401 {"detail":"bad token"}。口令保存在服务器的 webapp/config.json，修改后重启服务生效。已开启 CORS，浏览器页面可以直接跨域调用。

接口一览

创建任务 POST /api/v1/generate

请求体 JSON，所有字段除 prompt 外都可省略：

返回值就是任务对象；不带 wait 时立即返回，状态为 queued。

multipart 版本 POST /api/jobs

字段名与上表相同（prompt, profile, aspect, res, seconds, seed, steps），图片放在一个或多个 images 文件字段里。不支持 wait 和 callback_url，拿到 id 后用 GET /api/jobs/{id}?wait=true 等待即可。

文生图 / 改图 POST /api/v1/image

Qwen-Image-2.1（7B，2026-09-20 发布）：不传图就是文生图；传 1 到 10 张图就是改图 / 多图参考，提示词里用 Picture 1、Picture 2 指代各张图（按传入顺序）。支持中英文文字渲染。返回值同样是任务对象，成品字段是 image。实测（25 步，模型已加载）：qwen21 1K 约 4.5 秒、2K 约 27 秒；qwen21_bf16 1K 约 8 秒、2K 约 46 秒；单图改图 1K 约 7 秒；krea2_turbo 1K 约 3.3 秒、2K 约 18 秒，带 1 张风格参考约 8 秒。切换模型后的第一次调用多约 5 到 20 秒加载。

尺寸表

curl · 文生图，同步等结果

复制curl -s https://desktop-lp9ii17.tail97a7d2.ts.net/api/v1/image \
  -H "Authorization: Bearer <TOKEN>" -H "Content-Type: application/json" \
  -d '{"prompt":"一张咖啡馆海报，手写体中文标题「晨光咖啡」，暖色调，胶片质感","aspect":"3:4","res":"1K","wait":true}'
# → {"id":"…","status":"done","image":"/out/….png","image_download":"/api/jobs/…/image",…}

curl · Krea 2 Turbo 文生图 + 一张风格参考

复制curl -s https://desktop-lp9ii17.tail97a7d2.ts.net/api/v1/image   -H "Authorization: Bearer <TOKEN>" -H "Content-Type: application/json"   -d '{"prompt":"a lighthouse on a rocky coast at dawn, mist, golden light",
       "profile":"krea2_turbo","images":["https://example.com/watercolor_style.jpg"],
       "aspect":"16:9","res":"1K","wait":true}'

curl · 改图，两张参考图

复制curl -s https://desktop-lp9ii17.tail97a7d2.ts.net/api/v1/image \
  -H "Authorization: Bearer <TOKEN>" -H "Content-Type: application/json" \
  -d '{"prompt":"让 Picture 1 里的人穿上 Picture 2 的外套，保持姿势、背景和光线不变",
       "images":["https://example.com/person.png","https://example.com/coat.png"],
       "size_from_ref":true,"res":"1K"}'

curl · 上传本地图片改图（multipart）

复制curl -s https://desktop-lp9ii17.tail97a7d2.ts.net/api/images \
  -H "Authorization: Bearer <TOKEN>" \
  -F "prompt=把背景换成雪山日出，其它保持不变" -F "size_from_ref=true" \
  -F "images=@photo.png"

任务对象

复制{
  "id": "20260918_202901_6197",
  "kind": "video | image",                // image = Qwen-Image-2.1 任务
  "status": "queued | running | done | failed",
  "prompt": "…", "profile": "fasth3", "mode": "t2v | i2v | t2i | edit",
  "aspect": "16:9", "res": "480p", "size": "864x480",
  "seconds": 5.0, "frames": 124, "seed": 1234, "steps": 8, "image_count": 0,
  "created": 1789731030.1,

  "position": 1,                          // queued：队列位置（1 = 下一个）
  "progress": {"value": 3, "max": 8},     // running：采样步进度
  "stage": "采样", "elapsed": 12.3,        // running：当前阶段、已用秒数

  "exec_s": 24.7,                         // done：生成耗时（秒）
  "video": "/out/20260918_202901_6197.mp4",             // done（视频）：可直接播放的静态地址
  "video_download": "/api/jobs/20260918_202901_6197/video",  // done（视频）：带文件名的下载地址
  "image": "/out/….png", "image_download": "/api/jobs/…/image",  // done（图片）：同上；另有 negative, cfg, size_from_ref
  "finished": 1789731060.2,

  "error": "…",                           // failed：原因
  "callback_status": 200                  // 设置了 callback_url 时：回调的 HTTP 状态
}

stage 依次经过：加载模型 → 加载文本编码器 → 编码提示词/图片 → 采样 → 视频解码 → 音频解码 → 封装 → 保存。模型只在切换方案时重新加载。

可选值

耗时参考

RTX 5090，fasth3 8 步，实测每条片子的生成耗时（不含排队）：

fasth3_4step_int8 采样步数减半，整体约快 30% 到 40%。切换方案的第一条任务多 3 到 10 秒加载时间。同一时间只跑一个任务，排队时间 = 前面任务的耗时之和。

调用示例

curl · 文生视频，同步等结果，然后下载

复制curl -s https://desktop-lp9ii17.tail97a7d2.ts.net/api/v1/generate \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"一只戴墨镜的小熊猫在舞台上打鼓，暖色聚光灯，观众欢呼，电影感。声音：鼓点、欢呼声。","res":"480p","seconds":5,"wait":true}'

# 返回的 JSON 里 status 为 done 时：
curl -L -o clip.mp4 -H "Authorization: Bearer <TOKEN>" \
  https://desktop-lp9ii17.tail97a7d2.ts.net/api/jobs/<id>/video

curl · 图生视频，两张图（首帧 + 末帧），不等待

复制curl -s https://desktop-lp9ii17.tail97a7d2.ts.net/api/v1/generate \
  -H "Authorization: Bearer <TOKEN>" -H "Content-Type: application/json" \
  -d '{"prompt":"镜头缓慢推进，画面从第一帧过渡到最后一帧。声音：轻柔的风声。",
       "images":["https://example.com/first.png","https://example.com/last.png"],
       "res":"480p","seconds":5}'
# → {"id":"2026…","status":"queued",…}

curl -s -H "Authorization: Bearer <TOKEN>" \
  "https://desktop-lp9ii17.tail97a7d2.ts.net/api/jobs/<id>?wait=true&timeout=600"

curl · 参考图模式（视频不从图片开始）

复制curl -s https://desktop-lp9ii17.tail97a7d2.ts.net/api/v1/generate \
  -H "Authorization: Bearer <TOKEN>" -H "Content-Type: application/json" \
  -d '{"prompt":"<Picture 1> 里的女孩走进咖啡馆，坐到窗边翻开一本书，镜头缓慢推近。声音：咖啡馆环境音。",
       "images":["https://example.com/girl.png"], "image_mode":"reference",
       "res":"480p","seconds":5}'

curl · 声音克隆朗读台词并对口型

复制curl -s https://desktop-lp9ii17.tail97a7d2.ts.net/api/v1/generate \
  -H "Authorization: Bearer <TOKEN>" -H "Content-Type: application/json" \
  -d '{"prompt":"<Picture 1> 里的老人站在灯塔窗前，面部特写，认真地对着镜头说话，口型清晰。声音：他的声音，雨声。",
       "images":["https://example.com/keeper.png"],
       "audios":["https://example.com/keeper_voice.wav"],
       "tts_text":"海上的风很大，你要小心。今晚我会一直守在这里。",
       "tts_ref_text":"别怕，灯还亮着。我在这儿等你回来。", "tts_language":"Chinese",
       "res":"480p","seconds":5}'

只想要语音不要视频：POST /api/v1/tts，JSON 字段 text、ref_audio、ref_text（可选）、language，同步返回 {"audio":"/out/tts_….wav"}。

curl · 上传本地图片（multipart）

复制curl -s https://desktop-lp9ii17.tail97a7d2.ts.net/api/jobs \
  -H "Authorization: Bearer <TOKEN>" \
  -F "prompt=The scene comes alive, gentle camera drift. Audio: ambient." \
  -F "res=480p" -F "seconds=5" \
  -F "images=@first.png" -F "images=@middle.png" -F "images=@last.png"

Python · 轮询进度并下载

复制import base64, time, requests

BASE = "https://desktop-lp9ii17.tail97a7d2.ts.net"
H = {"Authorization": "Bearer <TOKEN>"}

def data_uri(path):
    return "data:image/png;base64," + base64.b64encode(open(path, "rb").read()).decode()

job = requests.post(f"{BASE}/api/v1/generate", headers=H, json={
    "prompt": "A golden retriever puppy runs through autumn leaves, slow motion. Audio: leaves crunching.",
    "images": [data_uri("first.png")],      # 可省略 → 文生视频
    "res": "480p", "seconds": 5, "seed": 42,
}).json()

while job["status"] in ("queued", "running"):
    time.sleep(3)
    job = requests.get(f"{BASE}/api/jobs/{job['id']}", headers=H).json()
    print(job["status"], job.get("position"), job.get("stage"), job.get("progress"))

if job["status"] == "done":
    mp4 = requests.get(BASE + job["video_download"], headers=H).content
    open("clip.mp4", "wb").write(mp4)
    print("saved, generation took", job["exec_s"], "s")
else:
    print("failed:", job.get("error"))

JavaScript · 浏览器 fetch，同步等待后直接播放

复制const BASE = "https://desktop-lp9ii17.tail97a7d2.ts.net";
const r = await fetch(BASE + "/api/v1/generate", {
  method: "POST",
  headers: { "Authorization": "Bearer <TOKEN>", "Content-Type": "application/json" },
  body: JSON.stringify({ prompt: "城市夜景航拍，霓虹反射在湿润的街道上。声音：车流、雨声。", res: "352p", seconds: 5, wait: true })
});
const job = await r.json();
if (job.status === "done") document.querySelector("video").src = BASE + job.video;   // /out/… 不需要口令

回调模式

提交时带 "callback_url": "https://你的服务器/hook"，任务结束后会向该地址 POST 一份任务对象（成功和失败都会发）。video 是相对路径，拼上 BASE 即可下载；回调的 HTTP 状态会记录在任务的 callback_status。

错误与限制

• 单卡顺序执行，同一时刻只有一个任务在生成，其余排队；position 是队列位置。
• 图片最多 6 张，单张 25 MB 以内，png / jpg / webp。
• 任务失败时 error 带 ComfyUI 的异常信息；服务重启会把未完成的任务标记为失败。
• 成品和上传图保存在服务器上，不会自动清理，用 DELETE /api/jobs/{id} 删除。
• 相同 prompt、参数和 seed 会复现同一条片子；换分辨率后不是同一画面的缩放，而是重新生成。