开发者 · API 文档

把数字人视频能力接进你的系统

梦境 AI 提供一套 REST 接口，覆盖形象查询、音色合成、脚本生成、视频产出与订单支付。接口全部返回 JSON，鉴权基于 Cookie 会话。

版本：v2.0.1 基础地址：https://你的域名 数据格式：JSON

快速开始

接口路径统一以 /api 开头。下面这段流程能跑通「登录 → 挑形象 → 提交任务 → 查询结果」的最短链路：

bash

# 1. 登录，拿到会话 Cookie（写入 cookies.txt）
curl -c cookies.txt -X POST https://你的域名/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"account":"13900000001","password":"123456"}'

# 2. 挑一个数字人形象
curl -b cookies.txt "https://你的域名/api/avatars?page=1&pageSize=5"

# 3. 提交视频生成任务
curl -b cookies.txt -X POST https://你的域名/api/videos \
  -H "Content-Type: application/json" \
  -d '{"title":"产品介绍第一条","avatarId":"AV1001","voiceId":"VO1001","script":"这里是你的口播文案"}'

# 4. 轮询任务进度（progress 到 100 即为完成）
curl -b cookies.txt https://你的域名/api/videos/VD1001

关于鉴权载体。登录成功后服务端下发 mj_sid 会话 Cookie（HttpOnly、SameSite=Lax，有效期 7 天）。用浏览器之外的客户端调用时，只需把这个 Cookie 带上即可，不需要额外申请 Token。后台接口与用户接口共用同一套会话机制，区别只在账号角色。

鉴权方式

站点没有为开放平台单独设计一套 OAuth，而是直接复用站内的会话机制。这样做的好处是接口与网页看到的永远是同一份数据，不会出现「API 里的梦豆余额和页面上对不上」这类问题。

场景	需要什么	说明
公开接口	无	站点信息、形象列表、音色列表、套餐、选题素材等，可直接访问
用户接口	已登录会话	创作、我的作品、钱包流水、下单支付；未登录返回 `401`
管理接口	管理员会话	路径以 `/api/admin/` 开头；非管理员返回 `403`
支付回调	渠道签名	由支付渠道服务端调用，不走会话鉴权，而是验签 + 幂等处理

不要把管理员会话交给第三方。管理接口可以改套餐价格、改订单状态、读全部用户数据。需要给外部系统开通能力时，请用「联系商务」申请为你的场景单独开放的接口范围，而不要直接给管理员账号。

通用约定

响应结构

成功与失败统一包一层，便于客户端只写一次解包逻辑：

成功

{
  "code": 0,
  "message": "ok",
  "data": { /* 业务数据 */ }
}

失败

{
  "code": 400,
  "message": "手机号格式不正确",
  "data": null
}

HTTP 状态码与响应体里的 code 保持一致。客户端判断成败请以 HTTP 状态码为准，message 是给人看的，随时可能调整文案，不要用来做分支判断。

金额单位

接口里的金额字段（amount、price）单位是分，整数。19.90 元 传 1990。这是为了避免浮点误差——财务数据上 0.1 + 0.2 !== 0.3 是事故而不是小事。展示时再除以 100。

分页

列表接口接受 page（从 1 开始）与 pageSize（默认 20，上限 200），返回体含总数：

分页响应

{
  "code": 0,
  "data": {
    "items": [ /* 当前页 */ ],
    "total": 128,
    "page": 1,
    "pageSize": 20
  }
}

接口列表

下表列出全部可用路径。GET 表示读取，POST 表示创建或触发动作，PUT / PATCH 表示更新，DELETE 表示删除。

站点与版本

方法	路径	说明
GET	/api/settings	站点公开配置：站点名、公告、注册开关、梦豆规则、后台入口路径
GET	/api/version	代码版本与构建日期，用于确认服务器上跑的是不是最新代码
GET	/api/home/overview	首页聚合数据：统计、热门形象、模板、场景

账号

方法	路径	说明
POST	/api/auth/register	注册。手机号或邮箱二选一，成功后自动登录并赠送注册梦豆
POST	/api/auth/login	登录。参数 `account` + `password`
POST	/api/auth/logout	退出并销毁会话
GET	/api/auth/me	当前登录用户。未登录返回 401，前端据此展示登录态
PUT	/api/me/profile	修改昵称、头像
GET	/api/me/wallet	梦豆余额与最近流水
GET	/api/me/overview	个人中心聚合：作品数、订单数、消耗统计

数字人 / 音色 / 模板

方法	路径	说明
GET	/api/avatars	形象列表。支持 `keyword` `category` `gender` `sortBy`
GET	/api/avatars/:id	形象详情
GET	/api/voices	音色列表。支持 `keyword` `gender`
GET	/api/templates	爆款模板列表
GET	/api/templates/:id	模板详情，含示例脚本结构
GET	/api/plans	套餐列表，价格单位为分

视频生成

方法	路径	说明
POST	/api/videos	提交生成任务（需登录）。消耗梦豆，余额不足返回 400
GET	/api/videos	我的作品列表
GET	/api/videos/:id	任务详情。`progress` 为 0-100 的进度百分比
DELETE	/api/videos/:id	删除作品。生成中的任务不允许删除

POST /api/videos · 请求与响应

// 请求
{
  "title": "产品介绍第一条",
  "avatarId": "AV1001",     // 必填，来自 /api/avatars
  "voiceId": "VO1001",      // 可选，不传用形象默认音色
  "templateId": "TP1001",   // 可选，套用模板结构
  "script": "这里是你的口播文案",
  "aspect": "9:16",         // 可选：9:16 / 16:9 / 1:1
  "duration": 30             // 可选，秒
}

// 响应
{
  "code": 0,
  "message": "ok",
  "data": {
    "video": {
      "id": "VD1001",
      "status": "processing",
      "progress": 0,
      "cost": 20              // 本次消耗的梦豆
    }
  }
}

下单与支付

方法	路径	说明
GET	/api/pay/methods	当前可用的支付方式（按后台已启用的渠道动态下发）
POST	/api/pay/create	创建订单并发起支付。金额由服务端按套餐计算，客户端传价格会被忽略
GET	/api/pay/orders/:id	订单与支付状态，用于收银台轮询
POST	/api/pay/orders/:id/reconcile	主动查单（用户点了「我已完成支付」时调用），以渠道结果为准修正本地状态
POST	/api/pay/orders/:id/cancel	关闭未支付的订单
GET	/api/me/orders	我的订单列表
GET	/api/me/wallet-txns	梦豆流水
GET	/api/pay/coupons	可领取 / 已领取的优惠券
POST	/api/pay/notify/wechat	微信支付结果通知（渠道服务端调用）
POST	/api/pay/notify/alipay	支付宝异步通知（渠道服务端调用）
POST	/api/pay/notify/aggregate	聚合支付异步通知（渠道服务端调用）
GET	/api/pay/notify/aggregate	部分聚合渠道用 GET 回跳，同样做验签与幂等处理

支付状态只以服务端为准。不要让前端在支付完成后直接调接口「标记已支付」——回调验签与幂等才是唯一的发货入口。客户端要做的只有两件事：跳转到渠道收银台，然后轮询 /api/pay/orders/:id 看状态。

AI 能力

方法	路径	说明
GET	/api/ai/capabilities	当前已就绪的 AI 能力（文本 / 语音 / 视频）与可用模型
POST	/api/ai/generate	生成口播脚本 / 选题拆解。未配置供应商时返回降级结果而不是报错
POST	/api/ai/tts	文本转语音，返回音频地址

选题素材

方法	路径	说明
GET	/api/collect/feed	已采集的选题素材库，支持分类与关键词筛选
POST	/api/collect/items/:id/adopt	采用为创作起点（需登录），便于运营看哪些选题受欢迎

后台接口总览

以下接口全部位于 /api/admin/ 下，需要管理员会话。这里只列分组与用途；具体字段以后台页面为准，不建议第三方直接依赖，接口可能随运营需求调整。

分组	主要用途	代表路径
概览与用户	数据看板、用户增删改查、封禁、导出	/api/admin/stats /api/admin/users
内容资产	数字人、模板、音色、作品的维护与审核	/api/admin/avatars /api/admin/videos/:id
交易	订单表格、查单、退款、财务对账、CSV 导出	/api/admin/orders /api/admin/finance/summary
支付渠道	渠道配置、密钥脱敏保存、连通性测试、平台证书获取	/api/admin/pay/channels
AI 供应商	多供应商配置、按能力分组、连通性测试、用量与计价	/api/admin/ai/configs
内容采集	采集源管理、试采、立即采集、内容库维护、调度开关	/api/admin/collect/sources
商务留言	「联系商务」表单提交的线索，含跟进状态与备注	/api/admin/contact
系统	站点设置、操作日志、演示数据重置	/api/admin/settings

错误码

状态码	含义	常见原因与处理
200	成功	—
400	参数错误	字段缺失或格式不对，`message` 会指出具体字段
401	未登录	会话过期（默认 7 天）或 Cookie 没带上，重新登录即可
403	权限不足	访问了管理接口但当前账号不是管理员；或路径越权被拦截
404	资源不存在	ID 不存在，或接口路径拼错
405	方法不允许	路径存在但 HTTP 方法与接口定义不符
409	状态冲突	典型场景：订单状态已变化（重复发货、重复退款），或渠道不支持自动退款需要人工处理
429	请求过于频繁	触发限流，按 `message` 提示的时间重试
500	服务器内部错误	请把请求路径与时间反馈给技术支持

限流与配额

商务留言：同一 IP 每小时最多 5 条，两条之间至少间隔 20 秒，防止脚本灌库。
内容采集：同一域名设有最小采集间隔，避免把对方站点打挂；采集失败会记录原因并保留在采集记录里。
AI 调用：按供应商配额走，遇到上游 429 / 5xx 会自动退避重试，重试仍失败会在任务记录里留下错误原因。
梦豆消耗：视频生成、AI 调用按后台配置的单价扣减，余额不足直接返回 400，不会先扣成负数再失败。

需要更高的调用配额或更短的间隔？通过「联系商务」说明你的场景与预估量级，我们会按实际情况调整配置。

版本变更

接口的变更（新增字段、调整路径、行为修正）都会记录在更新日志里，并在 GET /api/version 返回的版本号上体现。

查看更新日志帮助中心联系商务