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

版本： 1.0 ｜ 更新日期： 2026-07-30

概述

开放平台让你用程序（或让大模型）调用平台的内容生产能力：

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

开放平台只提供视频能力。图文创作（抽帧成图 + 文案）暂不对外开放，请在网页端「创作中心 → 图文内容创作」使用。

接口根地址：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 （两个页面都免登录，可直接分享给对接的开发者）

认证

所有接口都要带请求头：

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}
  ]
}

id 即各任务的 voice_id。audio_url 是试听直链。

背景音乐

GET /open/bgm

字段：id / name / file_url / duration / tags / sort_order。对应 bgm_id、bgm_ids。

片尾视频

GET /open/outros

字段：id / title / file_url / duration / width / height。对应 outro_id、outro_ids。

数字人形象

GET /open/digital-humans

字段：id / name / description / file_url / cover_url / is_preset。对应 digital_human_id。

素材分组

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

字段：id / name / description / clip_count。对应 clip_group_id、clip_group_ids。

两者的 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。

任务分组

GET /open/groups

给作品归类用（平台公共分组），对应 group_id。

封面模板

GET /open/cover-templates?portrait=true

字段：template_id / name / image（排版示意图）/ is_random。对应 cover_config.template_id。 真实封面大字由系统按每条视频的文案自动提取，不需要你传文字。

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

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

创作任务

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

创建成功统一返回：

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

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

POST /open/fluid-tasks

专属字段：

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,
    "enable_subtitle": true
  }'

2. 数字人视频

POST /open/digital-human-tasks

专属字段：

head_duration=-1（全程口播）不需要任何素材片段，可直接用。

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。
• 所有 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"))

让大模型直接调用（AI Skill）

个人中心「开放平台」页可下载 Claude Skill（lingzao-video-skill.zip）。 解压后把 lingzao-video 目录放进 Claude 的 skills 目录（Claude Code 为 ~/.claude/skills/）， 把 API 密钥写入环境变量 LINGZAO_API_KEY（或对话中直接给它）， 之后用自然语言下指令即可，例如：

用数字人做 5 条讲「秋季护肤」的短视频，每条 30 秒，配轻快点的背景音乐

skill 会自行选择任务类型、查音色/素材分组、提交任务、轮询进度并把成片链接给你。