开放 API 接入文档三元巡狩・六神兽 视频生成平台

当前账号模型、参数与价格对照

登录主页后自动读取实时配置，仅列出当前可提交的子接口。新接入使用表内平台 model 标识；展示名称与平台模型 ID 一一对应，重命名后 ID 保持不变。旧版 workflow / provider 名称和编号选择继续兼容。上游模型 ID、接入地址及路由协议仅在管理后台维护，不对外返回。

正在读取接口目录…

刷新模型与价格

API 客户端可读取 GET /v1/workflows、GET /v1/image/providers，同样需要 Bearer API Key。价格根据该 Key 所属账号计算；请求可用 max_charge 设置本次费用上限。

1接口概览

Base URL：http://47.93.118.167:5000（统一经平台前端 5000 端口接入，API Key 鉴权；后端端口不对外，本地自建环境为 http://127.0.0.1:5000）

方法	路径	说明
GET	/v1/skills	获取 AI 改写技能列表（免费）
GET	/v1/workflows	获取视频工作流列表（免费）
POST	/v1/rewrite	提示词改写（DeepSeek，按 tokens 计费）
POST	/v1/enhance	提示词增强（MiniMax H3-Context-IR，按 tokens 计费；生成视频前强烈建议对接）
POST	/v1/generate	生成分镜图（图生图/文生图，按张计费）
POST	/v1/video/generate	保存原请求并预留额度，原任务可交付后结算
POST	/v1/video/check	查询任务状态；任务完成后返回下载地址
GET	/v1/video/file/{task_id}	下载视频文件（mp4）

2接入准备

1. 在平台网页端注册并登录账号；
2. 登录后点击页面左侧侧边栏 「🔑 集成 API」，在弹出的窗口中填写密钥名称（必填）并点击 「＋ 生成新 API Key」，得到形如 sk-xxxxxxxx 的密钥（窗口内会同时展示 Base URL 并支持一键复制）；
3. 点击右上角 「余额」 查看余额；如需充值请联系管理员开通（当前充值功能暂未开放）；
4. 将 API Key 妥善保存在调用端环境变量中，不要写死在代码里或提交到公开仓库。

3鉴权方式

所有接口均需在请求头携带 API Key，格式如下：

# 请求头示例
Authorization: Bearer sk-xxxxxxxxxxxxxxxx

鉴权失败统一返回 HTTP 401 与 {"ok": false, "error": "无效的 API Key"}。

4调用流程

5生成视频

请求参数

字段	必填	类型	说明
prompt	是	string	视频画面描述（提示词），需为自然语言描述，建议 20～200 字，越具体越好
workflow	否	string	指定工作流（子接口名，见 GET /v1/meta?type=workflows 返回的名称）；缺省使用后台「选中工作流」。传了不存在的名称会返回 400 不支持的子接口
duration	否	number	视频时长（秒），默认 5；不能超过该工作流时长上限（默认 15 秒），超出会返回 400
image_data_urls	否	array[string]	参考图列表（图生视频），每项为 data:image/...;base64,...，最多 9 张（首张为首帧）；不传则为文生视频
audio_data_urls	否	array[string]	参考音频列表，每项为 data:audio/...;base64,...，最多 3 段（第 i 段对应 ref_audio_i）
resolution	否	string	分辨率档位，默认 768p竖（720x1280 竖屏）。具体可选档位以网页端展示为准
seed	否	number	随机种子，≥0 的整数；固定种子可复现相同画面风格，默认随机
context_ir_enabled	否	boolean	是否自动启用 H3-Context-IR 提示词增强，默认 true；增强按 tokens 额外计费，余额不足时自动回退为原始提示词（不影响视频生成）

请求示例（curl）

# 文字生成视频（文生视频）
export API_KEY="sk-xxxxxxxxxxxxxxxx"

curl -sS -X POST http://47.93.118.167:5000/v1/video/generate \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "一只金红色的凤凰展开尾羽，从翻滚的云海上缓缓飞过，阳光洒在羽毛上闪闪发光，电影级画面，镜头缓慢跟随",
    "duration": 5
  }'

成功响应

HTTP 200
{
  "ok": true,
  "event_id": "fdc491b5-88fd-4266-b09a-29e5bf6713aa",  // 任务 ID，后续轮询/下载使用
  "cost": 0.2,                                          // 本次实际扣费（元）
  "balance": 7461.08,                                   // 扣费后账户余额（元）
  "free_video_used": false                              // 是否使用了新用户免费视频额度
}

返回字段	类型	说明
event_id	string	任务 ID（即 task_id），轮询与下载均使用它
cost	number	本次扣费（元）。任务失败仅退还其中视频费部分
balance	number	扣费后剩余余额
free_video_used	boolean	本次是否消耗新用户免费视频机会

6查询任务状态

字段	必填	类型	说明
event_id	是	string	生成接口返回的任务 ID

请求示例

curl -sS -X POST http://47.93.118.167:5000/v1/video/check \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"event_id": "fdc491b5-88fd-4266-b09a-29e5bf6713aa"}'

响应：处理中（建议 5～10 秒后再查）

{
  "ok": true,
  "status": "processing",
  "msg": "任务状态：RUNNING…"
}

响应：已完成

{
  "ok": true,
  "status": "done",
  "download_url": "/v1/video/file/fdc491b5-88fd-4266-b09a-29e5bf6713aa"  // 相对路径，需拼接 Base URL 下载
}

返回字段	类型	说明
status / public_status	string	queued / submitted / uncertain 请求已保存；processing / generating 生成中；done / succeeded 生成成功；failed 明确生成失败
terminal / confirmed_failure	boolean	只有明确终态失败才停止跟踪。HTTP 5xx、超时、无效JSON、ok=false 本身都不能证明生成失败
status_version / observed_at	number	原单状态版本、上次持久状态的观测时间；成功终态不会被迟到的查询异常降级
query_unavailable / retry_after	boolean / number	查询健康状态与建议等待秒数；临时查不到进度时沿用原编号和上次任务状态
download_url	string/null	完成时的视频下载路径；null 表示任务成功但视频源已过期，可联系客服

7下载视频

拼接平台根地址 + download_url，不要重复拼接 /v1。平台入口需要 Bearer API Key，成功可返回文件或 302 跳转；使用支持安全跳转的HTTP客户端，跨域后不转发平台API Key。

# 下载视频文件
curl -f -L -o output.mp4 \
  -H "Authorization: Bearer $API_KEY" \
  http://47.93.118.167:5000/v1/video/file/fdc491b5-88fd-4266-b09a-29e5bf6713aa

8图生视频：参考图参数

在 prompt 之外，可通过 image_data_urls 传入最多 9 张参考图（人物、场景、风格等，首张为首帧），其余参数与文生视频完全一致。每张图需编码为 data URL：

data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...  // 形如这样的一长串

常见语言编码方式：

• Python：base64.b64encode(open("a.png","rb").read()).decode()，再拼前缀 "data:image/png;base64,"
• JS：FileReader 的 readAsDataURL() 直接得到 data URL
• 命令行：base64 -w 0 a.png（Linux/macOS）后手动拼接前缀

# 图片 + 文字 生成视频（图生视频）
curl -sS -X POST http://47.93.118.167:5000/v1/video/generate \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "角色保持参考图形象，在古战场上挥剑，镜头缓缓环绕，电影级打光",
    "duration": 5,
    "image_data_urls": [
      "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...（第一张图的完整 base64）",
      "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...（第二张，可选）"
    ]
  }'

9提示词增强（强烈建议）

调用 MiniMax H3-Context-IR 将分镜提示词增强为「多段式结构化长提示词」，显著提升角色一致性与画面质量。该功能需管理员在后台开启，未开启时返回 HTTP 503。

字段	必填	类型	说明
prompt	是	string	待增强的提示词（最长 8000 字）
image_data_url	否	string	首帧参考图 data URL，用于保证画面中主体与参考一致
duration	否	number	视频时长（秒），默认 15，影响增强输出的时间线粒度

成功响应

{
  "ok": true,
  "result": "【增强后的结构化提示词】…",
  "cost": 0.11,
  "balance": 7461.08,
  "tokens_in": 1200,
  "tokens_out": 1800
}

若未生效（超时或上游异常）返回 ok=false 且不扣费。增强所得提示词可直接作为 /v1/video/generate 的 prompt 使用。

10计费与免费额度

项目	规则
视频制作	以当前账号模型目录的报价为准，包含按次或按秒方式。先按原请求预留一次额度，成片保存可交付后结算一次；明确失败按原资金来源释放，不因查询异常重复扣退
提示词增强	基础费 0.10 元/次 + 按 tokens 计费（输入 5.80 元/百万 tokens、输出 23.00 元/百万 tokens，当前默认），仅实际产生增强时收取；余额不足自动回退原始提示词，不阻塞视频生成
视频体验额度	新用户赠送已关闭。已获得且未使用的原有额度保留；是否可用以账号实时返回为准。确认生成失败时原子次额度只退回一次，不额外生成赠送。会员权益独立计算。
失败退款	任务失败（含超时 30 分钟未完成）自动退还本次视频费，已消耗的增强费用不退

11限制与说明

项目	说明
时长上限	单个任务默认最长 15 秒（以工作流上限为准），超出返回 400
并发限制	按当前账号、子接口和全局配置执行。已取得原任务编号的请求继续查询原单，不因为查询限流而重新生成
参考图数量	按当前模型目录的能力上限校验，请勿假定超量素材会被忽略
参考音频数量	按当前模型目录的能力上限校验
文件保留	成片默认保留 3 天，任务和资金记录继续保留，二者不是同一清理对象
归属校验	每个 API Key 只能查询/下载本账号的任务（event_id 不可跨账号访问）

12HTTP 状态码与错误

先区分：本次查询失败，还是视频任务失败

提交生成与查询进度是两次独立请求。例如：视频已受理、正在生成；随后一次进度查询返回503，只说明这次没能读到最新状态。视频可能仍在生成，也可能已经完成。请保留原任务编号与上次可信状态，继续查询；不要显示“生成失败”、停止取片或再次调用生成。

返回情况	接入方处理
HTTP 200，status=failed 且 terminal=true、confirmed_failure=true	任务明确失败；展示 error 和 failure_details，按实际资金回执显示退款。
HTTP 503、超时、断网、无法解析响应，或 error_scope=query	只记录“进度暂未刷新”，保留原编号与上次状态。按 Retry-After 重查；连续异常逐步延长至60秒，不重新生成。
HTTP 200，status=done、public_status=succeeded	生成成功。按 delivery_available、download_url 和 expires_at 及时下载。

{
  "ok": false,
  "code": "status_read_unavailable",
  "request_error": true,
  "error_scope": "query",
  "task_state_unchanged": true,
  "query_unavailable": true,
  "retryable": true,
  "retry_after": 5,
  "event_id": "dvq-原任务编号"
}

上述503回执不包含任务 status=failed。API不会仅因一次查询异常释放资金或改变任务终态。接入方须分别保存任务状态与最近一次查询是否成功；不能把所有非200都映射成视频失败。

推荐同一任务每5秒左右查询一次；大量任务使用 POST /v1/video/results/reconcile，JSON为 {"task_ids":["dvq-..."]}，每批最多100个原编号。长期接入可使用 GET /v1/video/results?after_revision=0&limit=50 增量补拉，并保存返回游标。

明确失败后的正常重提

明确失败且原额度已退回后，可以修正素材再提交；也可以使用新的 client_request_id。沿用原逻辑编号时，平台为重试建立独立执行记录，旧失败及退款保留。响应中的 logical_request_id 是逻辑原编号，client_request_id 是本次执行编号，execution_attempt 是执行轮次。请保存本次响应。

首次明确失败退款后，沿用原逻辑编号正常提交即可。后续主动重试请同时传 retry_of_client_request_id（值为上次响应的执行编号），或等价请求头 Retry-Of。同一重试目标的网络重发会合并为一次执行，不要在传输自动重试时更换目标。原任务仍在途、已成功或付费结果未知时，不会开启新的付费执行。

{
  "client_request_id": "原逻辑编号",
  "retry_of_client_request_id": "上一次失败且退款的执行编号",
  "prompt": "修正后的提示词",
  "duration": 15
}

按逻辑请求号查询得到最新一轮；按旧 dvq-... 任务号查询，仍得到那一笔原任务的结果。重试分配后若受理回执尚未就绪，会返回可重试查询异常，不会把旧任务的失败当作新任务结果。

素材格式与具体原因

支持模型允许的图片、音频和视频格式，扩展名与MIME大小写、常见别名会统一处理；合法同类文件声明错误时按实际内容纠正。例如JPEG内容声明PNG不会再仅因此被拒绝。损坏、伪造或跨类型文件仍会拒绝；原资产不修改，必要转换仅作用于发送副本。

时长错误会注明是“参考音频累计时长”“单段参考素材”还是“输出视频”。例如“参考音频累计22.6秒，超过15秒上限”，应缩短或减少参考音频；修改输出视频时长不能解决。具体上限以所选模型能力和实际返回的 failure_details 为准。

除下载接口外，所有接口出错时返回 JSON：{"ok": false, "error": "原因"}。

状态码	含义 / 常见原因
400	请求参数错误：缺少 prompt、缺少 event_id、时长超过上限等
401	API Key 无效或未携带 Authorization 头
402	余额不足，请先充值
403	账号被停用，或无权查询/下载该任务
429	并发任务数达上限，请稍后重试
500 / 502 / 503	本次HTTP请求或依赖暂不可用，不代表视频终态，不据此退款、重扣或重新生成；保留原编号重查

13完整示例（提交 → 轮询 → 下载）

Python（推荐）

# pip install requests
import base64, time, uuid
import requests

API_KEY = "sk-xxxxxxxxxxxxxxxx"                  # 替换为你的 API Key
BASE = "http://47.93.118.167:5000"
HEADERS = {"Authorization": "Bearer " + API_KEY}

def submit(prompt, client_request_id, duration=5, image_path=None):
    body = {"prompt": prompt, "duration": duration, "client_request_id": client_request_id}
    if image_path:                                 # 图生视频（可选）
        b64 = base64.b64encode(open(image_path, "rb").read()).decode()
        body["image_data_urls"] = ["data:image/png;base64," + b64]
    r = requests.post(BASE + "/v1/video/generate", json=body, headers=HEADERS, timeout=60)
    j = r.json()
    if not j.get("event_id"):
        raise RuntimeError("尚未取得任务编号；保留原client_request_id，按原请求号查询，勿换号重提")
    print("原任务已保存", j["event_id"], "；保留编号，等待可交付后结算")
    return j["event_id"]

def wait_done(event_id, timeout=3600):
    t0 = time.monotonic()
    while time.monotonic() - t0 < timeout:
        try:
            with requests.post(BASE + "/v1/video/check", json={"event_id": event_id},
                               headers=HEADERS, timeout=(3, 12)) as r:
                if r.status_code != 200:
                    time.sleep(5)
                    continue                       # 查询错误：保留原编号继续查
                j = r.json()
        except (requests.RequestException, ValueError):
            time.sleep(5)
            continue                               # 不写成生成失败，不创建新任务
        if j.get("status") == "done":
            if j.get("download_url"):
                return BASE + j["download_url"]
            raise RuntimeError("任务成功，但文件已不可下载，请核对delivery_state和expires_at")
        if j.get("terminal") is True and j.get("confirmed_failure") is True and j.get("status") == "failed":
            raise RuntimeError(f"原任务明确失败: {j.get('error')}")
        time.sleep(max(1, min(60, j.get("retry_after") or 5)))
    print("本次暂停自动查询；原任务仍保留，请稍后按原编号恢复查询")
    return None

def download(url, out="video.mp4"):
    with requests.get(url, headers=HEADERS, stream=True, timeout=300) as r:
        r.raise_for_status()
        with open(out, "wb") as f:
            for chunk in r.iter_content(1 << 16):
                f.write(chunk)
    print("已保存:", out)

client_request_id = "client-" + uuid.uuid4().hex
print("先持久保存原请求号:", client_request_id)       # 网络中断后用此号恢复，勿换号重复生成
event_id = submit("一只金红色的凤凰从云海上缓缓飞过，电影级画面", client_request_id)
print("持久保存原任务号:", event_id)
url = wait_done(event_id)
if url:
    download(url)

原单恢复、增量补拉和完成通知

所有接口使用现有 Bearer API Key，只返回本账号的原单，不创建生成、不改变资金。

接口	用途
GET /v1/video/requests/{client_request_id}	提交连接中断后按原请求号找回原任务，下载路径与按任务号查询一致
POST /v1/video/results/reconcile	传 {"task_ids":["dvq-原编号"]}，每批1至100笔，恢复调用方曾误标失败的任务
GET /v1/video/results?after_revision=0&limit=50	按账号状态版本补拉；保存 next_revision 并翻页，historical_projection_ready=false 时历史结果仍在补齐，继续后续补拉
GET /v1/video/events?after_revision=0&limit=50	持久终态事件。按 event_id 去重、按 status_version 忽略乱序旧状态
POST /v1/video/events/{event_id}/ack	接入方已保存事件后的确认，不等于已下载视频
PUT /v1/video/result-webhook	可选配置 {"url":"https://你的公网域名/通知路径"}。仅HTTPS/443，返回一次性 signing_secret；重复配置会轮换密钥
GET / DELETE /v1/video/result-webhook	查看配置（不返回密钥）或停用通知；未配置时不发送回调

回调请求头含 X-Video-Event-ID、X-Video-Timestamp、X-Video-Signature: v1=...。对原始请求体计算 HMAC-SHA256(secret, timestamp + "." + raw_body)，校验时间偏差、签名和事件ID，再以数据库事务保存并返回2xx。回调至少投递一次，需去重；不跟随重定向，失败退避重试，超过3天转人工关注，仍可补拉数据库事件。

Shell：按原编号恢复结果

export API_KEY="sk-xxxxxxxxxxxxxxxx"
BASE="http://47.93.118.167:5000"

# 批量核对：替换为已持久保存的原任务编号，不新建生成
curl -sS -X POST "$BASE/v1/video/results/reconcile" \
  -H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" \
  -d '{"task_ids":["dvq-原任务编号1","dvq-原任务编号2"]}'

# 增量补拉：保存返回的next_revision，后续替换after_revision
curl -sS "$BASE/v1/video/results?after_revision=0&limit=50" \
  -H "Authorization: Bearer $API_KEY"

附其他接口（目录 / 技能 / 工作流 / 改写 / 增强 / 生图）

0. 接口目录 GET /v1/meta（免费）

统一入口，用 type 参数选择子接口（必填）：catalog（接口目录）、skills（技能列表）、workflows（工作流列表）。

字段	必填	类型	说明
type	是	string	catalog / skills / workflows

# 接口目录
curl -sS "http://47.93.118.167:5000/v1/meta?type=catalog" -H "Authorization: Bearer $API_KEY"
# 技能列表
curl -sS "http://47.93.118.167:5000/v1/meta?type=skills" -H "Authorization: Bearer $API_KEY"
# 工作流列表
curl -sS "http://47.93.118.167:5000/v1/meta?type=workflows" -H "Authorization: Bearer $API_KEY"

0.1 文本 AI POST /v1/ai/text

文本类 AI 统一入口，用 op 参数选择子接口（必填）：rewrite（提示词改写，等同 /v1/rewrite）、enhance（提示词增强，等同 /v1/enhance）。参数与旧接口完全一致。

字段	必填	类型	说明
op	是	string	rewrite / enhance

# 提示词改写
curl -sS -X POST http://47.93.118.167:5000/v1/ai/text \
  -H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" \
  -d '{"op":"rewrite","text":"一个少年觉醒修仙天赋","skill_id":"cinematic-studio"}'
# 提示词增强
curl -sS -X POST http://47.93.118.167:5000/v1/ai/text \
  -H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" \
  -d '{"op":"enhance","prompt":"少年在山巅觉醒","duration":5}'

1. 获取技能列表 GET /v1/skills（免费）

返回平台可用的 AI 改写技能列表及计费参数，用于前端展示或选择改写技能。

字段	类型	说明
skills	array	技能列表，每项含 id name category desc
rewrite	object	改写计费：enabled input_cost output_cost base_cost
context_ir	object	增强计费：enabled input_cost output_cost base_cost

curl -sS http://47.93.118.167:5000/v1/skills \
  -H "Authorization: Bearer $API_KEY"

2. 获取视频工作流 GET /v1/workflows（免费）

返回可用的视频生成工作流列表（脱敏，不含密钥），含名称、分辨率、时长上限、视频单价。

curl -sS http://47.93.118.167:5000/v1/workflows \
  -H "Authorization: Bearer $API_KEY"

3. 提示词改写 POST /v1/rewrite

用 DeepSeek 按指定风格技能改写提示词 / 剧本（强制输出六段式结构）。

字段	必填	类型	说明
text	是	string	要改写的内容（最长 8000 字符）
skill_id	否	string	单个技能 id
skill_ids	否	array	多个技能 id（优先于 skill_id）

响应

{
  "ok": true,
  "result": "【六段式改写结果】…",
  "cost": 0.05,
  "balance": 7461.08,
  "tokens_in": 576,
  "tokens_out": 37
}

4. 生成分镜图 POST /v1/generate

生成一张分镜图（图生图 / 文生图），返回 base64 图片。

字段	必填	类型	说明
prompt	是	string	图片提示词
provider	否	string	指定生图 API（子接口名）；缺省自动轮询。传了不存在的名称会返回 400 不支持的子接口
name	否	string	图片名称
size	否	string	尺寸，如 720x1280（竖屏）/ 1280x720（横屏）
images	否	array	参考图 data URL 数组（最多 2 张，图生图）

响应

{
  "ok": true,
  "image_b64": "iVBORw0KGgo...（PNG base64）",
  "cost": 0.08,
  "balance": 7461.08
}

14常见问题

• 调用返回「无效的 API Key」？ 检查请求头是否为 Authorization: Bearer sk-xxx（注意 Bearer 后有一个空格），且 Key 未被删除。
• 提交时提示余额不足？ 按秒预扣费，请确保余额 ≥ 本次费用（如 5 秒 0.25 元），可联系管理员充值。
• 多久能拿到视频？ 单条 5 秒任务通常约 1～3 分钟，取决于上游排队情况。
• 任务失败会扣钱吗？ 失败自动退还视频费；增强已消耗的 tokens 费用不退。
• 视频能保存多久？ 成片可交付后默认保留3天，以 expires_at 为准，请及时下载；任务和资金记录继续保留。
• 可以传几张图 / 几段音频？ 参考图最多 10 张（首张为首帧）、参考音频最多 5 段（以上游额度为准）；不传即为文生视频。