MINIMAXH3

开始

调用约定

本站页面走通用格式：提交拿到 task_id，再轮询结果。不要把方舟的 content 数组发到 /v1/videos/generations。

Header 写 Authorization: Bearer <Key>，或 X-API-Key。只写 Key、不加 Bearer 也可以。
图片、视频、数字人提交成功是 HTTP 202，返回 task_id。当场没有成品 URL。
立刻 GET /v1/tasks/{task_id}，每 3 到 5 秒一次。status=success 后再读 result_urls。

鉴权

方式	Header	值
Bearer	`Authorization`	`Bearer your-api-key`
X-API-Key	`X-API-Key`	`your-api-key`

写请求时记住

model 传 minimaxH3。完整列表看 GET /v1/models 的 id 和 caps。页面按钮（时长只有 5 / 10）是界面简化，不是接口限制。
网页默认浅洗，会带 face.mode=light。API 不传 face 是不过脸（原图上传），不是浅洗。要旧打码请写旧 mode，见「过脸」。要关也可写 face.enabled=false。
通用视频字段写 ratio、video_resolution、first_frame_url。方舟才认 size / aspect_ratio / content / 扁平 image_urls。
cgt-... 和 UUID 都可以查 /v1/tasks/{id}。

错误码

HTTP	含义
`400`	参数无效，或渠道不存在 / 已关闭
`401`	Key 无效、过期或已禁用
`402`	积分不足
`429`	超限。默认 60 次/分钟。生成中任务过多时带 `"code":"GENERATING_LIMIT"`
`500`	内部错误
`503`	繁忙，稍后重试

提交 + 轮询

import requests, time

API = "https://jboybyncfylu.sealosbja.site"
H = {"Authorization": "Bearer your-api-key"}
r = requests.post(f"{API}/v1/images/generations", headers=H,
    data={"prompt": "雨后街道，暖色店灯", "model": "minimaxH3", "ratio": "1:1"})
r.raise_for_status()
tid = r.json()["task_id"]
while True:
    time.sleep(3)
    t = requests.get(f"{API}/v1/tasks/{tid}", headers=H).json()
    if t["status"] == "success":
        print(t["result_urls"]); break
    if t["status"] == "failed":
        print(t.get("fail_reason")); break

错误体

{
  "error": "错误信息"
}
{
  "error": "当前有 N 个任务正在生成中，请等待完成后再提交",
  "code": "GENERATING_LIMIT"
}

生成

POST `/v1/images/generations`

文本生图或参考图生图。可用 multipart/form-data 或 JSON。成功 HTTP 202，返回 task_id。兼容路径 /api/v3/images/generations 参数相同。

不传参考图就是文生图。网页默认会带 face.mode=light。API 不传 face 则不过脸，原图上传。

参数

参数	类型	必填	默认	说明
`prompt`	string	是	-	最大 8000 字符
`model`	string	否	`minimaxH3`	以 `GET /v1/models` 的 `id` 为准
`ratio`	string	否	`1:1`	`1:1` `4:3` `3:4` `16:9` `9:16` `3:2` `2:3` `21:9`
`resolution`	string	否	`2k`	`1k` / `2k` / `4k`，看该模型 `caps.res`
`negative_prompt`	string	否		不想出现的内容
`intelligent_ratio`	boolean	否	-	智能比例
`channel`	string	否	平台默认	先 `GET /v1/channels`。图片不要写死 `official`
`face`	object / JSON	否	网页浅洗	字段见「过脸」

multipart

curl -X POST "https://jboybyncfylu.sealosbja.site/v1/images/generations" \
  -H "Authorization: Bearer your-api-key" \
  -F "prompt=雨后街道，暖色店灯，50mm" \
  -F "model=minimaxH3" \
  -F "ratio=16:9" \
  -F "resolution=2k" \
  -F 'face={"enabled":true,"mode":"light"}'

JSON

{
  "prompt": "雨后街道，暖色店灯，50mm",
      "model": "minimaxH3",
  "ratio": "16:9",
  "resolution": "2k",
  "face": { "enabled": true, "mode": "light" }
}

响应 HTTP 202

{
  "task_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "pending",
  "model": "minimaxH3",
  "created_at": "2026-04-01T12:00:00.000Z"
}

一张参考图：文件字段 images，或 URL 字段 image_url。不要混用两套。强度用 sample_strength（0~1，默认 0.5）。

在文生图参数之外再加

参数	类型	必填	说明
`images`	file	二选一	参考图文件，单张 ≤20MB
`image_url`	string	二选一	参考图 URL
`sample_strength`	number	否	默认 `0.5`，越大越像参考
`face`	object / JSON	否	只处理本单参考图。网页默认浅洗

张数上限看该模型 caps.maxRef。路由最多收 10 张文件。

文件

curl -X POST "https://jboybyncfylu.sealosbja.site/v1/images/generations" \
  -H "Authorization: Bearer your-api-key" \
  -F "prompt=转成水彩" \
  -F "model=minimaxH3" \
  -F "sample_strength=0.6" \
  -F "images=@/path/to/ref.jpg" \
  -F 'face={"enabled":true,"mode":"light"}'

URL JSON

{
  "prompt": "转成水彩",
  "model": "minimaxH3",
  "sample_strength": 0.6,
  "image_url": "https://example.com/ref.jpg",
  "face": { "enabled": true, "mode": "light" }
}

多张参考：重复提交 images 文件，或一次给 image_urls 数组。JSON 字符串和数组都认。

在文生图参数之外再加

参数	类型	必填	说明
`images`	file[]	二选一	最多 10 张，单张 ≤20MB
`image_urls`	string / array	二选一	多张参考 URL
`sample_strength`	number	否	默认 `0.5`
`face`	object / JSON	否	每张参考图都会按本单过脸

也可以同时给 image_url 和 image_urls，会拼成一张列表。仍受 caps.maxRef 限制。

多文件

curl -X POST "https://jboybyncfylu.sealosbja.site/v1/images/generations" \
  -H "Authorization: Bearer your-api-key" \
  -F "prompt=融合这些参考" \
  -F "model=minimaxH3" \
  -F "images=@/path/to/a.jpg" \
  -F "images=@/path/to/b.jpg"

URL 数组

curl -X POST "https://jboybyncfylu.sealosbja.site/v1/images/generations" \
  -H "Authorization: Bearer your-api-key" \
  -F "prompt=融合这些参考" \
  -F "model=minimaxH3" \
  -F 'image_urls=["https://example.com/a.jpg","https://example.com/b.jpg"]'

JSON

{
  "prompt": "融合这些参考",
  "model": "minimaxH3",
  "image_urls": [
    "https://example.com/a.jpg",
    "https://example.com/b.jpg"
  ]
}

生成

POST `/v1/videos/generations`

通用格式。字段用 prompt，不要发方舟 content 数组。可用 multipart 或 JSON。成功 HTTP 202。三种模式请分开看，不要混字段。

三种模式共用下面这张表。模式专属字段写在对应页。当前模型支不支持某模式，看 GET /v1/models 的 caps.modes。

共用参数

参数	类型	必填	默认	说明
`prompt`	string	是	-	最大 8000 字符
`model`	string	否	`minimaxH3`	以 `GET /v1/models` 为准
`ratio`	string	否	`1:1`	同图片那 8 档。建议显式写 `16:9` 或 `9:16`。不要传 `adaptive`
`duration`	number	否	`5`	整数秒。多数模型 `caps.dur` 是 4~30，或以离散档为准
`video_resolution`	string	否	`720p`	看 `caps.res`。本接口不认 `resolution` 别名
`function_mode`	string	否	自动	`first_last_frames` / `multi_frame` / `omni_reference`
`channel`	string	否	平台默认	先 `GET /v1/channels`
`face`	object / JSON	否	网页浅洗	只处理本单里的参考图片

不写 function_mode 时怎么判

你传了什么	判定
`materials`，或 `image_file_` / `video_file_` / `audio_file_*`	`omni_reference`
`frame_1`…`frame_10` 文件 + `multi_frames` 合计 ≥ 2	`multi_frame`
其余（无图、仅首帧、首尾帧都算）	`first_last_frames`

建议显式写 function_mode，避免字段混用被判错。

提交成功 HTTP 202

{
  "task_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "pending",
  "model": "minimaxH3",
  "created_at": "2026-04-01T12:00:00.000Z"
}

接着轮询

GET /v1/tasks/{task_id}
Authorization: Bearer your-api-key

三种模式的请求体见左边各页。方舟的 size / aspect_ratio / image_urls / content 不要发到本接口。

function_mode = first_last_frames

首尾帧

同一模式里有三种用法：不附图（文生视频）、只给首帧、首帧加尾帧。不写 function_mode 时，只要没走到多帧或全能引用，就会落到这里。

文生视频不传任何帧。只靠 prompt 出片。 仅首帧给 first_frame 或 first_frame_url。画面从这张图开始动。 首尾帧再加 end_frame 或 end_frame_url。从站到坐这类动作用这个。

本模式参数

参数	类型	必填	说明
`prompt`	string	是	动作和镜头。最大 8000
`function_mode`	string	否	写成 `first_last_frames`
`first_frame`	file	否	首帧文件，单张 ≤20MB。与 URL 二选一
`first_frame_url`	string	否	首帧 URL
`end_frame`	file	否	尾帧文件。与 URL 二选一
`end_frame_url`	string	否	尾帧 URL
`ratio`	string	否	默认 `1:1`，建议写 `16:9` / `9:16`
`duration`	number	否	默认 5。看 `caps.dur`
`video_resolution`	string	否	默认按计费当 `720p`
`model` / `channel` / `face`		否	同共用页。过脸只处理首尾帧图片

文件还是 URL

同一端只选一种：首帧用文件就不要再写 first_frame_url。
本接口不认 image_urls。那是方舟扁平字段。
可以只有首帧、没有尾帧。只有尾帧没有首帧一般没有意义。

1. 文生视频 JSON

{
  "model": "minimaxH3",
  "prompt": "猫咪在草地上奔跑",
  "function_mode": "first_last_frames",
  "ratio": "9:16",
  "duration": 15,
  "video_resolution": "720p"
}

2. 仅首帧 JSON

{
  "model": "minimaxH3",
  "prompt": "镜头缓缓前推，人物转头微笑",
  "function_mode": "first_last_frames",
  "ratio": "16:9",
  "duration": 8,
  "first_frame_url": "https://example.com/first.jpg",
  "face": { "enabled": true, "mode": "light" }
}

3. 首尾帧 multipart

curl -X POST "https://jboybyncfylu.sealosbja.site/v1/videos/generations" \
  -H "Authorization: Bearer your-api-key" \
  -F "prompt=人物从站立坐下" \
  -F "model=minimaxH3" \
  -F "function_mode=first_last_frames" \
  -F "ratio=16:9" \
  -F "duration=10" \
  -F "video_resolution=720p" \
  -F "first_frame_url=https://example.com/standing.jpg" \
  -F "end_frame_url=https://example.com/sitting.jpg"

4. 本地文件

curl -X POST "https://jboybyncfylu.sealosbja.site/v1/videos/generations" \
  -H "Authorization: Bearer your-api-key" \
  -F "prompt=人物从站立坐下" \
  -F "model=minimaxH3" \
  -F "function_mode=first_last_frames" \
  -F "first_frame=@/path/to/standing.jpg" \
  -F "end_frame=@/path/to/sitting.jpg" \
  -F "duration=10"

function_mode = multi_frame

多帧

至少 2 个关键帧，最多 10 个。用来卡几个时间点的画面。先确认该模型 caps.modes 含 multi_frame，没有就不要走这一页。

本模式参数

参数	类型	必填	说明
`prompt`	string	是	整段描述
`function_mode`	string	建议	写成 `multi_frame`
`frame_1` ~ `frame_10`	file	二选一	按序号上传。单张 ≤20MB。至少 2 帧
`multi_frames`	array	二选一	URL 字符串，或 `{ "url": "..." }`
`ratio` / `duration` / `video_resolution`		否	同共用页
`face`	object / JSON	否	只处理这些关键帧图片

怎么凑满 2 帧

文件：frame_1 + frame_2，可继续到 frame_10。
URL：multi_frames 数组长度 ≥ 2。
可以文件和 URL 混用，合计 ≥ 2 才会自动判成多帧。
不要用 first_frame / image_file_* 来传多帧。

文件 multipart

curl -X POST "https://jboybyncfylu.sealosbja.site/v1/videos/generations" \
  -H "Authorization: Bearer your-api-key" \
  -F "prompt=从门口走到窗边再坐下" \
  -F "model=minimaxH3" \
  -F "function_mode=multi_frame" \
  -F "ratio=16:9" \
  -F "duration=10" \
  -F "frame_1=@/path/to/door.jpg" \
  -F "frame_2=@/path/to/window.jpg" \
  -F "frame_3=@/path/to/sit.jpg"

URL JSON

{
  "model": "minimaxH3",
  "prompt": "从门口走到窗边再坐下",
  "function_mode": "multi_frame",
  "ratio": "16:9",
  "duration": 10,
  "multi_frames": [
    "https://example.com/door.jpg",
    "https://example.com/window.jpg",
    { "url": "https://example.com/sit.jpg" }
  ]
}

URL multipart

curl -X POST "https://jboybyncfylu.sealosbja.site/v1/videos/generations" \
  -H "Authorization: Bearer your-api-key" \
  -F "prompt=从门口走到窗边再坐下" \
  -F "model=minimaxH3" \
  -F "function_mode=multi_frame" \
  -F 'multi_frames=["https://example.com/door.jpg","https://example.com/window.jpg"]'

function_mode = omni_reference

全能引用

混用图片、视频、音频。prompt 里每个 @名称 必须对上一个素材。下面四组都是完整请求，按组合看。

参数	说明
`function_mode`	写成 `omni_reference`
`image_file_1` ~ `30`	图片文件或 URL。引用名是字段名
`video_file_1` ~ `10`	视频，单个 ≤20MB
`audio_file_1` ~ `10`	音频，单个 ≤20MB，≤15 秒
`materials`	JSON 数组。每项 `type` + `url` + `name`

两个角色同框。文件用 @image_file_1 @image_file_2。URL 用 materials.name，例如 @角色A @角色B。

素材	你传	prompt 里写
角色 A	`image_file_1` 或 `name=角色A`	`@image_file_1` / `@角色A`
角色 B	`image_file_2` 或 `name=角色B`	`@image_file_2` / `@角色B`

本页共用字段

function_mode=omni_reference。materials 每条必须有 type、url、name。prompt 以 @ 开头时 curl 用 --form-string。

文件

curl -X POST "https://jboybyncfylu.sealosbja.site/v1/videos/generations" \
  -H "Authorization: Bearer your-api-key" \
  --form-string "prompt=@image_file_1 和 @image_file_2 坐在对面说话" \
  -F "model=minimaxH3" \
  -F "function_mode=omni_reference" \
  -F "ratio=16:9" \
  -F "duration=8" \
  -F "image_file_1=@/path/to/charA.jpg" \
  -F "image_file_2=@/path/to/charB.jpg"

JSON（自定义中文名）

{
  "model": "minimaxH3",
  "prompt": "@角色A 和 @角色B 坐在对面说话",
  "function_mode": "omni_reference",
  "ratio": "16:9",
  "duration": 8,
  "materials": [
    { "type": "image", "name": "角色A", "url": "https://example.com/charA.jpg" },
    { "type": "image", "name": "角色B", "url": "https://example.com/charB.jpg" }
  ]
}

一张人像加一段参考音频。音频单个 ≤20MB，时长 ≤15 秒，建议 mp3 / wav。

素材	你传	prompt 里写
人像	`image_file_1` 或 `name=演员`	`@image_file_1` / `@演员`
音乐	`audio_file_1` 或 `name=配乐`	`@audio_file_1` / `@配乐`

文件

curl -X POST "https://jboybyncfylu.sealosbja.site/v1/videos/generations" \
  -H "Authorization: Bearer your-api-key" \
  --form-string "prompt=@image_file_1 在咖啡馆微笑，背景音乐用 @audio_file_1" \
  -F "model=minimaxH3" \
  -F "function_mode=omni_reference" \
  -F "ratio=9:16" \
  -F "duration=8" \
  -F "image_file_1=@/path/to/charA.jpg" \
  -F "audio_file_1=@/path/to/bg.mp3"

JSON

{
  "model": "minimaxH3",
  "prompt": "@演员 在咖啡馆微笑，背景音乐用 @配乐",
  "function_mode": "omni_reference",
  "ratio": "9:16",
  "duration": 8,
  "materials": [
    { "type": "image", "name": "演员", "url": "https://example.com/charA.jpg" },
    { "type": "audio", "name": "配乐", "url": "https://example.com/bg.mp3" }
  ],
  "face": { "enabled": true, "mode": "light" }
}

用一张图定人，用一段视频定场景或动作。参考视频单个 ≤20MB。

素材	你传	prompt 里写
人物	`image_file_1` 或 `name=人物`	`@image_file_1` / `@人物`
场景	`video_file_1` 或 `name=场景`	`@video_file_1` / `@场景`

文件

curl -X POST "https://jboybyncfylu.sealosbja.site/v1/videos/generations" \
  -H "Authorization: Bearer your-api-key" \
  --form-string "prompt=@image_file_1 走进 @video_file_1 的街道里" \
  -F "model=minimaxH3" \
  -F "function_mode=omni_reference" \
  -F "ratio=16:9" \
  -F "duration=10" \
  -F "image_file_1=@/path/to/person.jpg" \
  -F "video_file_1=@/path/to/street.mp4"

JSON

{
  "model": "minimaxH3",
  "prompt": "@人物 走进 @场景 的街道里",
  "function_mode": "omni_reference",
  "ratio": "16:9",
  "duration": 10,
  "materials": [
    { "type": "image", "name": "人物", "url": "https://example.com/person.jpg" },
    { "type": "video", "name": "场景", "url": "https://example.com/street.mp4" }
  ]
}

两个人 + 一段场景视频 + 一段配乐。张数不能超过该模型 caps.materials。后缀 933 = 图 9 / 视频 3 / 音频 3。

素材	你传	prompt 里写
角色 A	`image_file_1` / `name=角色A`	`@image_file_1` / `@角色A`
角色 B	`image_file_2` / `name=角色B`	`@image_file_2` / `@角色B`
场景	`video_file_1` / `name=场景`	`@video_file_1` / `@场景`
配乐	`audio_file_1` / `name=配乐`	`@audio_file_1` / `@配乐`

不要只写 materials.name 却不给 url，再另传文件。@角色A 对不上 image_file_1。
过脸只处理图片素材。

文件（四件）

curl -X POST "https://jboybyncfylu.sealosbja.site/v1/videos/generations" \
  -H "Authorization: Bearer your-api-key" \
  --form-string "prompt=@image_file_1 和 @image_file_2 在 @video_file_1 里对话，背景音乐用 @audio_file_1" \
  -F "model=minimaxH3" \
  -F "function_mode=omni_reference" \
  -F "ratio=16:9" \
  -F "duration=10" \
  -F "image_file_1=@/path/to/charA.jpg" \
  -F "image_file_2=@/path/to/charB.jpg" \
  -F "video_file_1=@/path/to/cafe.mp4" \
  -F "audio_file_1=@/path/to/bg.mp3"

JSON（四件）

{
  "model": "minimaxH3",
  "prompt": "@角色A 和 @角色B 在 @场景 里对话，背景音乐用 @配乐",
  "function_mode": "omni_reference",
  "ratio": "16:9",
  "duration": 10,
  "materials": [
    { "type": "image", "name": "角色A", "url": "https://example.com/charA.jpg" },
    { "type": "image", "name": "角色B", "url": "https://example.com/charB.jpg" },
    { "type": "video", "name": "场景", "url": "https://example.com/cafe.mp4" },
    { "type": "audio", "name": "配乐", "url": "https://example.com/bg.mp3" }
  ],
  "face": { "enabled": true, "mode": "light" }
}

生成

POST `/v1/videos/lip-sync`

人像加音频，一次对口型。数字人没有过脸。face_index 只表示选哪张脸。请用自动模式。

一张人像 + 一段音频，同一请求提交。成功 HTTP 202。接着 GET /v1/tasks/{id}。

参数

参数	类型	必填	说明
`image`	file	三选一	人像文件
`image_url`	string		人像 URL
`image_uri`	string		上游已有的人像 URI。不要传 `local:` 前缀
`audio`	file	三选一	音频文件
`audio_url`	string		音频 URL
`audio_vid`	string		上游已有的音频 id。不要传 `local:` 前缀
`model`	string	否	默认 `minimaxH3`
`prompt`	string	否	可选场景说明
`face_index`	number	否	选哪张脸，默认 0。不是过脸
`audio_duration`	number	否	毫秒，用来控制生成时长
`channel`	string	否	先 `GET /v1/channels`

文件

curl -X POST "https://jboybyncfylu.sealosbja.site/v1/videos/lip-sync" \
  -H "Authorization: Bearer your-api-key" \
  -F "image=@/path/to/portrait.jpg" \
  -F "audio=@/path/to/speech.mp3" \
  -F "model=minimaxH3" \
  -F "prompt=室内采访，正面中景"

URL

curl -X POST "https://jboybyncfylu.sealosbja.site/v1/videos/lip-sync" \
  -H "Authorization: Bearer your-api-key" \
  -F "image_url=https://example.com/portrait.jpg" \
  -F "audio_url=https://example.com/speech.mp3" \
  -F "model=minimaxH3"

响应 HTTP 202

{
  "task_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "pending",
  "model": "minimaxH3",
  "created_at": "2026-04-01T12:00:00.000Z"
}

拆步接口现在不暂存素材。请仍把人像和音频放在一次请求里提交。

各步现状

接口	现状
POST `/v1/videos/lip-sync/upload-image`	HTTP 400：`素材请在创建任务时一并提交，本机不暂存文件`
POST `/v1/videos/lip-sync/upload-audio`	同上
POST `/v1/videos/lip-sync/detect-faces`	不真实检脸。返回占位 `session_id=deferred`，`faces=[{index:0}]`，`expires_in=0`
POST `/v1/videos/lip-sync/submit`	可以创建任务，但人像和音频必须仍在这一次请求里
POST `/v1/videos/lip-sync/cancel`	返回成功，本机无会话可取消

submit 参数

参数	类型	必填	说明
`image` / `image_url` / `image_uri`	file / string	三选一	人像
`audio` / `audio_url` / `audio_vid`	file / string	三选一	音频
`model`	string	否	默认 `minimaxH3`
`prompt`	string	否	可选说明
`face_index`	number	否	选哪张脸，默认 0
`audio_duration`	number	否	毫秒
`channel`	string	否	计费渠道

成功同样 HTTP 202。和自动模式是同一条入队逻辑。

submit（带文件）

curl -X POST "https://jboybyncfylu.sealosbja.site/v1/videos/lip-sync/submit" \
  -H "Authorization: Bearer your-api-key" \
  -F "image=@/path/to/portrait.jpg" \
  -F "audio=@/path/to/speech.mp3" \
  -F "model=minimaxH3" \
  -F "face_index=0"

detect-faces 现网返回

{
  "session_id": "deferred",
  "faces": [{ "index": 0 }],
  "face_count": 1,
  "image_uri": "",
  "expires_in": 0,
  "detection": "deferred"
}

生成

过脸

是否过脸、用哪一档，只看这一单的 face。网页默认浅洗，会显式带 mode:light。API 不传 face 是不过脸（原图），不是浅洗，也不是网页那套旧打码。数字人的 face_index 不是过脸。

网页默认。必须显式带 mode: "light"。不传 face 是不过脸。只写 face: true 是旧过脸（子客户端默认模糊整张脸），不是浅洗。

	内容
下发	`face: { enabled: true, mode: "light" }`
效果	轻磨皮，五官还在
别名	`轻` / `洗淡` / `风格`
无效字段	`range` / `shape` / `strength` / `margin`

按单生效，队列里各任务互不影响
没检出脸：该张原图上传，不报错
前端不要把修复前缀拼进 params.prompt
网页样片只是预览，不代替真实检脸

图片 JSON

{
  "prompt": "雨后街道，暖色店灯",
  "model": "minimaxH3",
  "image_url": "https://example.com/ref.jpg",
  "face": { "enabled": true, "mode": "light" }
}

视频 JSON

{
  "prompt": "人物转头微笑",
  "model": "minimaxH3",
  "function_mode": "first_last_frames",
  "first_frame_url": "https://example.com/first.jpg",
  "face": { "enabled": true, "mode": "light" }
}

multipart

-F 'face={"enabled":true,"mode":"light"}'

整张偏彩铅 / 浅色素描。同样必须带 mode，不要只写 enabled: true。

	内容
下发	`face: { enabled: true, mode: "heavy" }`
效果	整张偏彩铅 / 浅色素描
别名	`重` / `素描风` / `first_reference` / `full`
无效字段	`range` / `shape` / `strength` / `margin`

JSON

{
  "prompt": "转成水彩",
  "model": "minimaxH3",
  "image_url": "https://example.com/ref.jpg",
  "face": { "enabled": true, "mode": "heavy" }
}

multipart

-F 'face={"enabled":true,"mode":"heavy"}'

原图预览，原图上传。API 不传 face 和写 enabled: false 效果一样。网页不过脸会显式带 enabled: false。

	内容
下发	`face: { enabled: false }` 或 `face: false`
效果	不过脸，原图上传

JSON

{
  "prompt": "雨后街道，暖色店灯",
  "model": "minimaxH3",
  "image_url": "https://example.com/ref.jpg",
  "face": { "enabled": false }
}

multipart

-F 'face={"enabled":false}'

过脸放 JSON 根上。方舟不要塞进 content。数字人没有过脸。

接口	怎么传
`POST /v1/images/generations`	JSON 对象，或 multipart 里 `face` 的 JSON 字符串
`POST /v1/videos/generations`	同上。只处理首帧 / 多帧 / 全能引用里的图片
`POST /api/v3/images/generations`	JSON 顶层 `face`
`POST /api/v3/contents/generations/tasks`	JSON 顶层 `face`，不要塞进 `content`

请求会落到哪一档

请求	行为
不传 `face` / `faceMode`，或 `{}`	不过脸，原图上传
`face: false` / `enabled: false`	不过脸，原图上传
`face: true` 或 `{enabled:true}`，不写 mode	旧过脸，子客户端默认 `blur` + 整张脸
`mode=light` / `heavy`	浅洗 / 重风格
旧 `mode=blur/pixel/cutleft` 等	旧 YuNet 打码

人脸拒 FACE_REJECTED 返回中文原文。

方舟视频（face 在根上）

{
  "model": "minimaxH3",
  "content": [
    { "type": "text", "text": "猫咪奔跑 --ratio 16:9 --dur 8" },
    { "type": "image_url", "image_url": "https://example.com/first.jpg", "role": "first_frame" }
  ],
  "face": { "enabled": true, "mode": "light" }
}

子客户端先 YuNet 检脸，再按 mode 盖 range。浅洗 / 重风格不读这些字段。网页选「旧打码」会带齐整套表单；API 请自己写全，不要只传 face: true 就当和网页一样。

旧过脸 = mode 是 blur / pixel / mask / grid / sketch / pencil / cutleft / sketchcut。写成 light / heavy 就不是旧档。网关不补默认打码。

没有过脸字段，或 face 是空对象 {}：不过脸，原图上传。
face: false 或 enabled: false：不过脸。
mode 是 light / heavy：浅洗 / 重风格，不读下面这些旧字段。
mode 是旧档，或 face: true 且没写 light / heavy：走旧 YuNet。

你怎么传	实际走哪套
网页选「旧打码」	带齐表单：默认 `cutleft` + `tface` + `rect`，强度 100，边距 23，置信 0.75，偏移 1.73
API 写齐旧字段	按你写的 `mode` / `range` / `origin` 打码
`face: true` 或 `{enabled:true}`，不写 mode	子客户端用自己的旧默认：`blur` + 整张脸 `face` + 椭圆，强度 30，边距 0，置信 0.45。和网页旧打码不一样
只写 `face.mode=pixel` 等旧档	过脸，没写的项用子客户端默认
不传 `face` 或 `{}`	不过脸，原图上传。要旧打码必须显式写旧 `mode`，或 `face: true`

只处理本单参考图。视频 / 音频原样落地。
没检出脸：该张原图上传，不报错。
某张打码失败：该张用原图，不挡交单。
多张参考图共用这一套参数。

网页旧打码实际下发

{
  "prompt": "雨后街道，暖色店灯",
      "model": "minimaxH3",
  "image_url": "https://example.com/ref.jpg",
  "face": {
    "enabled": true,
    "mode": "cutleft",
    "range": "tface",
    "shape": "rect",
    "origin": "mask",
    "strength": 100,
    "margin": 23,
    "confidence": 0.75,
    "offset": 1.73
  }
}

只开旧过脸（子客户端默认模糊整张脸）

{
  "prompt": "雨后街道，暖色店灯",
  "image_url": "https://example.com/ref.jpg",
  "face": true
}

multipart 网页旧打码

curl -X POST "https://jboybyncfylu.sealosbja.site/v1/images/generations" \
  -H "Authorization: Bearer your-api-key" \
  -F "prompt=雨后街道，暖色店灯" \
  -F "model=minimaxH3" \
  -F "images=@/path/to/ref.jpg" \
  -F 'face={"enabled":true,"mode":"cutleft","range":"tface","shape":"rect","origin":"mask","strength":100,"margin":23,"confidence":0.75,"offset":1.73}'

mode 决定罩子里怎么画。非法值退回 blur。也认中文：模糊 马赛克 纯色 网格 素描 铅笔 抠到左边 抠图转素描。

mode	界面	罩子里做什么
`blur`	模糊	高斯模糊。子客户端只写 `face: true` 时用这个
`pixel`	马赛克	像素块
`mask`	纯色遮罩	罩内填深色
`grid`	网格	网格线
`sketch`	素描	罩内转线稿
`pencil`	铅笔	罩内转带灰调的铅笔
`cutleft`	抠到左边	原位按 `origin` 填，罩内像素挪到旁边。见「抠到旁边」
`sketchcut`	抠图转素描	挪过去的那块先转素描。见「抠到旁边」

strength 1~100，越大越狠。网页旧打码默认 100；子客户端缺省 30。

马赛克，只盖眼睛

{
  "prompt": "雨后街道，暖色店灯",
  "model": "minimaxH3",
  "image_url": "https://example.com/ref.jpg",
  "face": {
    "enabled": true,
    "mode": "pixel",
    "range": "eyes",
    "shape": "ellipse",
    "strength": 80
  }
}

模糊整张脸（子客户端缺省）

{
  "prompt": "雨后街道，暖色店灯",
  "image_url": "https://example.com/ref.jpg",
  "face": {
    "enabled": true,
    "mode": "blur",
    "range": "face",
    "shape": "ellipse",
    "strength": 30
  }
}

multipart

-F 'face={"enabled":true,"mode":"pixel","range":"eyes","strength":80}'

range 决定盖脸的哪一块。半脸、眼、嘴按 YuNet 五点（右眼 / 左眼 / 鼻尖 / 右嘴角 / 左嘴角）算。点不够时退回整张脸 face。

range	盖哪里
`face`	整张脸椭圆或矩形。子客户端缺省用这个
`halfleft` / `halfright`	按眼到嘴的中线切本人左 / 右半脸，不是画面左右
`eyes`	双眼一条，会跟眼线倾斜
`eyeleft` / `eyeright`	本人左眼 / 本人右眼，加号罩。也认 `左眼` / `右眼` / `left_eye` / `right_eye`
`eyesmouth`	眼睛一条 + 嘴一条
`tface`	T 形：眉 + 双眼 + 鼻梁 + 嘴。网页旧打码默认这个

shape：ellipse 椭圆，rect 矩形。眼 / 嘴条会跟两点连线倾斜。margin 0~40，按脸框外扩百分比。网页默认 23，子客户端缺省 0。

T 形眼鼻嘴 + 矩形（网页旧打码默认范围）

{
  "face": {
    "enabled": true,
    "mode": "mask",
    "range": "tface",
    "shape": "rect",
    "margin": 23
  }
}

只盖本人左眼

{
  "face": {
    "enabled": true,
    "mode": "blur",
    "range": "eyeleft",
    "shape": "ellipse"
  }
}

只有 cutleft / sketchcut 才读 origin 和 offset。其它 mode 写了也没用。名字叫「抠到左边」，贴不下时会改贴右边。

YuNet 检出脸，按 range 画出罩子。
把罩内像素拷出来。sketchcut 会先把这块转成素描。
按 offset × 罩宽平移。先试左边；左边贴出画面再试右边。两边都不行就只留原位。
原位再按 origin 填：mask 纯色，sketch 素描。

mode	origin	原位	旁边那块
`cutleft`	`mask`	纯色	彩色原图像素
`cutleft`	`sketch`	素描	彩色原图像素
`sketchcut`	`mask`	纯色	先转素描再挪过去
`sketchcut`	`sketch`	素描	素描（两边都是素描）

offset 0.30~2.00，按抠图自身宽度往旁边挪。1.0 大约一个身位。网页默认 1.73，子客户端缺省 1.10。

网页默认：抠左 + T 形 + 原位纯色

{
  "prompt": "雨后街道，暖色店灯",
  "model": "minimaxH3",
  "image_url": "https://example.com/ref.jpg",
  "face": {
    "enabled": true,
    "mode": "cutleft",
    "range": "tface",
    "shape": "rect",
    "origin": "mask",
    "strength": 100,
    "margin": 23,
    "confidence": 0.75,
    "offset": 1.73
  }
}

原位素描，旁边仍是彩色

{
  "face": {
    "enabled": true,
    "mode": "cutleft",
    "range": "face",
    "shape": "ellipse",
    "origin": "sketch",
    "offset": 1.1
  }
}

挪过去的块先转素描，原位纯色

{
  "face": {
    "enabled": true,
    "mode": "sketchcut",
    "range": "tface",
    "origin": "mask",
    "offset": 1.1
  }
}

两边都是素描

{
  "face": {
    "enabled": true,
    "mode": "sketchcut",
    "range": "face",
    "shape": "ellipse",
    "origin": "sketch",
    "offset": 1.1
  }
}

字段	网页旧打码	只写 face:true 时	说明
`enabled`	`true`	`true`	`false` 才跳过。不写但带了其它旧字段，仍过脸
`mode`	`cutleft`	`blur`	覆盖方式
`range`	`tface`	`face`	盖哪一块
`shape`	`rect`	`ellipse`	`ellipse` / `rect`
`origin`	`mask`	`mask`	只对抠图档
`strength`	`100`	`30`	1~100
`margin`	`23`	`0`	0~40
`confidence`	`0.75`	`0.45`	YuNet 下限 0.20~0.90
`offset`	`1.73`	`1.10`	只对抠图档 0.30~2.00

别名

对象也可写 faceAnonymize / faceParams / 人脸。扁平：faceEnabled faceMode faceRange faceShape faceOrigin faceStrength faceMargin faceScore / faceConfidence faceOffset。两边都写时嵌套 face 优先。根上的普通 mode / range / offset 不当过脸读。

enabled 也认 开 / 1 / "true"；关认 关 / 0 / "off"。

扁平字段

{
  "prompt": "雨后街道，暖色店灯",
  "image_url": "https://example.com/ref.jpg",
  "faceMode": "pixel",
  "faceRange": "eyes",
  "faceStrength": 80
}

视频只打参考图

{
  "prompt": "人物转头微笑",
  "model": "minimaxH3",
  "function_mode": "first_last_frames",
  "first_frame_url": "https://example.com/first.jpg",
  "face": {
    "enabled": true,
    "mode": "cutleft",
    "range": "tface",
    "origin": "mask",
    "offset": 1.73
  }
}

查询

任务

提交之后用这里取结果。cgt- 前缀和 UUID 都可以查。成功 / 失败记录大约保留 3 天。

GET `/v1/tasks/{taskId}`

建议 3 到 5 秒一次。不要在 success 之前读 result_urls。

字段	说明
`task_id`	任务 ID
`status`	`pending` / `submitted` / `generating` / `post_processing` / `finalizing` / `success` / `failed`
`model` / `task_type`	模型；`image` / `video` / `lip_sync`
`progress_pct` / `progress_text`	0~100；进度文案
`result_urls`	仅 `success`
`fail_reason`	仅 `failed`，用户可读中文
`created_at`	ISO 8601

常见 fail_reason

文案	说明
内容审核未通过，请修改后重试	提示词或素材审核
参考图含未认证人脸，暂不支持生成。请换其它参考图，或改用文生视频。	`FACE_REJECTED`，有中文原文时原样返回
生成的视频内容存在风险，请修改提示词后重试	结果安全过滤
素材上传失败，请重试	素材上传出错
生成时间过长，任务已结束，费用已退回，请重新提交	约 3.5 小时未出结果，已退费
服务繁忙，请稍后重试	负载高

请求

GET /v1/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890
Authorization: Bearer your-api-key

成功

{
  "task_id": "a1b2c3d4-...",
  "status": "success",
  "model": "minimaxH3",
  "task_type": "image",
  "progress_pct": 100,
  "progress_text": "生成完成",
  "result_urls": ["https://cdn.example.com/result/image_001.png"],
  "created_at": "2026-04-01T12:00:00.000Z"
}

GET `/v1/tasks`

列出当前 Key 下的任务，按创建时间倒序。

参数	说明
`type` 或 `task_type`	`image` / `video` / `lip_sync`。不写则全部

请求

GET /v1/tasks
GET /v1/tasks?type=video
Authorization: Bearer your-api-key

响应

{
  "total": 2,
  "tasks": [
    {
      "task_id": "a1b2c3d4-...",
      "status": "success",
      "task_type": "image",
      "prompt": "雨后街道",
      "labels": ["1:1", "2k"],
      "result_urls": ["https://cdn.example.com/a.png"],
      "created_at": "2026-04-01T12:00:00.000Z"
    }
  ]
}

查询

账户

积分、流水、充值、模型。定价以广场页和 GET /v1/channels 为准。

GET `/v1/balance`

{
  "balance": 1500,
  "frozen": 200,
  "total_recharged": 5000,
  "total_consumed": 3300,
  "created_at": "2026-03-15T08:00:00.000Z"
}

GET `/v1/transactions`

参数	默认	说明
`page`	`1`	页码
`page_size`	`20`	最大 100
`type`	全部	`confirm` 扣费 / `recharge` 充值 / `rollback` 退款 / `pre_deduct` 预扣

{
  "transactions": [{
    "id": 123,
    "type": "confirm",
    "amount": -200,
    "balance_after": 1300,
    "model": "minimaxH3",
    "task_type": "video",
    "task_id": "a1b2c3d4-...",
    "created_at": "2026-04-02T12:00:00.000Z"
  }],
  "total": 56,
  "page": 1,
  "page_size": 20
}

POST `/v1/recharge`

JSON {"card_code":"XXXX-XXXX-XXXX"}。每分钟最多 5 次，连续错误 10 次封 30 分钟。响应 balance、recharged_amount。

GET `/v1/models`

线上实时配置。看 data[].id 和 caps，不要抄过期表格。兼容 GET /api/v3/models。

caps	怎么读
`dur`	`{"min":4,"max":30}` = 4 到 30 任意整数秒；`[5,10]` = 只能这两档
`res`	视频 `720p`；图片 `1k` / `2k` / `4k`
`ratios`	请求写 `ratio`
`modes`	`first_last_frames` / `multi_frame` / `omni_reference`
`maxRef`	图片最多参考张数
`materials`	`maxImg` / `maxVid` / `maxAudio`

打开本页后加载当前 Key 可见的模型。

GET `/v1/channels`

已启用渠道和定价，只读。请求里 channel 不写则走默认渠道。

兼容

方舟格式

给已经按火山方舟对接的项目。本站页面不用这套。数字人请走通用格式。

	方舟	本站通用
视频	`POST /api/v3/contents/generations/tasks` JSON `content`	`POST /v1/videos/generations` `prompt`
图片	`/api/v3/images/generations` 或 `/v1/images/generations`	同左，multipart 或 JSON
查询	`GET /api/v3/contents/generations/tasks/{id}` 或 `?filter.task_ids=`	`GET /v1/tasks/{id}`
任务 ID	`cgt-UUID`，字段 `id`	UUID，字段 `task_id`
状态	`queued` / `running` / `succeeded` / `failed`	`pending` 到 `success` / `failed`
时间	Unix 秒	ISO 8601
视频 HTTP	`200`	`202`
取消	`DELETE /api/v3/contents/generations/tasks/{id}`（当前返回不支持）	无

两种 ID 现已兼容互相查询。过脸放 JSON 根上，不要塞进 content。

方舟提交成功（HTTP 200）

{
  "id": "cgt-a1b2c3d4-...",
  "model": "minimaxH3",
  "status": "queued",
  "created_at": 1711929600
}

POST `/api/v3/contents/generations/tasks`

JSON。可以用 content 数组，也可以扁平写 prompt + image_urls。

content 项

项	说明
`type: "text"`	`text` 可嵌 `--ratio` `--dur` `--fps` `--res` `--mode`。顶级 `ratio` / `duration` / `resolution` 优先
`type: "image_url"`	`role`：`first_frame` / `start`、`last_frame` / `end`、`frame`、`material`。省略当首帧
`type: "video_url"`	`role` 必须是 `material`，否则忽略
`type: "audio_url"`	自动当素材，不需要 `role`

三种模式怎么组 content

模式	怎么写
首尾帧	图片 `role: first_frame` / `last_frame`。也可扁平 `image_urls` 第 1 张首帧、第 2 张尾帧（最多 2 张）
多帧	至少 2 张图片 `role: frame`，或 `--mode multi_frame`
全能引用	图片 / 视频 `role: material`，音频直接 `audio_url`。prompt 用 `@name`。扁平时有视频 / 音频，或图片 ≥ 3 张，会自动进全能引用，命名 `Image1` / `Video1` / `Audio1`

扁平字段还认 aspect_ratio（= ratio）、resolution / quality。

首尾帧 content

{
  "model": "minimaxH3",
  "content": [
    { "type": "text", "text": "猫咪奔跑 --ratio 16:9 --dur 8" },
    { "type": "image_url", "image_url": "https://example.com/first.jpg", "role": "first_frame" },
    { "type": "image_url", "image_url": "https://example.com/last.jpg", "role": "last_frame" }
  ],
  "face": { "enabled": true, "mode": "light" }
}

全能引用 content

{
  "model": "minimaxH3",
  "content": [
    { "type": "text", "text": "@角色A 在咖啡馆微笑 --mode omni_reference" },
    {
      "type": "image_url",
      "image_url": { "url": "https://example.com/charA.jpg" },
      "role": "material",
      "name": "角色A"
    }
  ]
}

扁平 image_urls（首帧）

{
  "model": "minimaxH3",
  "prompt": "猫咪在草地上奔跑",
  "aspect_ratio": "9:16",
  "duration": 15,
  "resolution": "720p",
  "image_urls": ["https://example.com/first.jpg"]
}

GET `/api/v3/contents/generations/tasks/{id}`

也可用 GET /v1/tasks/{id}。未找到单条时 404，{"error":{"message":"任务不存在","type":"not_found"}}。

批量

GET /api/v3/contents/generations/tasks?filter.task_ids=cgt-...,cgt-...，也可写 task_ids。page_num 默认 1，page_size 默认 100。

成功

{
  "id": "cgt-a1b2c3d4-...",
  "model": "minimaxH3",
  "status": "succeeded",
  "content": { "video_url": "https://cdn.example.com/result/video_001.mp4" },
  "created_at": 1711929600
}

Image, video, avatar

Open the bench

调用约定

鉴权

写请求时记住

错误码

POST /v1/images/generations

参数

在文生图参数之外再加

在文生图参数之外再加

POST /v1/videos/generations

共用参数

不写 function_mode 时怎么判

首尾帧

本模式参数

文件还是 URL

多帧

本模式参数

怎么凑满 2 帧

全能引用

本页共用字段

POST /v1/videos/lip-sync

参数

各步现状

submit 参数

过脸

请求会落到哪一档

别名

任务

GET /v1/tasks/{taskId}

常见 fail_reason

GET /v1/tasks

账户

GET /v1/balance

GET /v1/transactions

POST /v1/recharge

GET /v1/models

GET /v1/channels

方舟格式

POST /api/v3/contents/generations/tasks

content 项

三种模式怎么组 content

GET /api/v3/contents/generations/tasks/{id}

批量

Model plaza

Channels and billing

Prices by channel

Activity

POST `/v1/images/generations`

POST `/v1/videos/generations`

POST `/v1/videos/lip-sync`

GET `/v1/tasks/{taskId}`

GET `/v1/tasks`

GET `/v1/balance`

GET `/v1/transactions`

POST `/v1/recharge`

GET `/v1/models`

GET `/v1/channels`

POST `/api/v3/contents/generations/tasks`

GET `/api/v3/contents/generations/tasks/{id}`