ComfyUI 多工作流 API

服务地址

• 公网文档首页：https://mov.upapi.cn/

• 在线接口文档：https://mov.upapi.cn/api.md

• 原始 Markdown：https://mov.upapi.cn/api.raw.md 网关只允许调用已注册的工作流，不接受调用方提交任意 ComfyUI 工作流。支持：

• Z-Image-Turbo Full BF16 文生图与中英文文字渲染

• Krea 2 Turbo FP8 + Krea2 Beauty v2.0 LoRA 审美文生图

• LongCat-Image BF16 文生图，中英文文字渲染与写实摄影

• Qwen-Image 2.1 INT8 文生图，中英文文字渲染，原生 2K 输出

• Qwen-Image 2.1 编辑版：按指令改图，最多 10 张参考图

• ERNIE-Image 标准版（50 步）与 Turbo（8 步，约 4 秒）文生图，可选提示词增强

• FLUX.2 Edit：使用最多 4 张参考图进行图像编辑

• Qwen3-TTS 1.7B 本地语音生成、音色设计与声音克隆

• MiniMax Music 3 FP16 本地纯音乐 BGM 与完整歌曲生成，最长 5 分钟

• Wan2.2 Animate / Wan Animate 2 动作迁移：参考图 + 驱动视频，让角色复现动作与表情

• 文生视频与原生立体声音频

• 首帧、尾帧或首尾帧控制

• Omni Reference：最多 9 张参考图、3 个参考视频、3 个独立参考音频

• 参考视频配套音轨或视频内嵌音轨

• 带签名的公开成果网页和文件直链

身份认证

除 /health、/api.md、/v1/crypto/public-key 和带签名的成果地址外，所有接口均需 API Key：

Authorization: Bearer <API_KEY>

或：

X-API-Key: <API_KEY>

API Key 由服务提供方单独分发，本文档不包含真实密钥。

创建任务成功后会额外返回仅属于该任务的 job_token。查询任务状态或通过鉴权接口下载文件时，必须同时提交 API Key 和该任务的 job_token：

X-Job-Token: <JOB_TOKEN>

job_token 只在创建响应中返回一次，不会在后续状态响应中回显。不同任务的令牌不能互用。

健康检查

curl https://mov.upapi.cn/health

{
  "status": "ok",
  "comfyui": true,
  "workflow_ready": true,
  "qwen3_tts": {
    "service": true,
    "node_ready": true,
    "ready": true,
    "dtype": "bfloat16",
    "attention": "sdpa",
    "models": {
      "preset_voice": true,
      "voice_design": true,
      "voice_clone": true
    }
  },
  "minimax_music3": {
    "node_ready": true,
    "models_ready": true,
    "ready": true,
    "model_precision": "fp16",
    "maximum_duration_seconds": 300
  }
}

查询接口结构

查询已经注册的工作流：

curl https://mov.upapi.cn/v1/workflows \
  -H "X-API-Key: <API_KEY>"

{
  "default_workflow": "minimax-h3",
  "workflows": [
    {
      "name": "minimax-h3",
      "display_name": "MiniMax H3 多模态视频",
      "adapter": "minimax_h3",
      "schema_url": "/v1/workflows/minimax-h3/schema"
    },
    {
      "name": "minimax-h3-realism-people",
      "display_name": "MiniMax H3 Realism People",
      "adapter": "minimax_h3",
      "schema_url": "/v1/workflows/minimax-h3-realism-people/schema"
    },
    {
      "name": "flux2-edit",
      "display_name": "FLUX.2 Edit",
      "adapter": "flux2_edit",
      "schema_url": "/v1/workflows/flux2-edit/schema"
    },
    {
      "name": "krea2-beautiful",
      "display_name": "Krea 2 Beautiful v2.0",
      "adapter": "krea2",
      "schema_url": "/v1/workflows/krea2-beautiful/schema"
    },
    {
      "name": "z-image-turbo-full",
      "display_name": "Z-Image-Turbo Full BF16",
      "adapter": "z_image_turbo",
      "schema_url": "/v1/workflows/z-image-turbo-full/schema"
    },
    {
      "name": "longcat-image",
      "display_name": "LongCat-Image BF16",
      "adapter": "longcat_image",
      "schema_url": "/v1/workflows/longcat-image/schema"
    },
    {
      "name": "qwen-image-2.1",
      "display_name": "Qwen-Image 2.1",
      "adapter": "qwen_image_21",
      "schema_url": "/v1/workflows/qwen-image-2.1/schema"
    },
    {
      "name": "qwen-image-2.1-edit",
      "display_name": "Qwen-Image 2.1 Edit",
      "adapter": "qwen_image_21_edit",
      "schema_url": "/v1/workflows/qwen-image-2.1-edit/schema"
    },
    {
      "name": "ernie-image",
      "display_name": "ERNIE-Image",
      "adapter": "ernie_image",
      "schema_url": "/v1/workflows/ernie-image/schema"
    },
    {
      "name": "ernie-image-turbo",
      "display_name": "ERNIE-Image Turbo",
      "adapter": "ernie_image",
      "schema_url": "/v1/workflows/ernie-image-turbo/schema"
    },
    {
      "name": "qwen3-tts-1.7b",
      "display_name": "Qwen3-TTS Local 1.7B",
      "adapter": "qwen3_tts",
      "schema_url": "/v1/workflows/qwen3-tts-1.7b/schema"
    },
    {
      "name": "minimax-music3",
      "display_name": "MiniMax Music 3 BGM",
      "adapter": "minimax_music3",
      "schema_url": "/v1/workflows/minimax-music3/schema"
    },
    {
      "name": "wan2.2-animate",
      "display_name": "Wan2.2 Animate",
      "adapter": "wan22_animate",
      "schema_url": "/v1/workflows/wan2.2-animate/schema"
    },
    {
      "name": "wan-animate-2",
      "display_name": "Wan Animate 2",
      "adapter": "wan_animate2",
      "schema_url": "/v1/workflows/wan-animate-2/schema"
    }
  ]
}

查询指定工作流结构：

curl https://mov.upapi.cn/v1/workflows/minimax-h3/schema \
  -H "X-API-Key: <API_KEY>"

兼容接口 /v1/schema 返回默认工作流结构；也可以指定名称：

curl "https://mov.upapi.cn/v1/schema?workflow=minimax-h3" \
  -H "X-API-Key: <API_KEY>"

动作迁移工作流 wan2.2-animate 与 wan-animate-2 的素材、参数和示例见下文「Wan 动作迁移」一节。

上传参考素材

POST /v1/assets?u={user_namespace}&kind={image|video|audio}&filename={文件名}
Content-Type: application/octet-stream
X-API-Key: <API_KEY>

<原始文件字节>

上传图片：

curl -X POST \
  "https://mov.upapi.cn/v1/assets?kind=image&filename=character.png" \
  -H "X-API-Key: <API_KEY>" \
  -H "Content-Type: image/png" \
  --data-binary "@character.png"

上传视频：

curl -X POST \
  "https://mov.upapi.cn/v1/assets?kind=video&filename=motion.mp4" \
  -H "X-API-Key: <API_KEY>" \
  -H "Content-Type: video/mp4" \
  --data-binary "@motion.mp4"

上传音频：

curl -X POST \
  "https://mov.upapi.cn/v1/assets?kind=audio&filename=voice.wav" \
  -H "X-API-Key: <API_KEY>" \
  -H "Content-Type: audio/wav" \
  --data-binary "@voice.wav"

响应中的 asset_id 用于创建任务：

{
  "asset_id": "comfy-api-assets/96972a52da114732a8667bb2d6ec62ce.png",
  "kind": "image",
  "filename": "character.png",
  "size": 238015
}

单文件最大 512 MiB。支持格式：

• 图片：PNG、JPG、JPEG、WebP、BMP
• 视频：MP4、MOV、WebM、MKV、AVI
• 音频：WAV、MP3、FLAC、OGG、M4A、AAC

创建任务

POST /v1/jobs
Content-Type: application/json
X-API-Key: <API_KEY>

创建任务接口只接受加密信封，不接受明文任务 JSON。工作流名、user_namespace、user_task_id、parameters、inputs 和其中的提示词会作为一个完整 JSON 一起加密：

• 内容加密：AES-256-GCM
• 密钥封装：RSA-3072 / OAEP-SHA256 / MGF1-SHA256
• 附加认证数据：comfy-api:v1:jobs
• 防重放：客户端时间与服务器时间相差不能超过 5 分钟，同一个随机数只能使用一次

这一层可以让普通 HTTP 抓包看不到任务参数，但 API Key 仍位于请求头中，而且 HTTP 页面和公钥可能被主动篡改。需要抵御主动中间人、保护 API Key 和素材文件时，仍必须使用 HTTPS；服务端集成也建议预先核对并固定 kid。

先取得当前 RSA 公钥：

GET /v1/crypto/public-key

返回 kid、public_key_pem、算法名称和时间窗口。公钥可以缓存；如果创建任务返回 HTTP 409，应重新获取公钥并重新加密。实际发送到 /v1/jobs 的请求体格式如下，所有二进制字段均采用无填充 Base64URL：

{
  "version": 1,
  "alg": "RSA-OAEP-256",
  "enc": "A256GCM",
  "kid": "公钥标识",
  "encrypted_key": "RSA 加密后的 32 字节 AES 密钥",
  "iv": "12 字节随机 IV",
  "ciphertext": "AES-GCM 密文与 16 字节认证标签"
}

加密前的任务对象由 parameters 和 inputs 两部分组成。下文展示的任务 JSON 均为“加密前对象”，不能直接作为 /v1/jobs 的 HTTP 请求体发送。

顶层 workflow 用于选择已注册工作流；省略时使用 minimax-h3。user_namespace 用作上传和输出文件的隔离目录；user_task_id 是调用方自己的任务编号，用于跨系统关联：

{
  "workflow": "minimax-h3",
  "user_namespace": "customer_001",
  "user_task_id": "order-20260814-0001",
  "parameters": {},
  "inputs": {}
}

user_task_id 可选，类型为字符串，长度 1–128 个字符，不能包含控制字符。网关不会修改该值；创建响应、状态查询、完成/失败结果及成果网页都会原样返回。省略时返回 null。

user_namespace 可选，省略时为 api。只允许 1–64 位小写英文字母、数字、下划线和连字符，并且必须以字母或数字开头。上传素材时的查询参数 u 必须与加密任务对象中的 user_namespace 一致；生成结果将保存到该命名空间的子目录。

parameters

minimax-h3-realism-people 使用 fal/MiniMax-H3-Realism-People-LoRA。网关会自动在提示词前加入触发词 r34l1sm；如果提示词已包含该词则不会重复。官方目标强度为 1.0，需要更轻效果时可使用 0.6–0.8。

画面比例：

1:1 (Square)
2:3 (Portrait Photo)
3:2 (Photo)
3:4 (Portrait Standard)
4:3 (Standard)
9:16 (Portrait Widescreen)
16:9 (Widescreen)
21:9 (Ultrawide)

inputs

首尾帧模式不能与 Omni Reference 素材混用。只传 first_frame、last_frame 时自动进入首尾帧模式；传任一 reference_* 数组时自动进入 Omni Reference 模式。

Realism People 人物写实工作流

该工作流支持与 minimax-h3 相同的文生视频、首尾帧和 Omni Reference 输入，只需切换工作流名称，并可选传入 LoRA 强度：

{
  "workflow": "minimax-h3-realism-people",
  "user_task_id": "people-video-0001",
  "parameters": {
    "prompt": "A cinematic close-up of a real person walking through a city street",
    "lora_strength": 1.0,
    "duration": 5,
    "aspect_ratio": "16:9 (Widescreen)",
    "megapixels": 0.4,
    "steps": 20
  },
  "inputs": {}
}

在 Omni Reference 提示词中使用以下标签指代素材：

<Picture 1>、<Picture 2> ...
<Video 1>、<Video 2> ...
<Audio 1>、<Audio 2> ...

文生视频

{
  "workflow": "minimax-h3",
  "user_task_id": "order-20260814-0001",
  "parameters": {
    "prompt": "雨后的未来城市，电影摄影，车辆快速驶过，原生环境音",
    "seed": 123456,
    "duration": 5,
    "aspect_ratio": "16:9 (Widescreen)",
    "megapixels": 0.4,
    "steps": 20,
    "sampler": "res_multistep"
  }
}

首尾帧视频

{
  "workflow": "minimax-h3",
  "parameters": {
    "prompt": "The character turns toward the camera while the city lights come alive.",
    "duration": 5,
    "aspect_ratio": "16:9 (Widescreen)",
    "megapixels": 0.4
  },
  "inputs": {
    "first_frame": "comfy-api-assets/FIRST_IMAGE.png",
    "last_frame": "comfy-api-assets/LAST_IMAGE.png"
  }
}

多参考图与声音参考

{
  "workflow": "minimax-h3",
  "parameters": {
    "prompt": "Keep the identity and clothing of <Picture 1>. Use the environment style from <Picture 2>. The protagonist speaks in the voice and delivery of <Audio 1>: This shot is simply amazing!",
    "seed": 123456,
    "duration": 5,
    "aspect_ratio": "16:9 (Widescreen)",
    "megapixels": 0.4,
    "steps": 20
  },
  "inputs": {
    "reference_images": [
      "comfy-api-assets/CHARACTER.png",
      "comfy-api-assets/ENVIRONMENT.png"
    ],
    "reference_audios": [
      "comfy-api-assets/VOICE.wav"
    ],
    "reference_image_size": "match"
  }
}

参考视频与配套音轨

{
  "workflow": "minimax-h3",
  "parameters": {
    "prompt": "Follow the motion and camera rhythm of <Video 1>, while using its associated <Audio 1> as the voice and timing reference.",
    "duration": 5,
    "aspect_ratio": "16:9 (Widescreen)",
    "megapixels": 0.4
  },
  "inputs": {
    "reference_videos": [
      "comfy-api-assets/MOTION.mp4"
    ],
    "reference_video_audios": [
      "comfy-api-assets/MOTION_VOICE.wav"
    ]
  }
}

如果要直接使用视频内嵌音轨：

{
  "inputs": {
    "reference_videos": ["comfy-api-assets/MOTION.mp4"],
    "use_embedded_video_audio": true
  }
}

Python 整包加密并创建任务

安装依赖：pip install requests cryptography。request_body 可以替换为本节任一工作流示例：

import base64
import json
import os
import time

import requests
from cryptography.hazmat.primitives import hashes, serialization
from cryptography.hazmat.primitives.asymmetric import padding
from cryptography.hazmat.primitives.ciphers.aead import AESGCM

BASE_URL = "https://mov.upapi.cn"
API_KEY = os.environ["COMFY_API_KEY"]
AAD = b"comfy-api:v1:jobs"


def b64url(value: bytes) -> str:
    return base64.urlsafe_b64encode(value).decode("ascii").rstrip("=")


def encrypt_request(request_body: dict) -> dict:
    metadata = requests.get(f"{BASE_URL}/v1/crypto/public-key", timeout=15).json()
    public_key = serialization.load_pem_public_key(metadata["public_key_pem"].encode("ascii"))
    aes_key = os.urandom(32)
    iv = os.urandom(12)
    protected = {
        "issued_at": int(time.time() * 1000),
        "nonce": b64url(os.urandom(18)),
        "request": request_body,
    }
    plaintext = json.dumps(protected, ensure_ascii=False, separators=(",", ":")).encode("utf-8")
    ciphertext = AESGCM(aes_key).encrypt(iv, plaintext, AAD)
    encrypted_key = public_key.encrypt(
        aes_key,
        padding.OAEP(
            mgf=padding.MGF1(algorithm=hashes.SHA256()),
            algorithm=hashes.SHA256(),
            label=None,
        ),
    )
    return {
        "version": 1,
        "alg": "RSA-OAEP-256",
        "enc": "A256GCM",
        "kid": metadata["kid"],
        "encrypted_key": b64url(encrypted_key),
        "iv": b64url(iv),
        "ciphertext": b64url(ciphertext),
    }


request_body = {
    "workflow": "minimax-h3",
    "user_task_id": "order-20260814-0001",
    "parameters": {
        "prompt": "雨后的未来城市，电影摄影，车辆快速驶过，原生环境音",
        "duration": 5,
        "aspect_ratio": "16:9 (Widescreen)",
        "megapixels": 0.4,
        "steps": 20,
    },
    "inputs": {},
}

response = requests.post(
    f"{BASE_URL}/v1/jobs",
    headers={"X-API-Key": API_KEY},
    json=encrypt_request(request_body),
    timeout=30,
)
response.raise_for_status()
print(response.json())

响应：

{
  "id": "ae736d94-f406-4812-b599-af553eb349d6",
  "user_task_id": "order-20260814-0001",
  "workflow": "minimax-h3",
  "status": "queued",
  "job_token": "<JOB_TOKEN>",
  "elapsed_seconds": 0.0,
  "mode": "omni_reference",
  "status_url": "/v1/jobs/ae736d94-f406-4812-b599-af553eb349d6",
  "result_page_url": "https://mov.upapi.cn/results/ae736d94-f406-4812-b599-af553eb349d6?sig=..."
}

mode 可能为 text、first_last_frame、omni_reference、text_to_image 或 image_edit。

请在收到创建响应后立即安全保存 job_token；令牌遗失后无法通过状态接口取回。

FLUX.2 Edit 图像编辑

工作流名称：flux2-edit。底层保留 FLUX.2 Klein 9B FP8 权重，但普通 flux2 文生图工作流未注册、不会出现在接口目录中。先上传一至四张参考图片，再将素材 ID 放入 inputs.reference_image 或 inputs.reference_images。

{
  "workflow": "flux2-edit",
  "user_task_id": "edit-0001",
  "parameters": {
    "prompt": "Change the background to a snowy mountain landscape while preserving the person",
    "seed": 12345,
    "steps": 4,
    "cfg": 1.0,
    "sampler": "euler",
    "megapixels": 1.0,
    "upscale_method": "nearest-exact"
  },
  "inputs": {
    "reference_image": "comfy-api-assets/返回的素材文件名.png"
  }
}

inputs.reference_image 与 inputs.reference_images 二选一；后者最多 4 张。创建响应中的 mode 为 image_edit。实时结构：

GET /v1/workflows/flux2-edit/schema

Krea 2 Beautiful v2.0 文生图

工作流名称：krea2-beautiful。使用 Krea 2 Turbo FP8、Qwen3-VL 4B FP8 文本编码器、Qwen Image VAE，并默认加载 Krea2 Beauty v2.0 LoRA。建议使用自然语言完整描述场景，默认 8 步、CFG 1、Euler 采样和 Simple 调度。

{
  "workflow": "krea2-beautiful",
  "user_task_id": "krea2-0001",
  "parameters": {
    "prompt": "A natural-light editorial portrait of a woman standing beside a large window. Her expression is relaxed, with realistic skin texture and subtle imperfections. Warm afternoon light shapes her face and clothing. The background is softly layered and cinematic.",
    "seed": 20260828,
    "width": 1024,
    "height": 1024,
    "steps": 8,
    "cfg": 1.0,
    "sampler": "euler",
    "scheduler": "simple",
    "lora_strength": 1.0
  },
  "inputs": {}
}

lora_strength 支持 0–2.0，默认 1.0；设为 0 可临时关闭 Beauty LoRA。创建响应中的 mode 为 text_to_image。实时结构：

GET /v1/workflows/krea2-beautiful/schema

Z-Image-Turbo Full 文生图

工作流名称：z-image-turbo-full。使用完整 BF16 的 Z-Image-Turbo 主模型、Qwen 3 4B BF16 文本编码器和原版 VAE。官方推荐默认值为 8 步、CFG 1、res_multistep 采样器、simple 调度器和 Shift 3。

{
  "workflow": "z-image-turbo-full",
  "user_task_id": "z-image-0001",
  "parameters": {
    "prompt": "一张电影感产品摄影，桌上放着一杯咖啡，背景招牌清晰写着‘早上好’，自然晨光",
    "seed": 20260814,
    "width": 1024,
    "height": 1024,
    "steps": 8,
    "cfg": 1.0,
    "sampler": "res_multistep",
    "scheduler": "simple",
    "shift": 3.0
  },
  "inputs": {}
}

参数：

实时参数结构：

GET /v1/workflows/z-image-turbo-full/schema

创建任务仍使用 POST /v1/jobs；创建响应中的 mode 为 text_to_image，状态查询、耗时、GPU 数据、任务隔离和成果链接与其他工作流一致。

LongCat-Image 文生图

工作流名称：longcat-image。使用美团 LongCat-Image 6B 的完整 BF16 主模型、Qwen2.5-VL 7B FP8 文本编码器和 FLUX VAE。擅长中文与英文文字渲染（招牌、海报、包装）和写实摄影。官方推荐默认值为 20 步、CFG 4、Guidance 4、euler 采样器、simple 调度器；这是非蒸馏模型，CFG 生效，因此支持 negative_prompt。

需要画面中出现指定文字时，把文字用引号写进提示词：

{
  "workflow": "longcat-image",
  "user_task_id": "longcat-0001",
  "parameters": {
    "prompt": "一家街角咖啡店的门头摄影，木质招牌上清晰写着“早安咖啡”四个大字，下方一行小字“GOOD MORNING COFFEE”，玻璃门上贴着一张手写海报写着“今日特价 拿铁 18 元”，清晨柔和的自然光，真实摄影",
    "seed": 777,
    "width": 1024,
    "height": 1024,
    "steps": 20,
    "cfg": 4.0,
    "sampler": "euler",
    "scheduler": "simple"
  },
  "inputs": {}
}

参数：

参考耗时（RTX 5090，1024×1024、20 步）：首次含加载模型约 21 秒，之后约 9 秒。文字渲染偶尔会出现个别错字（实测一次把 GOOD 写成 GOOOD），换一个 seed 重新生成即可。

实时参数结构：

GET /v1/workflows/longcat-image/schema

创建响应中的 mode 为 text_to_image，其余与 Z-Image-Turbo 一致。

Qwen-Image 2.1 文生图

工作流名称：qwen-image-2.1。阿里 Qwen-Image 2.1，使用 INT8 主模型、Qwen3-VL 8B INT8 文本编码器和专用 VAE。中英文文字渲染准确，支持原生 2K 输出。官方推荐 25 步、CFG 1、euler 采样器、simple 调度器。

需要画面中出现指定文字时，把文字用引号写进提示词：

{
  "workflow": "qwen-image-2.1",
  "user_task_id": "qwen21-0001",
  "parameters": {
    "prompt": "一张书店橱窗的摄影，木质招牌上清晰写着“万卷书屋”，下方一行小字“TEN THOUSAND BOOKS”，玻璃上贴着手写海报“今日新书 七折”，午后斜射的自然光，真实摄影",
    "seed": 20260921,
    "width": 1024,
    "height": 1024,
    "steps": 25,
    "cfg": 1.0,
    "sampler": "euler",
    "scheduler": "simple"
  },
  "inputs": {}
}

参数：

参考耗时（RTX 5090，25 步）：1024×1024 约 5–8 秒；2048×2048 原生 2K 约 20 秒。2K 直出的招牌与海报文字依然清晰，适合需要大图的海报类场景。

实时参数结构：

GET /v1/workflows/qwen-image-2.1/schema

创建响应中的 mode 为 text_to_image，其余与 Z-Image-Turbo 一致。

Qwen-Image 2.1 编辑版（按指令改图）

工作流名称：qwen-image-2.1-edit。与 qwen-image-2.1 共用同一套模型，不需要额外下载。上传参考图后用自然语言描述要做的修改，最多 10 张参考图。

素材字段二选一：

• inputs.reference_image：单张图片素材 ID
• inputs.reference_images：图片素材 ID 数组，最多 10 张

提示词里用 <image1>、<image2> 指代第 1、2 张参考图，顺序与上传顺序一致。

单图修改：

{
  "workflow": "qwen-image-2.1-edit",
  "user_task_id": "qwen21-edit-0001",
  "parameters": {
    "prompt": "把 <image1> 中人物的紫色开衫换成亮红色的针织开衫，保持人物面容、姿势和背景完全不变",
    "seed": 20260921,
    "steps": 25,
    "cfg": 1.0
  },
  "inputs": {
    "reference_image": "comfy-api-assets/返回的素材文件名.png"
  }
}

多图合成：

{
  "workflow": "qwen-image-2.1-edit",
  "parameters": {
    "prompt": "把 <image1> 里的人物放到 <image2> 的书店橱窗前站着，保持她的相貌、发型和衣着不变，光线自然融合",
    "seed": 321
  },
  "inputs": {
    "reference_images": [
      "comfy-api-assets/人物.png",
      "comfy-api-assets/场景.png"
    ]
  }
}

参数：

参考耗时（RTX 5090，25 步，参考图约 1024×1024）：单张参考图约 4 秒，两张约 9 秒。参考图越多、越大，耗时越长。

实测效果：单图换装能保持人物面容、姿势和背景不变；双图合成能把人物放进另一张图的场景，并保留原场景招牌上的文字。写提示词时把要保留的内容明确列出来（例如“保持面容、姿势和背景不变”），效果更稳。

创建响应中的 mode 为 image_edit；完成后 files[].kind 为 image。

实时参数结构：

GET /v1/workflows/qwen-image-2.1-edit/schema

ERNIE-Image 文生图（标准版 / Turbo）

百度 ERNIE-Image 8B，擅长中英文文字渲染、海报和结构化版式。使用 Ministral 3 3B 文本编码器和 FLUX.2 VAE。提供两个工作流，参数名一致，可以只改 workflow 名称来切换：

步数可以自行指定。标准版 50 步是百度官方推荐值；实测 20 步画面已经干净，构图与 50 步基本一致，50 步在纹理和小物件上更精致。需要批量出图或快速预览时把 steps 设为 20，或直接用 Turbo。

{
  "workflow": "ernie-image",
  "user_task_id": "ernie-0001",
  "parameters": {
    "prompt": "一张奶茶店的新品海报，标题大字写着“桂花乌龙”，副标题“AUTUMN LIMITED”，右下角价格标签写着“¥16”，画面是一杯冒着热气的奶茶和飘落的桂花，暖色调，商业摄影",
    "seed": 11,
    "width": 1024,
    "height": 1024,
    "steps": 50,
    "cfg": 4.0,
    "enhance_prompt": false
  },
  "inputs": {}
}

Turbo 只需把 workflow 改为 ernie-image-turbo，并去掉 steps、cfg（或设为 8 和 1.0）。

参数：

提示词增强（enhance_prompt: true）：先用官方的 ERNIE-Image Prompt Enhancer 语言模型，把简短描述连同目标分辨率扩写成一大段详细的画面描述，再交给生图模型。适合“雨夜的霓虹街道，一个撑伞的女孩”这类一句话提示词。代价是每次多花约 25 秒，并且增强会改写语义（实测把“猫在书店里看书”扩写成了“猫凝视书架上的书”）。需要严格控制画面，或提示词里已经用引号指定了要渲染的文字时，保持关闭。关闭时不会加载该语言模型。

Turbo 偶尔会在画面里添加提示词中没有的零星文字（实测一次在杯身多出一行小字），换 seed 或改用标准版即可。

实时参数结构：

GET /v1/workflows/ernie-image/schema
GET /v1/workflows/ernie-image-turbo/schema

创建响应中的 mode 为 text_to_image，其余与 Z-Image-Turbo 一致。

Qwen3-TTS 本地声音生成

工作流名称：qwen3-tts-1.7b。三个官方 1.7B 模型均在本机运行，使用 BF16 与 PyTorch SDPA；不调用外部语音生成服务。支持中文、英文、日语、韩语、德语、法语、俄语、葡萄牙语、西班牙语和意大利语。

可查询音色、语言、模式和模型就绪状态：

GET /v1/audio/voices
X-API-Key: <API_KEY>

预设音色

{
  "workflow": "qwen3-tts-1.7b",
  "user_task_id": "audio-20260821-001",
  "parameters": {
    "mode": "preset_voice",
    "text": "欢迎使用本地 Qwen3-TTS 声音接口。",
    "language": "Chinese",
    "speaker": "Vivian",
    "instruct": "自然、清晰、语速适中",
    "reference_text": "",
    "x_vector_only": false,
    "seed": 42,
    "max_new_tokens": 2048,
    "temperature": 0.9,
    "top_p": 0.9,
    "repetition_penalty": 1.05,
    "unload_after_generate": true
  },
  "inputs": {}
}

预设音色包括 Vivian、Serena、Uncle_Fu、Dylan、Eric、Ryan、Aiden、Ono_Anna 和 Sohee。

自然语言设计音色

将 mode 改为 voice_design，并用 instruct 详细描述声音：

{
  "workflow": "qwen3-tts-1.7b",
  "user_task_id": "audio-design-001",
  "parameters": {
    "mode": "voice_design",
    "text": "夜色缓缓落在安静的海面上。",
    "language": "Chinese",
    "speaker": "Vivian",
    "instruct": "温暖沉静的成年女性声音，低音区，纪录片旁白风格，语速稍慢",
    "reference_text": "",
    "x_vector_only": false,
    "seed": 42,
    "max_new_tokens": 2048,
    "temperature": 0.9,
    "top_p": 0.9,
    "repetition_penalty": 1.05,
    "unload_after_generate": true
  },
  "inputs": {}
}

参考音频克隆声音

先通过素材接口上传参考音频，再把返回的 asset_id 放入加密任务 JSON。建议参考音频为 5–15 秒，超过 30 秒的部分会被自动截断。

{
  "workflow": "qwen3-tts-1.7b",
  "user_task_id": "audio-clone-001",
  "parameters": {
    "mode": "voice_clone",
    "text": "这是使用参考声音生成的新内容。",
    "language": "Chinese",
    "speaker": "Vivian",
    "instruct": "",
    "reference_text": "这里填写参考音频中实际说出的原文。",
    "x_vector_only": false,
    "seed": 42,
    "max_new_tokens": 2048,
    "temperature": 0.9,
    "top_p": 0.9,
    "repetition_penalty": 1.05,
    "unload_after_generate": true
  },
  "inputs": {
    "reference_audio": "comfy-api-assets/返回的声音素材文件名.wav"
  }
}

x_vector_only=true 时可以不传 reference_text，但声音克隆质量通常会下降。unload_after_generate=true 会在任务结束后释放语音模型显存，适合与生图、生视频工作流共用显卡。

声音任务与其他工作流一样，完整任务 JSON 必须先按前文方式加密，再发送到 POST /v1/jobs。创建响应中的 mode 为 text_to_audio，完成后 files[].kind 为 audio，返回 MP3 预览、下载地址、总耗时和 GPU 状态。

实时参数结构：

GET /v1/workflows/qwen3-tts-1.7b/schema

MiniMax Music 3 本地 BGM 生成

工作流名称：minimax-music3。使用 FP16 扩散模型、裁剪 INT8 文本编码器和 MiniMax Music 3 音频 VAE，全部在本机 ComfyUI / RTX 5090 上运行。默认输出高质量 MP3，支持纯音乐 BGM 和带歌词的完整歌曲，最长时长为 300 秒。

纯音乐 BGM 示例。lyrics 使用 [Instrumental]，明确禁止主唱：

{
  "workflow": "minimax-music3",
  "user_namespace": "customer_001",
  "user_task_id": "bgm-20260826-001",
  "parameters": {
    "caption": "电影感氛围配乐，C 小调，72 BPM，温暖钢琴与弦乐，克制开场，中段逐渐推向明亮高潮，结尾柔和收束，纯音乐，无人声，宽广立体声混音。",
    "lyrics": "[Instrumental]",
    "seed": 42,
    "max_duration": 30,
    "ar_cfg_scale": 1.7,
    "top_k": 50,
    "steps": 30,
    "cfg": 1.7,
    "sampler": "euler",
    "scheduler": "simple"
  },
  "inputs": {}
}

生成歌曲时，在 caption 中描述流派、速度、调性、人声和编曲，并在 lyrics 中使用结构标签：

{
  "workflow": "minimax-music3",
  "user_task_id": "song-20260826-001",
  "parameters": {
    "caption": "温暖流行民谣，92 BPM，G 大调，成年女声，原声吉他、钢琴与轻柔鼓组，主歌克制，副歌明亮开阔。",
    "lyrics": "[Intro]\n\n[Verse]\n清晨的光落在窗边……\n\n[Chorus]\n我们向着远方……\n\n[Outro]",
    "seed": 128,
    "max_duration": 60,
    "steps": 30,
    "cfg": 1.7,
    "ar_cfg_scale": 1.7,
    "top_k": 50,
    "sampler": "euler",
    "scheduler": "simple"
  },
  "inputs": {}
}

参数说明：

任务对象必须按前文方式整包加密后发送到 POST /v1/jobs。创建响应中的 mode 为 text_to_music；完成后 files[].kind 为 audio，并返回播放/下载地址、总耗时与 GPU 状态。

实时参数结构：

GET /v1/workflows/minimax-music3/schema

Wan 动作迁移

用一张角色参考图和一段驱动视频，让参考图里的角色复现视频中的身体动作、手势和表情。提供两个工作流，素材字段完全相同，可以只改 workflow 名称来切换：

如何选择（基于同一组素材的实测）：

• 驱动视频里人物在画面中的位置或大小变化明显（例如从远处走向镜头）→ 用 wan2.2-animate。骨架携带画面内的绝对位置和尺度，输出会逐帧复现原视频的景别。
• 驱动视频景别基本稳定，且与参考图的人物景别接近（全身对全身、半身对半身）→ 用 wan-animate-2。口型和细微表情更准，画面更锐利，背景与镜头可由提示词控制。
• wan-animate-2 是相对参考图的构图来映射运动的：参考图是中近景、驱动视频人物却由小变大时，输出会被放大成特写甚至出画。

命名变更（2026-09-18）：此前文档中的 wan2.2-animate 实际指向 Wan Animate 2 模型。现已纠正：wan2.2-animate 指向真正的 Wan 2.2 Animate，原工作流更名为 wan-animate-2。两者参数不同，请以各自的 schema 为准。

素材（两个工作流相同，均为必填）：

• inputs.reference_image：图片素材 ID，决定角色外观。建议人物清晰、构图与驱动视频接近
• inputs.driving_video：视频素材 ID，提供动作与表情。旧字段名 pose_video 仍可作为别名使用，但两者不能同时提交

只使用驱动视频从起始帧开始的前 length 帧。驱动视频不足 length 帧时任务仍会完成：超出部分角色保持最后一个姿态，表情不再受驱动（已实测 55 帧素材生成 77 帧）。建议让驱动视频的可用帧数不少于 length。输出视频不包含驱动视频的音轨。

wan2.2-animate 对驱动视频的要求：画面中应为单人，且人脸全程可见。检测不到人物的帧不会产生人脸裁剪，人脸序列会因此比骨架序列短并在时间上错位。多人、长时间背对镜头或人物出画的素材建议改用 wan-animate-2。

Wan2.2 Animate

{
  "workflow": "wan2.2-animate",
  "user_namespace": "customer_001",
  "user_task_id": "animate-20260918-001",
  "parameters": {
    "prompt": "An elderly woman walking toward the camera in a rural courtyard, natural motion, realistic lighting",
    "seed": 42,
    "steps": 6,
    "cfg": 1.0,
    "width": 480,
    "height": 832,
    "length": 77
  },
  "inputs": {
    "reference_image": "comfy-api-assets/customer_001/返回的素材文件名.png",
    "driving_video": "comfy-api-assets/customer_001/返回的素材文件名.mp4"
  }
}

参考耗时（RTX 5090，480×832、77 帧、6 步）：含首次加载模型约 85 秒。

Wan Animate 2

{
  "workflow": "wan-animate-2",
  "user_task_id": "animate2-20260918-001",
  "parameters": {
    "prompt": "Character appearance description: An elderly woman with short curly grey hair, wearing a purple cardigan over a floral blouse and black trousers, full body.\nBackground description: A rural courtyard in front of an old mud-brick house, soft overcast daylight.",
    "motion_prompt": "A person standing still and talking to someone, small natural gestures, background stationary",
    "seed": 42,
    "steps": 6,
    "width": 480,
    "height": 832,
    "length": 81
  },
  "inputs": {
    "reference_image": "comfy-api-assets/返回的素材文件名.png",
    "driving_video": "comfy-api-assets/返回的素材文件名.mp4"
  }
}

Wan Animate 2 的输出背景和镜头由提示词生成，与参考图背景、驱动视频背景都解耦，因此提示词分两个：

• prompt：按 Character appearance description: … 换行 Background description: … 的格式，描述角色外观和想要的背景
• motion_prompt：只描述驱动视频里的动作，不描述角色，例如 A person doing energetic street dance, background stationary

参考耗时（RTX 5090，480×832、77 帧、6 步）：约 50–65 秒。

两个工作流的任务对象都必须按前文方式整包加密后发送到 POST /v1/jobs。创建响应中的 mode 为 video_generate；完成后 files[].kind 为 video。实时参数结构：

GET /v1/workflows/wan2.2-animate/schema
GET /v1/workflows/wan-animate-2/schema

查询任务

curl https://mov.upapi.cn/v1/jobs/{id} \
  -H "X-API-Key: <API_KEY>" \
  -H "X-Job-Token: <JOB_TOKEN>"

完成响应：

{
  "id": "ae736d94-f406-4812-b599-af553eb349d6",
  "user_task_id": "order-20260814-0001",
  "workflow": "minimax-h3",
  "status": "completed",
  "elapsed_seconds": 10.47,
  "gpu": {
    "available": true,
    "name": "NVIDIA GeForce RTX 5090",
    "utilization_percent": 100,
    "temperature_c": 79,
    "memory_used_mib": 26718,
    "memory_total_mib": 32607,
    "memory_used_percent": 81.9
  },
  "files": [
    {
      "kind": "video",
      "filename": "MiniMax_H3_00003_.mp4",
      "url": "/v1/jobs/ae736d94-f406-4812-b599-af553eb349d6/files/0",
      "public_url": "https://mov.upapi.cn/public/jobs/ae736d94-f406-4812-b599-af553eb349d6/files/0?sig=..."
    }
  ],
  "errors": [],
  "result_page_url": "https://mov.upapi.cn/results/ae736d94-f406-4812-b599-af553eb349d6?sig=..."
}

elapsed_seconds 为任务从提交到当前或完成时的耗时，单位为秒，保留最多三位小数。旧任务缺少可用时间数据时可能返回 null。

gpu 是查询状态时的实时显卡数据：

• utilization_percent：GPU 核心利用率，百分比
• temperature_c：GPU 温度，摄氏度
• memory_used_mib：已使用显存，MiB
• memory_total_mib：总显存，MiB
• memory_used_percent：显存占用比例，百分比

无法读取 NVIDIA 状态时返回 {"available": false}。GPU 数据最多缓存 1 秒。

成果 Web 服务

任务创建后立刻返回 result_page_url。该网页在任务运行时每 5 秒自动刷新，完成后显示耗时、播放器和下载链接。

• result_page_url：公开成果网页
• files[].public_url：公开文件直链
• files[].url：需要 API Key 和对应 job_token 的下载接口

带签名的成果链接不需要 API Key。任何获得链接的人都能访问对应成果，请勿公开敏感内容。

FaceFusion 换脸接口

FaceFusion 是独立任务接口，不走 ComfyUI /v1/jobs。创建任务仍然必须使用 RSA + AES 加密 envelope。

创建任务

POST /v1/facefusion/jobs
Content-Type: application/json
X-API-Key: <API_KEY>

加密前的请求 JSON（单人换脸）：

{
  "mode": "single",
  "user_namespace": "ranran",
  "user_task_id": "facefusion-001",
  "inputs": {
    "source_image": "comfy-api-assets/ranran/source.png",
    "target_asset": "comfy-api-assets/ranran/target.mp4",
    "target_kind": "video"
  },
  "parameters": {
    "processors": ["face_swapper"],
    "face_swapper_model": "hyperswap_1a_256",
    "output_video_quality": 80
  }
}

加密前的请求 JSON（男女双人换脸）：

{
  "mode": "gender_pair",
  "user_namespace": "ranran",
  "user_task_id": "facefusion-people-001",
  "inputs": {
    "male_source_image": "comfy-api-assets/ranran/male.png",
    "female_source_image": "comfy-api-assets/ranran/female.png",
    "target_asset": "comfy-api-assets/ranran/target.mp4",
    "target_kind": "video"
  },
  "parameters": {
    "processors": ["face_swapper"],
    "face_swapper_model": "hyperswap_1a_256",
    "output_video_quality": 80,
    "output_video_encoder": "h264_nvenc",
    "video_memory_strategy": "tolerant"
  }
}

男女双人模式会串行执行两步：先用 male_source_image 替换目标视频中的男性脸，再用 female_source_image 替换中间结果中的女性脸，最后输出一个文件。性别识别依赖 FaceFusion 检测结果，复杂画面可能存在漏换或错换。

可选增强：

{
  "processors": ["face_swapper", "face_enhancer", "frame_enhancer"],
  "face_enhancer_model": "gfpgan_1.4",
  "frame_enhancer_model": "real_esrgan_x2"
}

创建响应会返回 job_token。查询状态和下载结果都必须带 X-Job-Token，避免其他人看到不属于自己的任务。

curl https://mov.upapi.cn/v1/facefusion/jobs/{id} \
  -H "X-API-Key: <API_KEY>" \
  -H "X-Job-Token: <JOB_TOKEN>"

完成状态响应示例：

{
  "id": "8bc0d901-1b14-436a-abf3-34d782c2049c",
  "user_task_id": "facefusion-people-001",
  "user_namespace": "ranran",
  "status": "completed",
  "elapsed_seconds": 128.34,
  "message": "completed",
  "file": {
    "filename": "facefusion-8bc0d901-1b14-436a-abf3-34d782c2049c.mp4",
    "kind": "video",
    "size": 12345678,
    "url": "/v1/facefusion/jobs/8bc0d901-1b14-436a-abf3-34d782c2049c/file",
    "public_url": "/v1/gallery/files/...?u=ranran",
    "gallery_url": "/v1/gallery/files/...?u=ranran"
  }
}

file.url 是受保护接口，必须带 X-Job-Token，适合 API 客户端下载：

curl https://mov.upapi.cn/v1/facefusion/jobs/{id}/file \
  -H "X-API-Key: <API_KEY>" \
  -H "X-Job-Token: <JOB_TOKEN>" \
  -o facefusion-result.mp4

file.public_url / file.gallery_url 是网页预览和浏览器下载地址，m.html 会优先使用它们。

网页测试入口：

https://mov.upapi.cn/m.html?view=facefusion&u=<user>

MiniMax H3 LightX2V Turbo 8-Step 加速工作流

新增工作流名称：minimax-h3-lightx2v-turbo。

它与 minimax-h3 使用相同的 API 输入结构，支持：

• 文生视频
• 首帧 / 尾帧 / 首尾帧
• Omni Reference 图片、视频、音频参考
• 原生视频 + 音频输出

区别：该工作流内置 minimax_h3_fl2v_turbo_8step_v1.0_comfyui_bf16.safetensors LoRA，并使用 MiniMaxH3SigmaShift，默认参数为：

创建任务示例：

{
  "workflow": "minimax-h3-lightx2v-turbo",
  "user_namespace": "customer_001",
  "user_task_id": "turbo-video-0001",
  "parameters": {
    "prompt": "A cinematic live-action shot of a runner crossing a rainy futuristic rooftop, native city ambience and dramatic music.",
    "duration": 5,
    "aspect_ratio": "16:9 (Widescreen)",
    "megapixels": 0.4,
    "steps": 8
  },
  "inputs": {}
}

如果需要微调加速 LoRA，可传：

{
  "parameters": {
    "lora_strength": 1.0,
    "shift_video": 12,
    "shift_audio": 3
  }
}

HTTP 状态码

安全提示

1. 当前公网入口为 HTTP，生产使用建议在服务器前增加 HTTPS。
2. 不要把 API Key 写入公开网页或仓库。
3. 不要在不同用户之间共享 job_token；每个令牌只能访问对应任务。
4. 素材和成果可能包含隐私信息，应妥善保管 API Key、任务令牌与签名成果链接。