comfyui
星渡开放平台文档
星渡 AutoDL ComfyUI 适配 API
本文档描述星渡对外提供的 7 个 H3 AutoDL public workflow 兼容接口。接口采用异步任务模式：先提交 workflow，再使用任务 ID 查询状态与结果。IndexTTS2 仅保留上游参数参考，当前未在星渡启用。
示例中的
YOUR_XINDU_API_KEY、任务 ID 和媒体 URL 均为占位值，不是真实凭据或生产资源。
1. 接入信息
- API origin：
https://xindu.xyz - 鉴权：
Authorization: Bearer YOUR_XINDU_API_KEY - 分组限制：API Key 必须绑定 H3 开放分组——group 51「国模全覆盖」或 group 120「H3视频专用」（一倍率）；其他分组不会开放这些 workflow
- 请求与响应：JSON
- 提交：
POST /v1/comfyui/comfyui_workflow/{workflow_id} - 查询：
GET /v1/comfyui/comfyui_workflow/result/{task_id}
请求体直接使用对应 workflow 的平铺字段，不要再包一层 input、parameters 或 workflow。
2. 异步调用流程
2.1 提交任务
curl -X POST \
'https://xindu.xyz/v1/comfyui/comfyui_workflow/minimax_h3_image_audio_to_video_v2_15s' \
-H 'Authorization: Bearer YOUR_XINDU_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"prompt": "电影感城市夜景，镜头缓慢推进",
"duration": 8,
"resolution": "768p竖",
"seed": 20260822,
"ref_image_0": "https://example.com/assets/first.webp",
"ref_audio_0": "https://example.com/assets/voice.mp3"
}'成功响应：
{
"code": "Success",
"data": {
"task_id": "task_example_01",
"status": "QUEUED",
"results": []
},
"msg": "success",
"request_id": "req_example_01"
}保存 data.task_id。request_id 用于排障，不可替代任务 ID。
2.2 查询状态
curl \
'https://xindu.xyz/v1/comfyui/comfyui_workflow/result/task_example_01' \
-H 'Authorization: Bearer YOUR_XINDU_API_KEY'任务状态保持 AutoDL 兼容值：
| 状态 | 含义 | 调用方行为 |
|---|---|---|
QUEUED | 已进入队列 | 继续轮询 |
RUNNING | 生成中 | 继续轮询 |
SUCCESS | 已完成 | 读取 data.results |
COMPLETED | 已完成（兼容状态） | 与 SUCCESS 相同，读取 data.results |
FAILED | 任务失败 | 停止轮询，记录 msg 与 request_id |
成功结果示例：
{
"code": "Success",
"data": {
"task_id": "task_example_01",
"status": "SUCCESS",
"results": [
{
"url": "https://example-result.invalid/temporary/output.mp4",
"type": "video",
"file_type": "mp4",
"output_type": "video"
}
]
},
"msg": "success",
"request_id": "req_example_02"
}2.3 下载结果
data.results[].url 是短期有效地址。任务成功后应立即下载并保存到自己的持久存储，不要把结果 URL 当作长期文件地址。下载结果时仍应检查 HTTP 状态、Content-Type 和文件大小。
3. 通用字段
3.1 seed
支持 seed 的 workflow 接受整数 1..999999999999999。不传时由 workflow 生成随机种子；不同 workflow 的随机默认值可能不同，调用方不应依赖固定默认 seed。
3.2 媒体 URL
- 图片：JPG、PNG、WebP
- H3 音频参考：MP3、WAV、MP4、FLAC
- IndexTTS2 音频参考：MP3、WAV
媒体字段必须是绝对 HTTP(S) URL，最长 4096 字符，不得携带 URL userinfo（如 user:password@host）或控制字符。URL 必须在任务执行期间可由服务端访问；需要鉴权、只在本地可见或过早失效的地址可能导致任务失败。
3.3 分辨率精确值
横竖值使用无括号字符串：
480p竖、480p横768p竖、768p横1080p竖、1080p横
方形值使用：
480p(1:1)、768p(1:1)、1080p(1:1)
每个 workflow 只接受下文列出的子集。
4. Workflow 一览
| workflow_id | 主要输入 | 时长 | 分辨率 | 参考媒体上限 |
|---|---|---|---|---|
minimax_h3_image_audio_to_video_v2_15s | 文本、图片、音频 | 1–15 秒 | 480p/768p 横竖 | 9 图、3 音频 |
minimax_h3_lightx2v_v5_15s | 文本、图片 | 1–15 秒 | 480p/768p 横竖与 1:1 | 9 图，至少 1 图 |
minimax_h3_image_audio_to_video_v2 | 文本、图片、音频 | 1–10 秒 | 480p/768p/1080p 横竖 | 9 图、3 音频 |
minimax_h3_image_audio_to_video | 图片、音频 | 1–15 秒 | 480p/768p/1080p 横竖 | 固定 1 图、1 音频 |
minimax_h3_lightx2v_v5 | 文本、图片 | 1–10 秒 | 480p/768p/1080p 横竖与 1:1 | 9 图，至少 1 图 |
minimax_h3_lightx2v_no_pic | 纯文本 | 1–15 秒 | 480p/768p 横竖 | 无 |
minimax_h3_lightx2v | 文本、首尾帧 | 1–15 秒 | 480p/768p 横竖 | 首帧、尾帧各 1 |
indextts2-v1 不在上表的星渡可调用 workflow 中；其上游参数仅在第 6 节作为参考保留。
5. H3 Workflow 参数
5.1 minimax_h3_image_audio_to_video_v2_15s
| 字段 | 必填 | 约束 |
|---|---|---|
prompt | 是 | 字符串，1–10000 字符 |
seed | 否 | 整数，1–999999999999999 |
duration | 否 | 整数，1–15，默认 5 |
resolution | 否 | 480p竖、480p横、768p竖、768p横；默认 768p竖 |
ref_image_0 … ref_image_8 | 否 | 图片 URL，最多 9 个 |
ref_audio_0 … ref_audio_2 | 否 | 音频 URL，最多 3 个 |
5.2 minimax_h3_lightx2v_v5_15s
| 字段 | 必填 | 约束 |
|---|---|---|
prompt | 是 | 字符串，1–500000 字符 |
seed | 否 | 整数，1–999999999999999 |
duration | 否 | 整数，1–15，默认 5 |
resolution | 否 | 480p/768p 横竖及 480p(1:1)、768p(1:1)；默认 768p竖 |
ref_image_0 | 是 | 图片 URL |
ref_image_1 … ref_image_8 | 否 | 图片 URL，连同 0 最多 9 个 |
5.3 minimax_h3_image_audio_to_video_v2
字段与 minimax_h3_image_audio_to_video_v2_15s 相同，但：
duration为 1–10 秒，默认 5；resolution另支持1080p竖、1080p横。
5.4 minimax_h3_image_audio_to_video
| 字段 | 必填 | 约束 |
|---|---|---|
audio_duration | 否 | 整数，1–15，默认 5 |
resolution | 否 | 480p/768p/1080p 横竖；默认 768p竖 |
ref_image_0 | 是 | 图片 URL，只接受 1 张 |
ref_audio_0 | 是 | 音频 URL，只接受 1 个 |
此 workflow 没有 prompt 字段；不要发送空 prompt 代替音频或图片。
5.5 minimax_h3_lightx2v_v5
| 字段 | 必填 | 约束 |
|---|---|---|
prompt | 是 | 字符串，1–500000 字符 |
seed | 否 | 整数，1–999999999999999 |
duration | 否 | 整数，1–10，默认 5 |
resolution | 否 | 480p/768p/1080p 横竖及三档 1:1；默认 768p竖 |
ref_image_0 | 是 | 图片 URL |
ref_image_1 … ref_image_8 | 否 | 图片 URL，连同 0 最多 9 个 |
5.6 minimax_h3_lightx2v_no_pic
| 字段 | 必填 | 约束 |
|---|---|---|
prompt | 是 | 字符串，1–200000 字符 |
duration | 否 | 整数，1–15，默认 5 |
resolution | 否 | 480p/768p 横竖；默认 768p竖 |
5.7 minimax_h3_lightx2v
| 字段 | 必填 | 约束 |
|---|---|---|
prompt | 是 | 字符串，1–2000000 字符 |
duration | 否 | 整数，1–15，默认 5 |
resolution | 否 | 480p/768p 横竖；默认 768p竖 |
first_frame | 是 | 首帧图片 URL |
last_frame | 是 | 尾帧图片 URL |
6. AutoDL 参考：IndexTTS2（星渡未启用）
indextts2-v1 是 AutoDL 上游参考 workflow，当前未在星渡启用，也不在星渡 OpenAPI 的可调用 workflow_id 枚举中。以下参数表仅用于理解上游格式，不能据此向星渡接口提交任务。
| 字段 | 必填 | 约束 |
|---|---|---|
prompt_simple | 是 | 音色参考音频 URL，MP3 或 WAV |
prompt_text | 是 | 待合成文本，1–2048 字符 |
emo_control_method | 是 | 固定为 与音色参考音频相同 |
emo_ref_audio | 否 | 情绪参考音频 URL，MP3 或 WAV |
emo_happy | 否 | 数值，0–1.4 |
emo_angry | 否 | 数值，0–1.4 |
emo_sad | 否 | 数值，0–1.4 |
emo_afraid | 否 | 数值，0–1.4 |
emo_disgusted | 否 | 数值，0–1.4 |
emo_melancholic | 否 | 数值，0–1.4 |
emo_calm | 否 | 数值，0–1.4 |
emo_surprised | 否 | 字符串，唯一允许值 0 |
emo_random | 否 | 布尔值 |
7. 计费
H3 视频 workflow 使用站内固定 CNY 单价，不乘分组倍率或用户倍率：
| 分辨率档 | 单价 |
|---|---|
480p，包括 480p竖、480p横、480p(1:1) | ¥0.12/秒 |
768p，包括 768p竖、768p横、768p(1:1) | ¥0.12/秒 |
1080p，包括 1080p竖、1080p横、1080p(1:1) | ¥0.12/秒 |
H3 价格按请求中的 duration 或 audio_duration 秒数及分辨率档计算。2026-09-12 起全档统一 ¥0.12/秒。例如 8 秒 768p竖 的参考金额为 8 × ¥0.12 = ¥0.96。
IndexTTS2 上游当前参考价为 ¥0.01/次，但该 workflow 本次未在星渡启用，不构成星渡可调用能力或站内报价。
8. Python 示例
import os
import time
from pathlib import Path
import requests
BASE_URL = "https://xindu.xyz"
API_KEY = os.environ["XINDU_API_KEY"]
WORKFLOW_ID = "minimax_h3_lightx2v_no_pic"
headers = {
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
}
submit = requests.post(
f"{BASE_URL}/v1/comfyui/comfyui_workflow/{WORKFLOW_ID}",
headers=headers,
json={
"prompt": "雨后的未来城市，霓虹倒影，固定镜头",
"duration": 5,
"resolution": "768p横",
},
timeout=30,
)
submit.raise_for_status()
submit_body = submit.json()
if submit_body.get("code") != "Success":
raise RuntimeError(submit_body)
task_id = submit_body["data"]["task_id"]
while True:
response = requests.get(
f"{BASE_URL}/v1/comfyui/comfyui_workflow/result/{task_id}",
headers={"Authorization": f"Bearer {API_KEY}"},
timeout=30,
)
if response.status_code == 429:
time.sleep(5)
continue
response.raise_for_status()
body = response.json()
if body.get("code") != "Success":
raise RuntimeError(body)
status = body["data"]["status"]
if status == "FAILED":
raise RuntimeError(body.get("msg") or body)
if status in ("SUCCESS", "COMPLETED"):
break
time.sleep(3)
for index, result in enumerate(body["data"].get("results", []), start=1):
download = requests.get(result["url"], timeout=120)
download.raise_for_status()
suffix = result.get("file_type") or "bin"
Path(f"result-{index}.{suffix}").write_bytes(download.content)生产代码应设置总轮询截止时间、指数退避或服务端建议的重试间隔，并持久化 task_id，避免调用进程重启后遗失任务。
9. 错误处理
错误响应仍包含 code、msg 和可用于排障的 request_id；data 可能为空。不要只判断 HTTP 200，也要判断 code 和任务 status。
9.1 提交任务不可盲目重试
POST 提交发生网络错误、超时、EOF、HTTP 502 或 503 时，任务可能已经被 AutoDL 接受。此时自动重放可能生成重复任务并重复计费；不要仅因没有收到成功响应就盲目重试。
如果响应 code 为 SubmissionUnknown，保存 data.task_id，不要重新提交，并携带 task_id 与 request_id 联系支持或核对上游任务记录。如果错误响应没有任务 ID，也应先核对请求日志或联系支持再决定是否重新提交。GET 状态查询是只读操作，可以在 429、502 或 503 后退避重试。
| HTTP | 场景 | 建议 |
|---|---|---|
| 400 | workflow 字段、类型、长度、媒体格式或枚举无效 | 修正请求，不要原样重试 |
| 401 | 缺少或无效 API Key | 检查 Authorization，不要打印完整 Key |
| 403 | Key 无权使用分组、workflow 或相关能力 | 更换有权限的 Key 或联系管理员 |
| 404 | workflow 或 task_id 不存在 | 检查路径和任务 ID |
| 409 | 任务状态或请求与现有任务冲突 | 查询原任务状态后再决定是否提交 |
| 429 | 请求频率、并发或队列受限 | 退避后重试，并限制客户端并发 |
| 502 | AutoDL/ComfyUI 上游返回无效响应或网关失败 | POST 不可盲目重试；GET 可有限次数退避重试 |
| 503 | 服务、计费、任务绑定或上游暂不可用 | POST 按上文核对结果；GET 可稍后重试 |
提交结果未知示例：
{
"code": "SubmissionUnknown",
"data": {
"task_id": "task_example_unknown",
"status": "SUBMISSION_UNKNOWN"
},
"msg": "upstream accepted the task but local ownership binding could not be persisted; retain task_id and contact support",
"request_id": "req_example_unknown"
}失败示例：
{
"code": "InvalidRequest",
"data": null,
"msg": "resolution is not supported by this workflow",
"request_id": "req_example_error"
}10. OpenAPI
机器可读契约见 AUTODL_COMFYUI_OPENAPI.yaml。OpenAPI 中的 workflow ID、字段约束、状态、结果和错误响应与本文档保持一致。