灵造AI（中巨量）开放平台 API 文档

版本： 1.1 ｜ 更新日期： 2026-08-28

概述

本文档描述灵造智能体接口（即中巨量-灵造AI 开放平台 API），让你用程序调用平台的内容生产能力：

💡 不想写代码？ 主流 AI 客户端（WorkBuddy、Codex / ChatGPT、Claude Code、 Claude 桌面端、Cursor 等）都支持 MCP——填一个地址加密钥就能让 AI 帮你出片， 下一节「接入 AI Agent」就是完整接入步骤（含各客户端配置与一句话安装）。 需要自己写代码调接口的，从「认证」往下看。

配套还有配置查询（音色 / 背景音乐 / 片尾 / 数字人 / 素材分组 / 封面模板）、任务进度与产出查询、任务删除、账户积分查询。

零素材也能出片

只有想用自己的素材时才需要上传。画面来源（clip_source）四选一，其中三种都不用你准备任何东西：

数字人视频还有一种更省事的做法：head_duration: -1（全程口播），整条只有数字人在讲，压根不涉及画面素材。

开箱即用的预设资源

下面这些平台都已备好，调接口拿 ID 直接用，不需要自己上传或克隆：

数量会随平台上新增加，以接口返回为准。想用自己的音色/形象，在网页端上传或克隆后同样从这些接口取到。

接口根地址：https://ai-mix.chuhaibang.com/api/v1/open

在线文档：https://ai-mix.chuhaibang.com/open-api ｜ AI Skill：https://ai-mix.chuhaibang.com/open-api/skill （两个页面都免登录，可直接分享给对接的开发者）

接入 AI Agent（MCP / Skill）

不想自己写代码调接口，直接让 AI 帮你出片——按你用的 AI 工具选一条：

两者建议一起用：MCP 是调用通道，Skill 是使用方法。三条路（MCP / Skill / 本文的 HTTP 接口） 调的是同一套后端，产出完全一致，随时可以换。

本文以下内容是给自己写代码调接口的人看的。

认证

所有接口都要带请求头：

curl "https://ai-mix.chuhaibang.com/api/v1/open/account" -H "X-Api-Key: lz_你的密钥"

失败响应：

密钥安全：密钥请尽可能在服务端使用；怀疑泄漏时可在用户中心点「重置」，旧密钥立即失效。

统一响应格式

成功（HTTP 200）：

{ "code": 0, "message": "ok", "data": { } }

失败（HTTP 4xx / 5xx）：

{ "detail": "错误描述" }

常用状态码：

计费规则

API 与网页端共用同一份积分（永久积分 + 当月月度积分）。创建任务时先校验余额， 建任务成功后立即扣除；建任务失败不扣费。积分流水会带「· 开放平台API」后缀，便于对账。

提交前建议先查 GET /open/account 的 total_credits。积分不足时返回：

{ "detail": "积分不足：本次需要 120，剩余 45" }

资源归属与配额

• 音色 / 背景音乐 / 片尾 / 数字人：可用「平台预设（已上架）」+「你自己上传的」； 引用他人上传的返回 403，引用已下架预设返回 400。
• 素材分组（clip_group_ids）：只能用自己的分组，或平台标记的热门分组（clip_source=hot）。
• 任务查询 / 删除：只能操作自己的任务（含网页端创建的）。
• 存储、社媒账号数等配额与网页端一致，超限时相关接口返回 403。

成品保留期 ⚠️

通过 API 创建的任务，成品默认只保留 1 天，之后由系统每日定时任务整批硬删—— DB 记录与磁盘文件（成品视频、封面、配音）一并删除，不可恢复。

这么设计是因为 API 能批量出片，不清理会迅速堆满存储配额。

{
  "description": "...",
  "voice_id": 1,
  "keep_forever": true
}

keep_forever: true 的成品会持续占用你的存储配额，且不再自动清理。 批量场景请自行控制数量，或改为「下载到自己的存储后调 DELETE /open/tasks/{id} 删除」。 存储超限会导致素材上传等接口返回 403。

其它说明：

• 保留期与 keep_forever 都只对 API 创建的任务生效；网页端/小程序创建的任务走各自的策略，在那两端传该字段无效。
• 已被提取为模板广场模板的批次不会被清理。
• 保留天数由平台配置，如需调整请联系平台运营。
• 任务详情/列表会回显 keep_forever，可据此确认设置是否生效。

账户

查询账户与积分

GET /open/account

响应 data（节选）：

配置查询

以下接口都是 GET，无参数（除标注外），返回列表。

💡 不想调接口找 ID？ 在「用户中心 → 开放平台」打开开发者模式，创作页面的数字人、 音色、背景音乐、片尾、素材分组旁会直接显示 #ID，点一下即可复制。

朗读音色

GET /open/voices

{
  "code": 0, "message": "ok",
  "data": [
    {"id": 1, "name": "女声-甜美", "audio_url": "https://.../voices/x.wav", "is_preset": true, "sort_order": 10}
  ]
}

做数字人视频时，优先用 /open/digital-humans 里该形象的 voice_profile_id —— 那是与形象绑定的音色，口型贴合度最好。

背景音乐

GET /open/bgm

传 bgm_ids（数组）时每条视频各自随机取一首，批量出片不会首首雷同。

片尾视频

GET /open/outros

传 outro_ids（数组）时每条视频随机取一个。

数字人形象

GET /open/digital-humans

素材分组

GET /open/clip-groups?source=group   # 我的分组（默认）
GET /open/clip-groups?source=hot     # 平台热门分组

热门素材分组是平台按主题打包好的公共素材库（如「AI科技」「汽车素材」「大海风景」「旅游风景」等 17 组、 合计 3000+ 片段），全体用户可直接使用。没有自己的素材时， 用 source=hot 取一个（或多个）分组 ID 填进 clip_group_ids，配 clip_source: "hot" 就能出片； 多个分组会合并成一个候选池，片段更丰富、成片重复度更低。

两者的 clip_source 必须和分组来源对应：拿 source=hot 的 ID 去配 clip_source: "group" 会报 403。

自己的分组与其中片段的维护（上传、下载链接、智能拆条、去水印）在网页端「素材管理」完成。

分组内片段（分页）

GET /open/clip-groups/{group_id}/clips?page=1&page_size=20

用于需要精确指定用哪几条片段时取 clip_group_clip_ids；不传该字段则系统在分组内自动挑选。

data 为分页结构 {total, page, page_size, items}，page_size 最大 500。 本人分组与平台热门分组都可以查。

任务分组

GET /open/groups

给作品归类用（就是网页端「我的作品」里的作品分类），对应创建任务时的 group_id。

不传 group_id 则任务归入「未分类」。任务详情会回显 group_name 便于核对。

封面模板

GET /open/cover-templates?portrait=true

portrait=true（默认）取竖屏示意图，portrait=false 取横屏；两种比例的模板 ID 是同一套， 做横屏视频时用 portrait=false 预览更准。真实封面大字由系统按每条视频的文案自动提取，不需要你传文字。

返回的第一项是「随机封面模板」（template_id 为 __random__、is_random: true）： 传它则每条视频各自随机取一个真实模板，适合批量出片时避免封面雷同。

{"cover_config": {"template_id": "__random__"}}

字幕模板

GET /open/subtitle-templates?portrait=true

响应字段

可选模板（接口按此顺序返回）

全部模板都支持字幕音效（has_sfx: true）。「默认高度」为竖屏值，横屏时模板 18% / 经典 6%。

字幕特效（entrances 的取值）

特效在同一模板内按句轮换（全程一种会显得单调），含高亮词的重点句固定用该模板最强的那种。 这些是模板的固有属性，不能单独指定——你只需选模板。

stacked（聚焦叠压）的规则与其它模板不同：它把一句拆成主副两段——前段白字先铺垫， 后段用高亮色缩放变大压上来，同时前段淡下去。按句在三种句式间轮换：

• overlay：后段直接盖在前段上（略偏右下、字号略小），前段原地变浅
• stack_up：前段缩小上移让位，后段大字落在原处，两者不重叠
• trio：三段句——首段转红居中，后两段白字同时从左上/右下滑入压住它

短句（一块）走常规居中出现，不做叠压。

除 __classic__ 外，字幕默认位于距画面底部 25%（竖屏 / 横屏 18%），避开手机端底部的 评论条与进度条；经典字幕保持原来的贴底位置（竖屏 8% / 横屏 6%）。 用 subtitle_bottom_percent（6–70）可以自己挪，越大越靠上； 用 subtitle_font_scale（0.7–1.5）在模板默认字号上整体放大/缩小。

第一项同样是「随机字幕模板」（__random__）。不传 subtitle_template_id 则用经典字幕 （白字黑边、无动效）。字幕文字取自文案，高亮词由 AI 自动挑选，都不需要你传。

enable_subtitle_sfx 开启后，音效与高亮严格同步：每个高亮词出现的瞬间必响一声， 每次从音效池里随机换一个音色。频率控制在高亮本身——同一个高亮词至少隔 4 秒才会 再次高亮/响（不同词互不影响，该出现就出现）。经典字幕同样适用。 stacked（聚焦叠压）的强调是每句都有的红/黄字，落点至少隔 6 秒； boxed（底框字幕）没有词级高亮，仍是每 3~4 句响一次。

字幕字体

GET /open/subtitle-fonts

响应字段：key（填给 subtitle_font_key）/ name（字体中文名）/ image（静态样张 PNG）。

10 款字体全部可免费商用：

不传 subtitle_font_key 则用所选模板自己的默认字体。 把细笔画字体（毛笔/手写类）换进无描边的模板时，系统会自动补 2.0 描边防止亮背景下看不清。

{"enable_subtitle": true, "subtitle_template_id": "punch", "enable_subtitle_sfx": true, "subtitle_font_key": "mashan"}

创作任务

三类视频任务的公共字段：

⚠️ 动画视频（/open/fluid-tasks）只接受上表的一个子集。它的画面是整屏文字动效， 没有素材片段可转场、也不叠加另一层字幕，因此下列字段对它无效： enable_title / title_*、enable_subtitle / subtitle_*、transition_type、 prefer_similar_ratio、clip_*、digital_human_id / head_duration / pip_config。 传了不会报错，会被静默忽略——别照着混剪的参数去调动画视频接口，否则会以为开了字幕其实没有。 动画视频实际支持的字段就是「1. 动画视频」小节列出的那些。

时长档位与数量上限

target_duration 在 AI 写文案（use_fixed_copy=false）时只能取固定档位，传其它值报 422：

固定文案模式（use_fixed_copy=true）不受档位限制，按文案朗读时长取任意秒数（混剪/数字人 1–600，动画 15–600）。

quantity 上限随时长（和画质）收紧，防止一次占满渲染队列：

数字人的「全程口播 / 片段中插 / 画中画」（head_duration 为 -1/-2/-3）另有更紧的配额： 15–20s≤50、30s≤40、60s≤20、120s≤10、300s≤4、600s≤2。 超限直接返回 422 并在 detail 里写明当前组合的上限，不会扣积分。

创建成功统一返回：

{
  "code": 0, "message": "ok",
  "data": {"task_id": 123, "title": "秋季护肤要点", "quantity": 5, "status": 0, "content_type": "fluid"}
}

朗读情绪

tts_emotion 控制整段朗读的语气，两种写法：

• 预设情绪名：开心 / 平静 / 惊讶 / 悲伤 / 愤怒 / 忧郁 / 恐惧 / 厌恶——走情绪向量，效果最稳。
• 自定义描述：任意一句话，如 像朋友聊天一样轻松随意、播音腔沉稳有力——走模型的文本描述情绪。

留空 = 不指定，跟随参考音本身的语气（与不传该字段行为一致）。

段内情绪切换（精准情绪控制，选填）：use_fixed_copy=true 时，可在 description 里 用成对标签把要变语气的句子包起来：

今天的销量又破纪录了，[开心]真的太棒了！[/开心]我们来看下具体数据。

标签内按该情绪朗读，标签外一律用 tts_emotion——闭合即复位，不需要额外的复位写法。 标签名可写预设情绪名，也可以写自定义描述（如 [像朋友聊天一样]…[/像朋友聊天一样]）。

标签本身不会被念出来，也不会进入字幕、分发文案和字数/时长计费（按剥掉标签后的正文算）。 不写标签就整段用 tts_emotion。仅中文朗读（tts_language=zh）支持——英文台词是译文， 标签在翻译前已剥离。

必须成对才生效：只写 [开心] 没有 [/开心] 的话，它就是普通正文， 方括号里的字会被念出来——所以要么补上闭合标签，要么别用方括号。 也正因为只认成对，[限时]五折 这类正常写法不会被误判成标记。

1. 动画视频（推荐入门，无需素材）

POST /open/fluid-tasks

专属字段：

支持的字段就这些（其余一律静默忽略，见上方公共字段表后的提示）：

横屏传 "resolution": "1920x1080" 即可，版式会按比例重新排布。

curl -X POST "https://ai-mix.chuhaibang.com/api/v1/open/fluid-tasks" \
  -H "X-Api-Key: lz_你的密钥" -H "Content-Type: application/json" \
  -d '{
    "description": "三个方法让短视频完播率翻倍",
    "voice_id": 1,
    "fluid_style": "karaoke",
    "quantity": 2,
    "target_duration": 30
  }'

2. 数字人视频

POST /open/digital-human-tasks

专属字段：

最省事的三种起步方式（都不用准备素材）：

• head_duration: -1 —— 全程口播，整条只有数字人在讲，不涉及画面素材
• clip_source: "fluid" —— 数字人开场 + AI 生成的文字动效画面
• clip_source: "hot" + clip_group_ids —— 数字人开场 + 平台热门素材（分组 ID 从 /open/clip-groups?source=hot 取）

留空 clip_source 走默认的 es 全库检索也可以，平台共享素材库会按文案自动匹配画面。

3. 视频混剪

POST /open/tasks

专属字段：

素材不足且 auto_crawl=false 时返回 400：

{
  "detail": {
    "code": "INSUFFICIENT_CLIPS",
    "message": "可用片段不足（12/30）",
    "keywords": ["护肤", "秋季"],
    "clip_count": 12,
    "min_clips": 30
  }
}

任务查询

任务列表

GET /open/tasks?page=1&page_size=20&status=2&content_type=fluid&only_api=true

data 为分页结构 {total, page, page_size, items}，items[] 含 id / title / status / quantity / total_done / total_failed / content_type / cover_url / created_at 等。

任务详情（含全部产出）

GET /open/tasks/{task_id}

{
  "code": 0, "message": "ok",
  "data": {
    "task": {"id": 123, "status": 2, "quantity": 2, "total_done": 2, "total_failed": 0, "content_type": "fluid"},
    "jobs": [
      {
        "id": 8801, "job_index": 0, "status": 4,
        "script_text": "……成片文案……",
        "distribute_copy": "……可直接用于发布的文案……",
        "output_url": "https://.../output/xxx.mp4",
        "cover_url": "https://.../output/xxx.jpg",
        "duration": 30.2,
        "image_urls": null
      }
    ]
  }
}

• jobs[].status：0 待处理 / 1 生成台词中 / 2 检索素材中 / 3 合成中 / 4 已完成 / 5 失败。 判断成功要用 4（0–3 都是进行中的阶段），失败看 5 的 error_msg。
• 成片取 output_url；封面取 cover_url。
• task 会原样回显提交时的全部创作参数（subtitle_template_id / bgm_ids / outro_ids / cover_config / interlude_anim / head_duration …），可用来核对参数是否按预期生效； 其中 voice_name / bgm_name / digital_human_name / group_name / clip_group_name 是配套的名称，省得再查一次列表接口。
• task.title 由 AI 按成片文案生成。提交瞬间返回的 title 是 description 的前 30 字截断， 文案生成完成后会被覆盖——需要正式标题请在轮询到 jobs[].status=4 后再读。
• 视频编码为 H.265（HEVC），1080×1920 / 25fps。个别老旧播放器或平台若不支持，需自行转码。
• 所有 URL 都是公网可直接下载的直链。
• 成品默认只保留 1 天（见「成品保留期」），请及时下载；需要长期留存就在提交时传 keep_forever: true。

产出分页列表

GET /open/tasks/{task_id}/jobs?page=1&page_size=20

批量很大（几百条）时用这个，避免详情接口一次返回过多数据。

删除任务

DELETE /open/tasks/{task_id}

删除任务及其产出文件，不可恢复，已消耗积分不退。

典型流程

1. GET  /open/account            # 看积分够不够
2. GET  /open/voices             # 选音色，拿 voice_id
   GET  /open/clip-groups        # （需要素材的任务）选素材分组
3. POST /open/fluid-tasks        # 提交任务，拿 task_id
4. GET  /open/tasks/{task_id}    # 每 10~30s 轮询一次
   → task.status == 2  取 jobs[].output_url
   → task.status == 3/4 看 jobs[].error_msg
5. 下载成品（默认 1 天后自动清理；要长期保留见「成品保留期」）

轮询建议：视频类生成耗时与 quantity × target_duration 正相关，通常几分钟到几十分钟； 间隔 15–30 秒即可，不要 1 秒一次。

Python 示例

import time
import requests

BASE = "https://ai-mix.chuhaibang.com/api/v1/open"
HEADERS = {"X-Api-Key": "lz_你的密钥", "Content-Type": "application/json"}


def post(path: str, payload: dict) -> dict:
    r = requests.post(f"{BASE}{path}", json=payload, headers=HEADERS, timeout=30)
    if r.status_code != 200:
        raise RuntimeError(f"HTTP {r.status_code}: {r.text}")
    return r.json()["data"]


def get(path: str, **params) -> dict:
    r = requests.get(f"{BASE}{path}", params=params, headers=HEADERS, timeout=30)
    if r.status_code != 200:
        raise RuntimeError(f"HTTP {r.status_code}: {r.text}")
    return r.json()["data"]


# 1) 余额与音色
print("积分：", get("/account")["total_credits"])
voice_id = get("/voices")[0]["id"]

# 2) 提交动画视频任务（不需要素材）
task = post("/fluid-tasks", {
    "description": "三个方法让短视频完播率翻倍",
    "voice_id": voice_id,
    "fluid_style": "karaoke",
    "quantity": 2,
    "target_duration": 30,
    "enable_subtitle": True,
})
task_id = task["task_id"]

# 3) 轮询到完成
while True:
    detail = get(f"/tasks/{task_id}")
    status = detail["task"]["status"]
    if status in (2, 3, 4):
        break
    print("处理中：", detail["task"]["total_done"], "/", detail["task"]["quantity"])
    time.sleep(20)

# 4) 取结果
for job in detail["jobs"]:
    if job["status"] == 2:
        print(job["output_url"])
        print("发布文案：", job.get("distribute_copy"))
    else:
        print("失败：", job.get("error_msg"))