MX工作站

Start

How to call

This site uses the common format: submit, get a task_id, then poll. Do not send Ark content arrays to /v1/videos/generations.

Send Authorization: Bearer <Key> or X-API-Key. A bare key without Bearer also works.
Image, video, avatar, and batch face wash return HTTP 202 and a task_id. There is no result URL in that response.
Poll GET /v1/tasks/{task_id} every 3–5 seconds. Read the two links only after status=success: result_urls (preview / play) and source_urls (HD save, may be empty).
To save a file, prefer GET /v1/tasks/{id}/download?index= or /file/{name}?index=. Both return the same bytes and pick HD first. Do not treat the preview URL as the HD file.

Auth

Method	Header	Value
Bearer	`Authorization`	`Bearer your-api-key`
X-API-Key	`X-API-Key`	`your-api-key`

When you write a request

model is the id from GET /v1/models. Use that list and caps. UI chips (5s / 10s) are a shortcut, not an API limit.
The website sends face.mode=light on generate jobs. If the API omits face, the still is uploaded as-is. That is not Light wash. For old mosaic, send an old mode. To skip wash, send face.enabled=false.
Common video fields are ratio, video_resolution, first_frame_url. Ark-only fields are size / aspect_ratio / content / flat image_urls.
Both cgt-... and UUID work on /v1/tasks/{id}.
channel is the name from GET /v1/channels, not the label. Omit it to use the default channel (default, shown as 低价). Lumen is channel=lumen, and the model must be in that channel’s models.

Status codes

HTTP	Meaning
`400`	Bad params, or the channel is missing / closed
`401`	Key invalid, expired, or disabled
`402`	Not enough credits
`429`	Rate limit. Default 60/min. Too many running jobs returns `"code":"GENERATING_LIMIT"`
`500`	Internal error
`503`	Busy, retry later

Submit + poll

import requests, time

API = "__SITE_API__"
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"], t.get("source_urls")); break
    if t["status"] == "failed":
        print(t.get("fail_reason")); break

Error body

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

Channel

Channel and models

`name`	Label	Status	Models you can send
`default`	低价
`lumen`	lumen
`official`	官方（即梦）

低价

curl -X POST "__SITE_API__/v1/videos/generations" \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "minimaxH3",
    "channel": "default",
    "prompt": "镜头缓缓前推",
    "ratio": "16:9",
    "duration": 5
  }'

lumen

curl -X POST "__SITE_API__/v1/videos/generations" \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "SD2.0MINI503",
    "channel": "lumen",
    "prompt": "镜头缓缓前推",
    "ratio": "16:9",
    "duration": 5
  }'

Generate

POST `/v1/images/generations`

Text-to-image or image-to-image. Multipart or JSON. Success is HTTP 202 with a task_id. /api/v3/images/generations takes the same fields.

不传参考图就是文生图。不传任何人脸参数，或 face 为空对象，由服务器内部默认处理。这不是不过脸。浅洗要显式写 face.mode=light。网页「服务器默认」不传这些字段，也不做预览。

Fields

参数	类型	必填	默认	说明
`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` 的 `name`，如 `default`、`lumen`。不写走 `is_default` 的渠道。图片不要写死 `official`
`face`	object / JSON	否	网页浅洗	字段见「过脸」

multipart

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

JSON

{
  "prompt": "雨后街道，暖色店灯，50mm",
      "model": "minimaxH3",
  "channel": "default",
  "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）。

Add these on top of text-to-image

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

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

文件

curl -X POST "__SITE_API__/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 字符串和数组都认。

Add these on top of text-to-image

参数	类型	必填	说明
`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 "__SITE_API__/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 "__SITE_API__/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"
  ]
}

Generate

POST `/v1/videos/generations`

Common format. Use prompt. Do not send Ark content arrays. Multipart or JSON. Success is HTTP 202. Keep the three modes separate; do not mix their fields.

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

Shared fields

参数	类型	必填	默认	说明
`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`	`480p` / `720p` / `1080p` / `2k` / `4k`（大小写都行，`2160p` 等同 `4k`），具体看该模型 `caps.res`。本接口不认 `resolution` 别名
`function_mode`	string	否	自动	`first_last_frames` / `multi_frame` / `omni_reference`
`channel`	string	否	默认渠道	填 `name`，如 `default`、`lumen`。不写走默认渠道。模型必须在该渠道的 `models` 里
`face`	object / JSON	否	网页浅洗	只处理本单里的参考图片

If function_mode is omitted

你传了什么	判定
`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

First / last frame

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

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

Fields for this mode

参数	类型	必填	说明
`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",
  "channel": "default",
  "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 "__SITE_API__/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 "__SITE_API__/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，没有就不要走这一页。

Fields for this mode

参数	类型	必填	说明
`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 "__SITE_API__/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 "__SITE_API__/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

Omni mix

Mix stills, clips, and audio. Every @name in the prompt must match a material. The four samples below are complete requests.

参数	说明
`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 "__SITE_API__/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 "__SITE_API__/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 "__SITE_API__/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 "__SITE_API__/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" }
}

Generate

POST `/v1/videos/lip-sync`

A face still plus audio, one lip-sync pass. Avatar has no face wash. face_index only picks which face. Use auto mode.

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

Fields

参数	类型	必填	说明
`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	否	填 `name`，如 `default`、`lumen`。不写走默认渠道

文件

curl -X POST "__SITE_API__/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 "channel=default" \
  -F "prompt=室内采访，正面中景"

URL

curl -X POST "__SITE_API__/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"
}

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

Current steps

接口	现状
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 fields

参数	类型	必填	说明
`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	否	填 `name`，如 `default`、`lumen`。不写走默认渠道

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

submit（带文件）

curl -X POST "__SITE_API__/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"
}

Generate

Face wash

Whether a still is washed, and which grade, is only the face object on that job. The website sends mode:light on generate. If the API omits face, the original still is uploaded. Avatar face_index is not a wash.

Website default on generate. You must send mode: "light". Omitting face skips wash. face: true is the old mosaic, not Light.

	内容
下发	`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"}'

Whole-frame tint / light sketch. You must send mode. Do not send only 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"}'

Original in and out. Omitting face and sending enabled: false do the same.

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

JSON

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

multipart

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

Put face on the JSON root. Do not nest it in Ark content. Avatar has no wash.

接口	怎么传
`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`
`POST /v1/images/process`	独立过脸。按张计费。不传 `face` 由服务器内部默认处理

请求会落到哪一档

请求	行为
不传 `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" }
}

The child runs YuNet, then covers range with mode. Light / Heavy ignore these fields. The website Old form sends the full set. The API will not fill defaults if you only send 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 "__SITE_API__/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
  }
}

Batch face wash

POST /v1/images/process is a billed face job: one task, up to 30 stills, charged per image. Generate-side wash stays a free sidecar.

Send stills as multipart images (repeat the field) or image_file_1…image_file_30, or as image_url / image_urls. No prompt. Need a child-reported, priced face model.

One request = one task = N stills. Cost = unit price × N. Cap 30. Single file ≤ 20MB.
If a still has no face or wash fails, that still stays original and is still billed.
Poll GET /v1/tasks/{id}. Download one file with GET /v1/tasks/{id}/download?index= or /file/{name}?index=. Pack all files with GET /v1/tasks/{id}/zip.
Default wash is on. Send face for Light / Heavy / old mosaic. enabled: false is rejected.

Download

One file: GET /v1/tasks/{id}/download?index=0
All files as a zip: GET /v1/tasks/{id}/zip

Field	Type
`model`	string	Required. A priced `face` model id
`channel`	string	Optional. `name` from `GET /v1/channels`, such as `default` or `lumen`. Omit it to use the default channel.
`images`	file[]	Repeat. Up to 30
`image_file_N`	file	N = 1…30
`image_url` / `image_urls`	string / array	HTTP stills
`face`	object / JSON	Optional. Default on

multipart

curl -X POST "$API/v1/images/process" \
  -H "Authorization: Bearer your-api-key" \
  -F "model=your-face-model" \
  -F "face={\"enabled\":true,\"mode\":\"light\"}" \
  -F "images=@a.jpg" \
  -F "images=@b.jpg"

JSON

{
  "model": "your-face-model",
  "image_urls": [
    "https://example.com/a.jpg",
    "https://example.com/b.jpg"
  ],
  "face": { "enabled": true, "mode": "light" }
}

zip

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

Query

Tasks

After submit, poll here for results. Both cgt- ids and UUIDs work. Success / fail rows are kept about 3 days.

GET `/v1/tasks/{taskId}`

Poll every 3–5 seconds. Do not read the two result links before success. How to save the file is on the Download tab.

Field	Notes
`task_id`	Task id
`status`	`pending` / `submitted` / `generating` / `post_processing` / `finalizing` / `success` / `failed`
`model` / `task_type`	Model id; `image` / `video` / `lip_sync` / `face`
`progress_pct` / `progress_text`	0–100 and a short status line
`result_urls`	Only on `success`. Preview / play. Not the HD file when `source_urls` is present.
`source_urls`	Only on `success`. HD original for save. Empty array means there is no separate HD link.
`fail_reason`	Only on `failed`. User-facing text
`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/play.mp4"],
  "source_urls": ["https://cdn.example.com/origin.mp4?download=true"],
  "created_at": "2026-04-01T12:00:00.000Z"
}

GET `/v1/tasks`

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

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

请求

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/play.mp4"],
      "source_urls": ["https://cdn.example.com/origin.mp4?download=true"],
      "created_at": "2026-04-01T12:00:00.000Z"
    }
  ]
}

Two result links

On success the poll body has two URL lists. They are not the same file. Show the preview. Save the HD original.

Do not read either list before status=success. Do not save result_urls[0] when source_urls has an item.

Field	Use
`result_urls`	Preview / play. Put this in a player or `<img>`. It may be a transcoded or watermarked stream.
`source_urls`	HD original for save-to-disk. Often ends with `?download=true`. Empty array = no separate HD; then the preview is the file.

Two download endpoints

Same bytes. Key required. index picks the Nth output (0-based). {name} is only a filename hint in the path; it does not pick a different file.

GET /v1/tasks/{task_id}/download?index=0
GET /v1/tasks/{task_id}/file/{name}?index=0

These endpoints pick in this order: a local HD file the child uploaded (kept 6 hours) → source_urls[index] → result_urls[index]. Response is the file bytes with Content-Disposition: attachment. Header X-Download-Source is hd / preview / local.

Several outputs: GET /v1/tasks/{task_id}/zip.

CDN links in the poll body may expire or block hotlink. Prefer the two endpoints above when saving.

HTTP	Meaning
`401`	Missing or invalid Key
`404`	No such task, or not this Key
`409`	Not ready, or no file left to save
`410`	Local file expired
`502`	Upstream download failed

Poll body: two links

{
  "status": "success",
  "result_urls": ["https://cdn.example.com/play.mp4"],
  "source_urls": ["https://cdn.example.com/origin.mp4?download=true"]
}

Save one file

GET /v1/tasks/a1b2c3d4-.../download?index=0
Authorization: Bearer your-api-key

GET /v1/tasks/a1b2c3d4-.../file/result.mp4?index=0
Authorization: Bearer your-api-key

curl

curl -L "$API/v1/tasks/$TASK_ID/download?index=0" \
  -H "Authorization: Bearer your-api-key" \
  -o result.mp4

curl -L "$API/v1/tasks/$TASK_ID/file/result.mp4?index=0" \
  -H "Authorization: Bearer your-api-key" \
  -o result.mp4

curl -L "$API/v1/tasks/$TASK_ID/zip" \
  -H "Authorization: Bearer your-api-key" \
  -o result.zip

Query

Account

Credits, ledger, top-up, models. Prices follow the plaza and 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 次封兑换。响应 balance、recharged_amount。

GET `/v1/recharge/products`

在售面值。响应 products[].face_yuan、credits、in_stock。

POST `/v1/recharge/orders`

店铺下单。JSON {"face_yuan":50,"pay":"wechat"}。来源按请求 Origin 记：官方站是无代理，已登记的二级站记到该代理。响应 pay_url，前端打开后轮询下面这条。

GET `/v1/recharge/orders/:id`

查自己的充值单并尝试到账。状态 pending / paid / credited / expired / failed。

GET `/v1/recharge/agent/orders`

代理对账。用后台绑给该站的 Key。查询 page、page_size、status、from、to（日期）。不返回卡密和查单密码。

GET `/v1/support/agent/threads`

代理客服会话。同一把 Key。主站用户走右下角主站客服；代理站用户按 Origin 进该站队列。回复 POST /v1/support/agent/threads/:id/messages。

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`

已启用的公开渠道、各自的模型和定价。创建图片、视频、对口型、过脸时，用这里的 name 作为请求字段 channel。页面上的「低价」是显示名，请求里要写 default。

字段	怎么用
`name`	请求里 `channel` 的值。当前公开渠道是 `default`（显示名「低价」）和 `lumen`
`display_name`	给人看的名字，不能拿来当 `channel`
`is_default`	为 `true` 的那条是默认渠道。请求不写 `channel` 就走它，现在是 `default`
`models`	这个渠道能调的模型 id，按 `image` / `video` / `lip_sync` / `face` 分开。上面的模型表不按渠道拆，换渠道前先看这里

同一个模型名不能跨渠道照搬。低价上的 minimaxH3 不在 lumen 里；lumen 当前视频模型是 SD2.0MINI503、SD2.0FAST803、SD2.0FAST813。渠道没有这个模型时返回 400：该渠道不支持模型。下面的响应只示范 name 和 models，完整列表以接口实时返回为准。

{
  "channels": [
    {
      "name": "default",
      "display_name": "低价",
      "is_default": true,
      "models": { "video": ["minimaxH3"] }
    },
    {
      "name": "lumen",
      "display_name": "lumen",
      "is_default": false,
      "models": { "video": ["SD2.0MINI503", "SD2.0FAST803", "SD2.0FAST813"] }
    }
  ]
}

调用示例在「调用约定」。

Compat

Ark format

For projects already wired to Volcengine Ark. This website does not use that format. Avatar stays on the common API.

	方舟	本站通用
视频	`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
}

Open the bench

选择充值金额

支付方式

扫码支付

充值订单

How to call

Auth

When you write a request

Status codes

Channel

Channel and models

POST /v1/images/generations

Fields

Add these on top of text-to-image

Add these on top of text-to-image

POST /v1/videos/generations

Shared fields

If function_mode is omitted

First / last frame

Fields for this mode

文件还是 URL

多帧

Fields for this mode

怎么凑满 2 帧

Omni mix

本页共用字段

POST /v1/videos/lip-sync

Fields

Current steps

submit fields

Face wash

请求会落到哪一档

别名

Batch face wash

Download

Tasks

GET /v1/tasks/{taskId}

常见 fail_reason

GET /v1/tasks

Two result links

Two download endpoints

Account

GET /v1/balance

GET /v1/transactions

POST /v1/recharge

GET /v1/recharge/products

POST /v1/recharge/orders

GET /v1/recharge/orders/:id

GET /v1/recharge/agent/orders

GET /v1/support/agent/threads

GET /v1/models

GET /v1/channels

Ark format

POST /api/v3/contents/generations/tasks

content 项

三种模式怎么组 content

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

批量

Model plaza

Channels and billing

Prices by channel

Activity

Agent CS

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/recharge/products`

POST `/v1/recharge/orders`

GET `/v1/recharge/orders/:id`

GET `/v1/recharge/agent/orders`

GET `/v1/support/agent/threads`

GET `/v1/models`

GET `/v1/channels`

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

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