logo
API docs by Redocly

火星电波 listenhub 服务接口文档 (2.0.4)

Download OpenAPI specification:

zkb: kb@marswave.ai URL: https://github.com/marswaveai/api-server License: Apache 2.0

此文档是 listenhub 服务的后端接口文档，适用场景是用于 APP 端的接口调用

Authentication

  • Authorization 用一个写死的 token 认证。后面需要有用户 JWT 方式认证, 格式为 Bearer <token>

user

用户管理相关接口

获取当前用户信息

获取当前用户信息

Authorizations:
None

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "username": "string",
  • "nickname": "string",
  • "avatar": "string",
  • "email": "string",
  • "activeStatus": 0,
  • "stripeCustomerId": "string",
  • "registerSource": "apple",
  • "provisionStatus": true,
  • "scopes": [
    ]
}

删除用户

删除用户

Authorizations:
None

Responses

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string",
  • "data": { }
}

更新用户信息

更新用户信息

Authorizations:
None
Request Body schema: application/json
required
nickname
string

昵称

avatar
string

头像

Responses

Request samples

Content type
application/json
{
  • "nickname": "string",
  • "avatar": "string"
}

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string",
  • "data": { }
}

获取用户配置

获取用户配置

Authorizations:
None

Responses

Response samples

Content type
application/json
{
  • "onboardingWeb": true,
  • "podcastVoiceExpiredToast": true,
  • "flowspeechVoiceExpiredToast": true,
  • "podcastUseTokenToast": true,
  • "storybookVoiceExpiredToast": true,
  • "storybookImagePop": true
}

切换用户配置

切换用户配置

Authorizations:
None
Request Body schema: application/json
required
onboardingWeb
boolean

是否开启Web端引导

podcastVoiceExpiredToast
boolean

是否开启播客语音过期提示

flowspeechVoiceExpiredToast
boolean

是否开启流式语音过期提示

podcastUseTokenToast
boolean

是否开启播客使用Token提示

Request samples

Content type
application/json
{
  • "onboardingWeb": true,
  • "podcastVoiceExpiredToast": true,
  • "flowspeechVoiceExpiredToast": true,
  • "podcastUseTokenToast": true
}

获取用户用量

获取用户用量

Authorizations:
None

Responses

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string",
  • "data": {
    }
}

用户签到

用户每日签到并获得积分奖励

Authorizations:
None
Request Body schema: application/json
required
platform
required
string
Enum: "listenhub" "nextlab" "banana-lab"

平台类型

Responses

Request samples

Content type
application/json
{
  • "platform": "listenhub"
}

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string",
  • "data": {
    }
}

获取签到状态

获取用户的签到状态信息

Authorizations:
None

Responses

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string",
  • "data": {
    }
}

获取订阅用量

获取订阅用量

Authorizations:
None
query Parameters
page
integer >= 1
Default: 1

页码

pageSize
integer [ 1 .. 100 ]
Default: 10

每页数量

Responses

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string",
  • "data": {
    }
}

获取 Banana 用户公开信息

获取指定用户的公开信息（昵称、头像）

Authorizations:
None
path Parameters
userId
required
string^[0-9a-fA-F]{24}$

用户 ID

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "nickname": "string",
  • "avatar": "string",
  • "createdAt": 0,
  • "subscriptionStatus": "string",
  • "subscriptionPlan": {
    }
}

auth

认证管理相关接口

web 第三方登录初始化

web 第三方登录初始化

Authorizations:
None
query Parameters
providerType
required
string
Enum: "google" "apple"

平台类型

redirectUri
required
string <uri>

重定向 URL

Responses

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string",
  • "data": {
    }
}

web 第三方登录回调

web 第三方登录回调

Authorizations:
None
query Parameters
code
required
any

第三方登录授权码

state
required
any

第三方登录状态

Responses

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string",
  • "data": {
    }
}

mobile 第三方登录回调

mobile 第三方登录回调

Authorizations:
None
query Parameters
code
required
any

第三方登录授权码

providerType
required
string
Enum: "google-mobile" "apple-mobile"

第三方登录平台类型

Responses

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string",
  • "data": {
    }
}

获取 token

获取 token

Authorizations:
None
Request Body schema: application/json
required
grantType
string
Value: "refresh_token"

授权类型

refreshToken
string

刷新令牌

Responses

Request samples

Content type
application/json
{
  • "grantType": "refresh_token",
  • "refreshToken": "string"
}

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string",
  • "data": {
    }
}

发送邮箱验证码

发送邮箱验证码

Authorizations:
None
Request Body schema: application/json
required
email
string

邮箱

type
string
Value: "signin"

验证码类型

Request samples

Content type
application/json
{
  • "email": "string",
  • "type": "signin"
}

发送邮箱验证码（带 Turnstile 验证）

发送邮箱验证码，需要提供 Cloudflare Turnstile 验证 token。 此接口增加了机器人验证，提高安全性。

Authorizations:
None
Request Body schema: application/json
required
email
required
string <email>

邮箱地址

turnstileToken
required
string

Cloudflare Turnstile 验证返回的 token

Responses

Request samples

Content type
application/json
{
  • "email": "user@example.com",
  • "turnstileToken": "0.AAAAAAAAAA_BBBBBBBBBBB.CCCCCCCCCC-1234567890-D"
}

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string",
  • "data": {
    }
}

邮箱验证码登录

邮箱验证码登录

Authorizations:
None
Request Body schema: application/json
required
email
string

邮箱

code
string

验证码

Responses

Request samples

Content type
application/json
{
  • "email": "string",
  • "code": "string"
}

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string",
  • "data": {
    }
}

注销 token

注销 token

Authorizations:
None
Request Body schema: application/json
required
refreshToken
string

刷新令牌

Responses

Request samples

Content type
application/json
{
  • "refreshToken": "string"
}

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string",
  • "data": {
    }
}

episode

单集相关接口

预估 Episode 生成所需的积分

根据输入文本内容和图片数量，预估生成 Episode 所需的脚本、音频和图片积分

Authorizations:
None
Request Body schema: application/json
required
query
string
Default: ""

输入文本内容

imageCount
integer >= 0
Default: 0

图片数量

visualOnly
boolean
Default: false

仅视觉模式，不需要音频计算，audioCredits 将返回 0

Responses

Request samples

Content type
application/json
{
  • "query": "",
  • "imageCount": 0,
  • "visualOnly": false
}

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string",
  • "data": {
    }
}

获取分类列表

获取分类列表，支持按产品和状态筛选

Authorizations:
None
query Parameters
productId
required
string

产品ID

activeStatus
string
Enum: "active" "inactive"

激活状态

Responses

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string",
  • "data": {
    }
}

获取画廊单集列表

获取画廊中的单集列表，支持按产品、语言、分类筛选

Authorizations:
None
query Parameters
page
integer >= 1
Default: 1

页码

pageSize
integer [ 1 .. 100 ]
Default: 10

每页数量

productId
required
string

产品ID

language
string
Enum: "zh" "en"

语言

category
string

分类键

Responses

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string",
  • "data": {
    }
}

获取单集列表

获取单集列表,支持分页和时间排序

Authorizations:
None
query Parameters
page
integer >= 1
Default: 1

页码,从1开始

pageSize
integer [ 1 .. 100 ]
Default: 10

每页数量

productId
string

产品ID筛选(可选)

keyword
string

搜索当前用户自己的单集标题；匹配 episode.title 或三类 topic.title，大小写不敏感；服务端会 trim 并截断到 100 字符

sortBy
string
Default: "created_at"
Value: "created_at"

排序字段

sortOrder
string
Default: "desc"
Enum: "asc" "desc"

排序方向

Responses

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string",
  • "data": {
    }
}

批量删除单集

批量删除指定ID的单集（单批最多 100 个）。若单集关联视频生成任务，会一并软删除该任务，并对进行中（pending/generating）的任务退还积分。

Authorizations:
None
Request Body schema: application/json
required
ids
Array of strings <= 100 items

要删除的单集ID列表

Responses

Request samples

Content type
application/json
{
  • "ids": [
    ]
}

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string",
  • "data": {
    }
}

获取单集详情

获取单集详情信息

Authorizations:
None
path Parameters
episodeId
required
string

单集ID

Responses

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string",
  • "data": {
    }
}

获取单集详情 V2

获取单集详情信息 V2

Authorizations:
None
path Parameters
episodeId
required
string

单集ID

Responses

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string",
  • "data": {
    }
}

获取单集详情 V4

获取单集详情信息 V4

Authorizations:
None
path Parameters
episodeId
required
string^[0-9a-fA-F]{24}$

单集ID (24位十六进制字符串)

Responses

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string",
  • "data": {
    }
}

获取单集详情 V5

获取单集详情信息 V5 (优化的数据结构)

Authorizations:
None
path Parameters
episodeId
required
string^[0-9a-fA-F]{24}$

单集ID (24位十六进制字符串)

Responses

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string",
  • "data": {
    }
}

获取事件流式数据 V5

获取指定事件的流式数据 V5 (支持 script_generate 和 outline_generate)

Authorizations:
None
path Parameters
episodeId
required
string^[0-9a-fA-F]{24}$

单集ID (24位十六进制字符串)

query Parameters
event
required
string
Enum: "scripts" "outline"
Example: event=scripts

事件类型

Responses

Response samples

Content type
text/event-stream
Example
id: 689ef06042a332af99cd5781
event: script_generate
data: {"chunk":"突然变成了一副巨型水印框。"}

id: 689ef06042a332af99cd5781
event: script_generate
data: {"chunk":"这栋百年建筑的每一扇窗户"}

id: 689ef06042a332af99cd5781
event: script_generate
data: {"chunk":"[END]"}

获取单集重混数据

获取单集的重混相关数据，用于创建新单集时预填充输入信息。 当前仅支持 storybook 类型单集。 访问条件：单集为公开分享状态（enabledShare=true）或为当前用户所有

Authorizations:
None
path Parameters
episodeId
required
string^[0-9a-fA-F]{24}$

单集ID (24位十六进制字符串)

Responses

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string",
  • "data": {
    }
}

获取单集业务信息 V3

获取单集业务信息 V3

Authorizations:
None
path Parameters
episodeId
required
string

单集ID

Responses

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string",
  • "data": {
    }
}

获取当前事件列表 V3

获取当前事件列表 V3

Authorizations:
None
path Parameters
episodeId
required
string

单集ID

Responses

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string",
  • "data": {
    }
}

获取事件流式数据 V3

获取事件流式数据 V3

Authorizations:
None
path Parameters
episodeId
required
string

单集ID

query Parameters
event
required
string
Example: event=script_generate,outline_generate

事件类型(逗号分隔)

Responses

Response samples

Content type
text/event-stream
Example
id: 689ef06042a332af99cd5781
event: script_generate
data: {"chunk":"突然变成了一副巨型水印框。"}

id: 689ef06042a332af99cd5781
event: script_generate
data: {"chunk":"这栋百年建筑的每一扇窗户"}

id: 689ef06042a332af99cd5781
event: script_generate
data: {"chunk":"[END]"}

批量获取事件数据 V3

根据episodeId和events批量获取事件数据(只有非流式数据返回)

Authorizations:
None
path Parameters
episodeId
required
string

单集ID

query Parameters
event
required
string
Example: event=tag_generate,source_generate,title_generate,script_generate,outline_generate,audio_generate

事件类型 (逗号分隔)

Responses

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string",
  • "data": {
    }
}

生成流式语音

流式语音

Authorizations:
None
Request Body schema: application/json
required
Array of objects

来源

object

模板配置（可选）

Responses

Request samples

Content type
application/json
{
  • "sources": [
    ],
  • "template": {
    }
}

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string",
  • "data": {
    }
}

编辑单集

编辑单集内容，生成新的音频

Authorizations:
None
Request Body schema: application/json
required
type
required
string
Enum: "podcast" "flowspeech"

类型 podcast播客, flowspeech流式语音

required
Array of objects = 1 items

语音数组（目前限制1个）

language
required
string

语言

required
Array of objects

脚本数组

sourceEpisodeId
string

源单集ID（可选）

Responses

Request samples

Content type
application/json
{
  • "type": "podcast",
  • "speakers": [
    ],
  • "language": "string",
  • "scripts": [
    ],
  • "sourceEpisodeId": "string"
}

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string",
  • "data": {
    }
}

生成单集幻灯片

生成单集幻灯片

Authorizations:
None
path Parameters
episodeId
required
string

单集ID

Responses

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string",
  • "data": {
    }
}

分享单集

分享单集

Authorizations:
None
path Parameters
episodeId
required
string

单集ID

Request Body schema: application/json
required
enabledShare
boolean
Default: true

是否开启分享

Responses

Request samples

Content type
application/json
{
  • "enabledShare": true
}

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string",
  • "data": {
    }
}

更新单集标题

更新单集的标题

Authorizations:
None
path Parameters
episodeId
required
string

单集ID

Request Body schema: application/json
required
title
required
string

单集标题

Responses

Request samples

Content type
application/json
{
  • "title": "My Episode Title"
}

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string",
  • "data": {
    }
}

重试失败的单集（v2）

重试失败的单集，会复制原单集和相关的 topic 数据，创建新的单集并重新开始生成流程。 原单集将被删除，返回新创建的单集 ID。

支持的单集类型：

  • FlowSpeech（流式语音）
  • Storybook（故事书）
  • 普通 Topic

注意：只有状态为失败的单集才能重试。

Authorizations:
None
path Parameters
episodeId
required
string^[0-9a-fA-F]{24}$

失败的单集ID

Responses

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string",
  • "data": {
    }
}

重试单集 Deprecated

重试单集（已废弃，请使用 v2 版本）

Authorizations:
None
path Parameters
episodeId
required
string

单集ID

Responses

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string",
  • "data": {
    }
}

重试单集音频

重试单集音频

Authorizations:
None
path Parameters
episodeId
required
string

单集ID

Responses

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string",
  • "data": {
    }
}

集成多种来源创建单集

集成多种来源创建单集

Authorizations:
None
Request Body schema: application/json
required
query
string

查询内容

type
string
Enum: "podcast-solo" "podcast-duo"

播客类型

Array of objects

来源列表

object

模板配置（可选）

Responses

Request samples

Content type
application/json
{
  • "query": "string",
  • "type": "podcast-solo",
  • "sources": [
    ],
  • "template": {
    }
}

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string",
  • "data": {
    }
}

通过故事书创建单集

通过故事书创建单集

Authorizations:
None
Request Body schema: application/json
required
query
string

查询内容

Array of objects

来源列表

style
string

风格（可选）

object

图片配置（可选，兼容旧版本）

object

模板配置（可选）

Responses

Request samples

Content type
application/json
{
  • "query": "string",
  • "sources": [
    ],
  • "style": "string",
  • "imageConfig": {
    },
  • "template": {
    }
}

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string",
  • "data": {
    }
}

通过故事书创建单集视频

通过故事书创建单集视频

Authorizations:
None
path Parameters
episodeId
required
string

单集ID

Responses

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string",
  • "data": {
    }
}

生成故事书资源包

触发故事书资源包（ZIP）的异步生成，包含音频、图片、封面等所有资源文件

Authorizations:
None
path Parameters
episodeId
required
string

单集ID

Responses

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string",
  • "data": {
    }
}

生成故事书PPTX

触发故事书PPTX文件的异步生成，用于演示文稿导出

Authorizations:
None
path Parameters
episodeId
required
string

单集ID

Responses

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string",
  • "data": {
    }
}

获取图片编辑历史

获取故事书的图片编辑历史记录（pageImages）。 如果 pageImages 为空，会从 pages 数组初始化，将原始图片写入。 返回的数组按创建时间倒序排列（最新的在前）。

Authorizations:
None
path Parameters
episodeId
required
string

单集ID

Responses

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string",
  • "data": {
    }
}

生成单张图片（异步）

为故事书的指定页面生成新图片，加入编辑历史记录。 生成过程为异步操作，返回 imageId 用于后续查询状态。 图片生成完成后会更新到 topic.pageImages 数组中。

Authorizations:
None
path Parameters
episodeId
required
string

单集ID

Request Body schema: application/json
required
targetImageIndex
required
integer >= 0

目标页面索引（从0开始）

editQuery
string

编辑提示词（可选）

Array of objects

参考图片列表（可选，用户上传的参考图）

aspectRatio
string
Enum: "1:1" "9:16" "16:9" "4:3" "2:3" "3:2" "3:4" "21:9"

图片宽高比（可选）

size
string
Enum: "2K" "4K"

图片尺寸（可选，默认使用 storybook 创建时的设置）

Responses

Request samples

Content type
application/json
{
  • "targetImageIndex": 0,
  • "editQuery": "string",
  • "referenceImages": [
    ],
  • "aspectRatio": "1:1",
  • "size": "2K"
}

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string",
  • "data": {
    }
}

应用图片到指定页面

将某个图片应用到故事书的指定页面。 图片可以来自 pageImages 编辑历史记录或用户上传的图片URL。

Authorizations:
None
path Parameters
episodeId
required
string

单集ID

index
required
integer >= 0

页面索引（从0开始）

Request Body schema: application/json
required
imageUrl
required
string

要应用的图片URL

Responses

Request samples

Content type
application/json
{
  • "imageUrl": "string"
}

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string",
  • "data": {
    }
}

重试图片生成

当图片生成失败时，用户可以重新触发生成。 只有状态为 fail 的图片记录才能重试。

Authorizations:
None
path Parameters
episodeId
required
string

单集ID

imageId
required
string

图片记录ID（来自 pageImages 数组）

Responses

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string",
  • "data": {
    }
}

上传自定义图片

上传用户自定义图片，直接作为 pageImages 的数据源，不需要 AI 生成。 适用于用户已有图片想要替换页面图片的场景。

Authorizations:
None
path Parameters
episodeId
required
string

单集ID

Request Body schema: application/json
required
targetImageIndex
required
integer >= 0

目标页面索引（从0开始）

imageUrl
required
string <uri>

用户上传的图片URL

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string",
  • "data": {
    }
}

通过文本创建单集

通过文本内容创建单集

Authorizations:
None
Request Body schema: application/json
required
text
required
string

文本内容

enabledDeepSearch
boolean
Default: false

是否开启搜索

deepsearchMode
string
Enum: "deep" "fast"

深度搜索模式

Responses

Request samples

Content type
application/json
{
  • "text": "string",
  • "enabledDeepSearch": false,
  • "deepsearchMode": "deep"
}

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string",
  • "data": {
    }
}

通过URL创建单集

通过URL地址创建单集

Authorizations:
None
Request Body schema: application/json
required
url
required
string

网页地址

duration
string
Default: "short"
Enum: "short" "long"

音频时长

object

模板配置（可选）

Responses

Request samples

Content type
application/json
{
  • "url": "string",
  • "duration": "short",
  • "template": {
    }
}

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string",
  • "data": {
    }
}

通过文件创建单集

通过已上传的文件创建单集

Authorizations:
None
Request Body schema: application/json
required
fileUrl
required
string

已上传的文件地址

fileName
required
string

文件名

Responses

Request samples

Content type
application/json
{
  • "fileUrl": "string",
  • "fileName": "string"
}

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string",
  • "data": {
    }
}

获取视频风格列表

根据语言获取视频风格配置列表，用于 storybook 视频生成时选择风格

path Parameters
language
required
string
Enum: "zh" "en"

语言

Responses

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string",
  • "data": {
    }
}

用户听过单集标记

用户听过单集标记

Authorizations:
None
Request Body schema: application/json
required
playedStatus
integer
Enum: 0 1 -1

状态 0 未播放, 1 已播放, -1 已开始

Responses

Request samples

Content type
application/json
{
  • "playedStatus": 0
}

explore

探索相关接口

获取画廊图片列表

获取公开的画廊图片列表，支持分页

Authorizations:
None
query Parameters
imageId
string

图片 ID（用于定位到特定图片）

page
integer >= 1
Default: 1

页码

pageSize
integer [ 1 .. 100 ]
Default: 10

每页数量

Responses

Response samples

Content type
application/json
{}

获取探索详情 V2

获取探索详情信息

Authorizations:
None
path Parameters
exploreId
required
string

探索ID

Responses

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string",
  • "data": {
    }
}

获取标签列表

获取所有可用的标签列表

Authorizations:
None
query Parameters
language
string
Enum: "zh" "en"

语言

Responses

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string",
  • "data": {
    }
}

获取探索列表

获取探索内容列表,支持分页和标签筛选

Authorizations:
None
query Parameters
page
integer >= 1
Default: 1

页码,从1开始

pageSize
integer [ 1 .. 100 ]
Default: 14

每页数量

tag
string

标签标识(不传则返回全部)

language
string
Enum: "zh" "en"

语言

Responses

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string",
  • "data": {
    }
}

获取探索详情

获取探索详情

Authorizations:
None
path Parameters
exploreId
required
string

探索ID

Responses

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string",
  • "data": {
    }
}

file

文件相关接口

预上传获取授权码

获取文件上传的预签名 URL。支持上传音集文件、用户头像和参考图片

Authorizations:
None
Request Body schema: application/json
required
fileKey
string

文件 key

contentType
string

文件类型

category
string
Default: "episode"
Enum: "episode" "avatar" "banana"

文件分类 (episode=音集, avatar=头像, banana=参考图片)

Responses

Request samples

Content type
application/json
{
  • "fileKey": "string",
  • "contentType": "string",
  • "category": "episode"
}

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string",
  • "data": {
    }
}

获取文件

获取文件

Authorizations:
None
query Parameters
fileUrl
required
any

文件 URL

Responses

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string",
  • "data": {
    }
}

获取 Banana 参考图片上传地址

获取上传参考图片的预签名地址和文件 URL

Authorizations:
None
Request Body schema: application/json
required
contentType
required
string

文件类型（如 image/png）

Responses

Request samples

Content type
application/json
{
  • "contentType": "string"
}

Response samples

Content type
application/json
{
  • "presignedUrl": "string",
  • "fileUrl": "string"
}

engine

引擎相关接口

subscription

订阅相关接口

获取用户订阅

获取用户订阅

Authorizations:
None

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

创建用户订阅

创建用户订阅

Authorizations:
None
Request Body schema: application/json
required
planId
string

订阅计划ID

redirectUrl
string

重定向URL

locale
string

当前界面 locale（如 zh-TW/zh-HK/zh-MO/zh-Hant），用于决定结算货币。 简体中文（zh/zh-CN）走 CNY，繁体中文走 USD；缺省时回落 Accept-Language。

Responses

Request samples

Content type
application/json
{
  • "planId": "string",
  • "redirectUrl": "string",
  • "locale": "zh-TW"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

获取用户订阅管理页

获取用户订阅管理页

Authorizations:
None

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

取消订阅

取消订阅

Authorizations:
None
Request Body schema: application/json
required
planId
string

订阅计划ID

promotionCode
string

优惠码

Responses

Request samples

Content type
application/json
{
  • "planId": "string",
  • "promotionCode": "string"
}

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string",
  • "data": {
    }
}

取消订阅

取消订阅

Authorizations:
None
Request Body schema: application/json
required
subscriptionId
string

订阅ID

Responses

Request samples

Content type
application/json
{
  • "subscriptionId": "string"
}

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string",
  • "data": {
    }
}

获取订阅计划

获取订阅计划

Authorizations:
None
query Parameters
platform
string
Enum: "ios" "android" "web"

平台

Responses

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string",
  • "data": {
    }
}

查询套餐变更信息

查询从当前套餐切换到新套餐的信息，包括变更类型、验证结果和费用计算。

返回信息：

  • 变更类型：upgrade（同周期升级）、downgrade（同周期降级）、duration_change（跨周期变更）、none（相同套餐）
  • 验证结果：是否满足变更条件
  • 验证错误列表：如果不满足条件，返回具体错误信息
  • 费用计算：如果是同周期升级，返回按比例折扣和需支付金额

验证规则：

  • 必须相同货币
  • 必须相同地区
  • 必须相同平台
  • 允许跨周期变更（月付 ↔ 年付）
Authorizations:
None
Request Body schema: application/json
required
newPlanId
required
string

新套餐 ID

Responses

Request samples

Content type
application/json
{
  • "newPlanId": "string"
}

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string",
  • "data": {
    }
}

订阅套餐升级

升级当前订阅套餐到更高价格的套餐。

限制条件：

  • 必须有活跃的订阅
  • 新套餐必须与当前套餐相同货币、相同地区、相同平台、相同周期
  • 新套餐价格必须高于当前套餐

升级规则：

  • 按天计算当前套餐的剩余价值（向上取整，对用户有利）
  • 剩余价值按 70% 作为折扣抵扣
  • 用户需支付差价金额
  • 升级立即生效，计费周期重置
Authorizations:
None
Request Body schema: application/json
required
newPlanId
required
string

新套餐 ID

redirectUrl
string

支付完成后的重定向 URL（可选）

locale
string

当前界面 locale（如 zh-TW/zh-HK/zh-MO/zh-Hant），用于决定升级支付货币。 简体中文（zh/zh-CN）走 CNY 并按汇率换算，繁体中文走 USD 且不换算；缺省时回落 Accept-Language。

Responses

Request samples

Content type
application/json
{
  • "newPlanId": "string",
  • "redirectUrl": "string",
  • "locale": "zh-TW"
}

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string",
  • "data": {
    }
}

订阅套餐降级

降级当前订阅套餐到更低价格的套餐。

限制条件：

  • 必须有活跃的订阅
  • 新套餐必须与当前套餐相同货币、相同地区、相同平台、相同周期
  • 新套餐价格必须低于当前套餐
  • 当前没有已安排的降级

降级规则：

  • 降级不会立即生效
  • 将在当前计费周期结束时生效
  • 降级前用户继续享有当前套餐的所有权益
  • 不产生退款
  • 降级信息记录在 Stripe subscription metadata 中
Authorizations:
None
Request Body schema: application/json
required
newPlanId
required
string

新套餐 ID

Responses

Request samples

Content type
application/json
{
  • "newPlanId": "string"
}

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string",
  • "data": {
    }
}

取消订阅降级

取消已安排的订阅降级。

说明：

  • 只能取消尚未生效的降级
  • 取消后将继续使用当前套餐
  • 下次计费周期仍按当前套餐续费
Authorizations:
None

Responses

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string",
  • "data": {
    }
}

settings

设置相关接口

获取设置

获取设置

Authorizations:
None

Responses

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string",
  • "data": {
    }
}

获取设置 V2

获取设置

Authorizations:
None

Responses

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string",
  • "data": {
    }
}

添加风格图片

为故事书模式添加风格参考图片，系统会自动分析图片并生成风格名称

Authorizations:
None
Request Body schema: application/json
required
type
required
string
Value: "storybook"

设置类型，目前仅支持 storybook

mode
required
string
Enum: "story" "info" "slides"

故事书模式

required
object

Responses

Request samples

Content type
application/json
{
  • "type": "storybook",
  • "mode": "story",
  • "image": {
    }
}

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string",
  • "data": {
    }
}

删除风格图片

删除指定模式下的风格参考图片

Authorizations:
None
path Parameters
type
required
string
Value: "storybook"

设置类型，目前仅支持 storybook

mode
required
string
Enum: "story" "info" "slides"

故事书模式

imageId
required
string

图片唯一标识

Responses

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string",
  • "data": {
    }
}

更新单集配置

更新单集配置

Authorizations:
None
Request Body schema: application/json
required
type
string
Enum: "speech" "podcast-solo" "podcast-duo" "storybook"

类型

duration
string
Enum: "short" "long"

单集时长(废弃)

speakers
Array of strings

主持人列表

language
string
Enum: "zh" "en"

语言

enabledShare
boolean
Default: false

是否开启分享

mode
string
Enum: "quick" "deep" "debate" "smart" "direct" "info" "story" "slides"

模式(smart,direct在type为speech模式下有效; info,story,slides在type为storybook模式下有效)

Responses

Request samples

Content type
application/json
{
  • "type": "speech",
  • "duration": "short",
  • "speakers": [
    ],
  • "language": "zh",
  • "enabledShare": false,
  • "mode": "quick"
}

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string",
  • "data": {
    }
}

获取单集配置(改版)

获取用户的单集配置，支持查询全部或指定 productId 的配置。

功能说明：

  • 不传 productId: 返回用户所有产品的配置（explainerVideo, slideDeck, aiPodcast, textToSpeech, aiImage 等）
  • 传 productId: 只返回指定产品的配置，格式仍然是 { settings: { [productId]: {...} } }
  • 如果用户没有配置或指定的 productId 不存在，返回空的 settings 对象

使用场景：

  • 获取全部配置: GET /v1/episode-settings
  • 获取单个配置: GET /v1/episode-settings?productId=aiPodcast
Authorizations:
None
query Parameters
productId
string^[a-zA-Z][a-zA-Z0-9_]*$
Example: productId=aiPodcast

产品ID（如 explainerVideo, slideDeck, aiPodcast, textToSpeech, aiImage），不传则返回全部。必须以字母开头，只能包含字母、数字、下划线。

Responses

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string",
  • "data": {
    }
}

更新单集配置(改版)

更新指定 productId 的单集配置，支持增量更新。

功能说明：

  • 只更新指定的 productId 配置，不影响其他 productId
  • 支持的 productId：explainerVideo, slideDeck, aiPodcast, textToSpeech, aiImage 等
  • 自动执行 upsert 操作，如果配置不存在则创建

配置说明：

  • speakers 字段按语言和人数组织，支持保存多种组合
  • speakersCount 无数量限制，支持任意人数配置
  • aspectRatio 仅用于视频类型（explainerVideo）
  • style 仅用于 slideDeck

使用场景：

  • 用户切换语言或模式时保存配置
  • 用户更换主持人组合时保存配置
  • 单个产品的配置更新
Authorizations:
None
path Parameters
productId
required
string^[a-zA-Z][a-zA-Z0-9_]*$
Example: aiPodcast

产品ID（如 explainerVideo, slideDeck, aiPodcast, textToSpeech, aiImage）。必须以字母开头，只能包含字母、数字、下划线。

Request Body schema: application/json
required
property name*
additional property
any

Responses

Request samples

Content type
application/json
{
  • "type": "podcast",
  • "mode": "deep",
  • "language": "zh",
  • "speakersCount": 2,
  • "speakers": {
    }
}

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string",
  • "data": {
    }
}

获取主持人列表

获取所有可用的主持人列表

Authorizations:
None
query Parameters
language
string

语言

Responses

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string",
  • "data": {
    }
}

添加 APNS 令牌

添加用户的 APNS (Apple Push Notification Service) 设备令牌，用于接收推送通知。

功能说明：

  • 支持为同一用户添加多个设备令牌（例如 iPhone、iPad）
  • 自动去重，重复添加相同 token 不会创建重复记录
  • 推送通知场景：
    • 内容生成完成通知
    • 积分不足提醒

注意事项：

  • token 参数必填
  • 仅对 iOS 客户端有效
Authorizations:
None
Request Body schema: application/json
required
token
required
string

iOS 设备的 APNS 令牌

Responses

Request samples

Content type
application/json
{
  • "token": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6"
}

Response samples

Content type
application/json
{
  • "success": true
}

删除 APNS 令牌

删除用户的 APNS 设备令牌，停止向该设备发送推送通知。

使用场景：

  • 用户退出登录
  • 用户卸载应用
  • 设备令牌过期或失效

注意事项：

  • 如果 token 不存在，操作仍然返回成功（幂等性）
  • 删除后该设备将不再接收任何推送通知
Authorizations:
None
Request Body schema: application/json
required
token
required
string

要删除的 APNS 令牌

Responses

Request samples

Content type
application/json
{
  • "token": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6"
}

Response samples

Content type
application/json
{
  • "success": true
}

查看 API key

获取当前用户的 API key

Authorizations:
None

Responses

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string",
  • "data": {
    }
}

重新生成 API key

重新生成当前用户的 API key

Authorizations:
None

Responses

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string",
  • "data": {
    }
}

system

系统相关接口

获取应用配置

获取应用配置信息，包含积分奖励配置等系统参数。

积分配置说明：

  • checkinBonus: 每日签到奖励积分
  • inviteSignupBonus: 邀请用户注册奖励积分
  • inviteSubscriptionBonus: 被邀请用户订阅后奖励积分
  • weeklyInviteBonusLimit: 每周邀请奖励积分上限

每项积分配置都包含 free（免费用户）和 active（订阅用户）两种状态的值。

活动期间：积分配置会自动切换为活动配置

Authorizations:
None
query Parameters
platform
required
string
Enum: "ios" "android" "web"

平台类型

Responses

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string",
  • "data": {
    }
}

获取 app 版本

获取 app 版本

Authorizations:
None
query Parameters
type
required
string
Value: "ios"

平台

currentVersion
required
string

当前版本

Responses

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string",
  • "data": {
    }
}

获取所有错误码列表

获取系统所有错误码及其描述信息，用于前端展示和国际化

注意：仅返回 publicVisible: true 的错误码，内部错误码不会暴露给前端

响应格式：

  • 返回一个对象，key 为错误码数字
  • 每个错误码包含嵌套的 message 对象，包含 en 和 zh 字段

示例：

{
  "21001": {
    "message": {
      "en": "Not supported provider type",
      "zh": "错误的身份提供商"
    }
  }
}
Authorizations:
None

Responses

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string",
  • "data": {
    }
}

invite-code

邀请码相关接口

获取邀请码及每周奖励信息

获取当前用户的邀请码（如不存在则自动生成）及每周奖励统计信息

Authorizations:
None

Responses

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string",
  • "data": {
    }
}

验证邀请码

新用户验证邀请码并发放奖励

Authorizations:
None
Request Body schema: application/json
required
inviteCode
required
string

邀请码

platform
required
string
Enum: "listenhub" "nextlab" "banana-lab"

平台类型

Responses

Request samples

Content type
application/json
{
  • "inviteCode": "string",
  • "platform": "listenhub"
}

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string",
  • "data": {
    }
}

utils

工具相关接口

获取URL预览

获取URL预览

Authorizations:
None
query Parameters
url
required
string

URL

Responses

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string",
  • "data": {
    }
}

events

获取事件列表

获取事件列表

Authorizations:
None
path Parameters
episodeId
required
string

单集 ID

Responses

Response samples

Content type
application/json
[
  • {
    }
]

批量获取所有非流式事件

批量获取所有非流式事件

Authorizations:
None
path Parameters
episodeId
required
string

单集 ID

Request Body schema: application/json
required
events
Array of strings (EventType)
Items Enum: "title_generate" "source_generate" "script_generate" "audio_generate" "outline_generate"

Responses

Request samples

Content type
application/json
{
  • "events": [
    ]
}

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string",
  • "data": {
    }
}

获取流式事件

获取流式事件

Authorizations:
None
path Parameters
episodeId
required
string

单集 ID

eventName
required
string

事件名称

Responses

Response samples

Content type
text/event-stream
data: {"code": 0, "message": "", "chunk": "xxxx"}
data: {"code": 0, "message": "", "chunk": "[[END]]"}
data: {"code": 0, "message": "", "chunk": "[[ERROR]]"}

voice-clone

音色克隆相关接口

多轮对话式录音引导

用于对话式音色克隆的交互接口，支持多轮对话引导用户录音。

流程说明：

  1. 首次调用：传入 language，context 为空，不传 audioFile，返回引导语音频
  2. 后续调用：用户录音后直接上传原始音频文件 (multipart/form-data)
  3. API 处理：接收文件 → 读取 Buffer → 通过 Synapse 传 base64 给 multimodal-engine
  4. Engine 处理：解码 base64 → ASR 识别 → LLM 生成回复 → TTS 转语音 → Base64 编码
  5. 返回响应：返回 base64 编码的音频数据（data URI 格式），前端直接播放
  6. 达到阈值：端调用 /clone 接口上传合并后的音频文件，触发克隆
Authorizations:
None
Request Body schema: multipart/form-data
required
language
required
string
Enum: "zh" "en"

语言类型

audioFile
string <binary>

用户录音文件 (首次调用不传)

context
string

对话历史 JSON 字符串 (首次调用传空数组或不传)

isEnd
boolean

是否结束对话

guideAudioIndex
number

引导音频 Index

taskId
string

克隆任务 ID (仅供后续 /clone 接口使用，chat 接口不处理)

Responses

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "success",
  • "data": {
    }
}

创建音色克隆任务

上传音频文件进行音色克隆，支持单个文件或多个音频片段（1-6 个）。

流程说明：

  1. 端上传原始文件：端直接上传原始音频文件 (multipart/form-data)，支持单个文件或多个片段（最多 6 个），不上传 GCS
  2. API 处理：接收文件 → 验证大小（单个最大 5MB，总计最大 20MB）→ 读取 Buffer → 通过 Synapse 传 base64 给 multimodal-engine → 创建任务，返回 taskId
  3. Engine 处理：解码 base64 → 如果是多个文件则自动合并 → 预处理（格式检测/转换）→ 调用克隆服务（中文 MiniMax，英文 Hume）→ 下载试听音频上传到 GCS
  4. 状态查询：通过 GET /clone/{taskId} 轮询查询状态
  5. 支持格式：PCM、WebM、MP4、WAV、MP3、M4A 等

文件限制：

  • 文件数量：1-6 个
  • 单个文件大小：最大 5MB
  • 总文件大小：最大 20MB
  • 建议每个片段：10-30 秒
  • 建议总时长：1-3 分钟
Authorizations:
None
Request Body schema: multipart/form-data
required
required
string or Array of strings

音频文件或音频片段数组

  • 单个文件：直接上传一个音频文件
  • 多个片段：上传 2-6 个音频片段，Engine 会自动合并
  • 单个文件最大 5MB
  • 总文件大小最大 20MB
language
required
string
Enum: "zh" "en"

音频语言

mode
string
Enum: "upload" "chat"

任务模式 - upload（文件上传克隆）或 chat（对话克隆），可选参数

Responses

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "success",
  • "data": {
    }
}

查询克隆任务状态

查询指定任务的克隆状态和结果。

状态说明：

  • pending: 任务已创建，等待处理
  • processing: 正在处理中
  • completed: 克隆完成，可获取 demoAudioUrl 和 thirdPartyId
  • failed: 克隆失败
Authorizations:
None
path Parameters
taskId
required
string
Example: 6915bde9cca4d3c8ecb3eaf5

克隆任务 ID

Responses

Response samples

Content type
application/json
{}

获取已确认的音色列表

获取用户已确认使用的音色列表，按创建时间倒序排列。 只返回通过 /confirm 接口确认的音色。

Authorizations:
None

Responses

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "success",
  • "data": {
    }
}

获取音色详情

获取指定音色的详细信息

Authorizations:
None
path Parameters
speakerId
required
string
Example: 6915c123cca4d3c8ecb3eaf6

音色 ID

Responses

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "success",
  • "data": {}
}

编辑音色信息

更新音色的名称和性别信息

Authorizations:
None
path Parameters
speakerId
required
string
Example: 6915c123cca4d3c8ecb3eaf6

音色 ID

Request Body schema: application/json
required
name
string

音色名称

gender
string
Enum: "male" "female" "other"

性别

Responses

Request samples

Content type
application/json
{
  • "name": "My Updated Voice",
  • "gender": "male"
}

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "success",
  • "data": {
    }
}

删除音色

删除指定的音色

Authorizations:
None
path Parameters
speakerId
required
string
Example: 6915c123cca4d3c8ecb3eaf6

音色 ID

Responses

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "success",
  • "data": {
    }
}

确认使用音色

将临时克隆任务转为永久音色记录。

流程说明：

  1. 用户在试听页面播放试听音频
  2. 点击 "Confirm Use" 按钮
  3. 填写 Name 和 Gender
  4. 首次调用此接口（不传 useCredits 或 useCredits=false）
  5. 如果免费次数已用完，返回错误码 27015，前端弹窗询问用户是否使用积分
  6. 用户同意后，再次调用接口并传入 useCredits=true
  7. 音色保存成功，可用于内容生成

可能的错误码：

  • 27001: 任务不存在或已过期
  • 27002: 任务尚未完成
  • 27007: 任务已确认
  • 27010: 音色永久保存失败（T2A 失败）
  • 27015: 免费次数已用完，需要使用积分（返回此错误后，前端应弹窗提示，用户同意后传入 useCredits=true 重新调用）
  • 26004: 积分不足（当 useCredits=true 且积分不足 300 时）
Authorizations:
None
Request Body schema: application/json
required
taskId
required
string

克隆任务 ID

name
required
string

音色名称

gender
required
string
Enum: "male" "female" "other"

性别

useCredits
boolean

是否使用积分确认（当免费次数用完时需要传 true）

Responses

Request samples

Content type
application/json
{
  • "taskId": "6915bde9cca4d3c8ecb3eaf5",
  • "name": "My Voice",
  • "gender": "male",
  • "useCredits": false
}

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "success",
  • "data": null
}

获取示例音色列表

获取预设的示例音色列表，用于展示克隆前后对比效果。 示例数据由后端写死，不需要用户创建。 支持按语言筛选，默认返回中文示例。

Authorizations:
None
query Parameters
language
string
Default: "zh"
Enum: "zh" "en"
Example: language=zh

语言（zh=中文, en=英文），默认 zh

Responses

Response samples

Content type
application/json
{}

image

AI 图像生成相关接口

预估图片生成所需积分

根据模型、尺寸、宽高比、质量等参数预估生成图片所需的积分，并返回订阅/权益提示。

Authorizations:
None
Request Body schema: application/json
required
model
string
Default: "gpt-image-2"

图片模型（如 gpt-image-2 / gpt-image-2-official / wan2.7-image 等）

imageSize
string
Default: "2K"
Enum: "1K" "2K" "4K"

分辨率档位

aspectRatio
string
Default: "1:1"
Enum: "1:1" "1:4" "1:8" "2:3" "3:2" "3:4" "4:1" "4:3" "8:1" "9:16" "16:9" "21:9"

宽高比

quality
string
Enum: "low" "medium" "high"

质量档位（仅 gpt-image-2-official Pro 生效，Lite 忽略）

prompt
string

图像描述（用于估算输入 token）

referenceImageCount
integer [ 0 .. 4 ]
Default: 0

参考图数量

enableSearch
boolean
Default: false

Responses

Request samples

Content type
application/json
{
  • "model": "gpt-image-2",
  • "imageSize": "1K",
  • "aspectRatio": "1:1",
  • "quality": "low",
  • "prompt": "string",
  • "referenceImageCount": 0,
  • "enableSearch": false
}

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string",
  • "data": {
    }
}

生成图片

创建 AI 图片生成任务

Authorizations:
None
Request Body schema: application/json
required
prompt
required
string

图像描述

referenceImageUrls
Array of strings <= 5 items

参考图像 URL 列表（最多 5 张；gpt-image-2 的 URL 与 Base64 参考图合计最多 4 张）

Array of objects <= 5 items

Base64 参考图列表（最多 5 张；gpt-image-2 的 URL 与 Base64 参考图合计最多 4 张）

imageSize
string
Default: "2K"
Enum: "1K" "2K" "4K"

图像尺寸

aspectRatio
string
Default: "1:1"
Enum: "1:1" "1:4" "1:8" "2:3" "3:2" "3:4" "4:1" "4:3" "8:1" "9:16" "16:9" "21:9"

宽高比。gpt-image-2 支持 1:1、2:3、3:2、3:4、4:3、9:16、16:9、21:9；1:4、4:1、1:8、8:1 仅 gemini-3.1-flash-image 模型支持。

language
string
Default: "auto"
Enum: "auto" "en" "ja" "ko" "hi" "zh" "pt" "es"

提示词语言

isLossless
boolean
Default: true

是否无损

isRetry
boolean
Default: false

是否为重试请求

model
string
Default: "gemini-3-pro-image"
Enum: "gemini-3-pro-image" "gemini-3.1-flash-image" "gpt-image-2"

图片生成模型。gpt-image-2 使用 OpenDev/OpenAI 通道，1K/2K 会先尝试使用免费额度。

enableSearch
boolean
Default: false

是否开启 Google Search（开启后模型可联网检索参考信息）

Responses

Request samples

Content type
application/json
{
  • "prompt": "一个美丽的日落风景",
  • "referenceImageUrls": [
    ],
  • "referenceImageBase64": [
    ],
  • "imageSize": "1K",
  • "aspectRatio": "1:1",
  • "language": "auto",
  • "isLossless": true,
  • "isRetry": false,
  • "model": "gemini-3-pro-image",
  • "enableSearch": false
}

Response samples

Content type
application/json
{
  • "imageId": "string"
}

获取我的图库

获取当前用户生成的所有图片列表（分页）

Authorizations:
None
query Parameters
page
integer >= 1
Default: 1

页码,从1开始

pageSize
integer [ 1 .. 50 ]
Default: 20

每页数量（最大 50）

keyword
string

搜索当前用户自己的图片 prompt，大小写不敏感；服务端会 trim 并截断到 100 字符

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "pagination": {
    }
}

批量删除图片

批量逻辑删除指定 ID 的图片（仅删除本人图片，单批最多 100 个）

Authorizations:
None
Request Body schema: application/json
required
ids
required
Array of strings <= 100 items

要删除的图片 ID 列表

Responses

Request samples

Content type
application/json
{
  • "ids": [
    ]
}

Response samples

Content type
application/json
{
  • "success": true
}

获取图片详情

获取指定图片的详细信息

权限规则：

  • 本人创建的图片：无论是否公开，都可以访问
  • 他人创建的公开图片（isPublic=true）：可以访问
  • 他人创建的私有图片（isPublic=false）：不允许访问，返回 403 错误
Authorizations:
None
path Parameters
imageId
required
string^[0-9a-fA-F]{24}$

图片 ID

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "userId": "string",
  • "prompt": "string",
  • "referenceImageUrls": [
    ],
  • "imageUrl": "string",
  • "thumbnailUrl": "string",
  • "aspectRatio": "string",
  • "imageSize": "string",
  • "language": "string",
  • "isPublic": true,
  • "status": "pending",
  • "tags": [
    ],
  • "createdAt": 0,
  • "updatedAt": 0,
  • "creator": {
    }
}

删除图片

逻辑删除指定的图片

Authorizations:
None
path Parameters
imageId
required
string^[0-9a-fA-F]{24}$

图片 ID

Responses

Response samples

Content type
application/json
{
  • "success": true
}

预估 Banana 图片生成所需积分

根据模型、尺寸、宽高比、质量等参数预估生成图片所需的积分，并返回订阅/权益提示。

Authorizations:
None
Request Body schema: application/json
required
model
string
Default: "gpt-image-2"

图片模型（如 gpt-image-2 / gpt-image-2-official / wan2.7-image 等）

imageSize
string
Default: "2K"
Enum: "1K" "2K" "4K"

分辨率档位

aspectRatio
string
Default: "1:1"
Enum: "1:1" "1:4" "1:8" "2:3" "3:2" "3:4" "4:1" "4:3" "8:1" "9:16" "16:9" "21:9"

宽高比

quality
string
Enum: "low" "medium" "high"

质量档位（仅 gpt-image-2-official Pro 生效，Lite 忽略）

prompt
string

图像描述（用于估算输入 token）

referenceImageCount
integer [ 0 .. 4 ]
Default: 0

参考图数量

enableSearch
boolean
Default: false

Responses

Request samples

Content type
application/json
{
  • "model": "gpt-image-2",
  • "imageSize": "1K",
  • "aspectRatio": "1:1",
  • "quality": "low",
  • "prompt": "string",
  • "referenceImageCount": 0,
  • "enableSearch": false
}

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string",
  • "data": {
    }
}

生成 Banana 图片

创建 Banana 图片生成任务

Authorizations:
None
Request Body schema: application/json
required
prompt
required
string

图像描述

referenceImageUrls
Array of strings <= 14 items

参考图像 URL 列表（最多 14 张；gpt-image-2 最多 4 张）

language
string
Default: "auto"
Enum: "auto" "en" "ja" "ko" "hi" "zh" "pt" "es"

提示词语言

imageSize
string
Default: "2K"
Enum: "1K" "2K" "4K"

图像尺寸

aspectRatio
string
Default: "1:1"
Enum: "1:1" "1:4" "1:8" "2:3" "3:2" "3:4" "4:1" "4:3" "8:1" "9:16" "16:9" "21:9"

宽高比。gpt-image-2 支持 1:1、2:3、3:2、3:4、4:3、9:16、16:9、21:9；1:4、4:1、1:8、8:1 仅 gemini-3.1-flash-image 模型支持。

isPublic
boolean
Default: false

是否公开（免费用户不可公开）

isLossless
boolean
Default: true

是否无损

isRetry
boolean
Default: false

是否为重试请求（为 true 时需传 rootImageId）

model
string
Default: "gemini-3-pro-image"
Enum: "gemini-3-pro-image" "gemini-3.1-flash-image" "gpt-image-2"

图片生成模型。gpt-image-2 使用 OpenDev/OpenAI 通道，1K/2K 会先尝试使用免费额度。

enableSearch
boolean
Default: false

是否开启 Google Search（开启后模型可联网检索参考信息）

rootImageId
string^[0-9a-fA-F]{24}$

源图片 ID（重试时必填）

Responses

Request samples

Content type
application/json
{
  • "prompt": "string",
  • "referenceImageUrls": [
    ],
  • "language": "auto",
  • "imageSize": "1K",
  • "aspectRatio": "1:1",
  • "isPublic": false,
  • "isLossless": true,
  • "isRetry": false,
  • "model": "gemini-3-pro-image",
  • "enableSearch": false,
  • "rootImageId": "string"
}

Response samples

Content type
application/json
{
  • "imageId": "string"
}

获取 Banana 图片列表

获取当前用户图片或公开图片列表（分页）

Authorizations:
None
query Parameters
imageId
string^[0-9a-fA-F]{24}$

图片 ID（用于筛选）

status
string
Enum: "pending" "success" "fail"

图片生成状态（仅 scope=me 生效）

scope
string
Default: "me"
Enum: "me" "public"

搜索范围：

  • me: 搜索当前用户的图片
  • public: 搜索所有公开图片
page
integer >= 1
Default: 1

页码，从1开始

pageSize
integer [ 1 .. 100 ]
Default: 10

每页数量（最大 100）

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "pagination": {
    }
}

批量删除 Banana 图片

逻辑删除指定的图片

Authorizations:
None
Request Body schema: application/json
required
imageIds
required
Array of strings[ items^[0-9a-fA-F]{24}$ ]

图片 ID 列表

Responses

Request samples

Content type
application/json
{
  • "imageIds": [
    ]
}

Response samples

Content type
application/json
{
  • "success": true
}

更新 Banana 图片公开状态

更新指定图片的公开状态

Authorizations:
None
Request Body schema: application/json
required
imageId
required
string^[0-9a-fA-F]{24}$

图片 ID

isPublic
required
boolean

是否公开

Responses

Request samples

Content type
application/json
{
  • "imageId": "string",
  • "isPublic": true
}

Response samples

Content type
application/json
{
  • "success": true
}

搜索图片

根据提示词关键字搜索图片，支持多种搜索范围：

  • scope=public（默认）：搜索所有公开图片
  • scope=me：搜索当前用户自己的图片（公开和非公开）
Authorizations:
None
query Parameters
keyword
required
string [ 1 .. 300 ] characters

搜索关键词

scope
string
Default: "public"
Enum: "me" "public"

搜索范围：

  • me: 搜索当前用户的图片
  • public: 搜索所有公开图片（默认）
page
integer >= 1
Default: 1

页码，从1开始

pageSize
integer [ 1 .. 50 ]
Default: 10

每页数量（最大 50）

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "pagination": {
    }
}

获取探索标签

获取 Banana 探索标签列表

Authorizations:
None
query Parameters
language
required
string
Example: language=en

语言（不支持时默认使用 en）

type
required
string
Enum: "explore" "featured"

标签类型

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

批量获取精选图片

批量获取多个标签的精选图片

Authorizations:
None
query Parameters
tags
required
string
Example: tags=all,portrait,landscape

标签 key 列表（逗号分隔）

pageSize
integer [ 1 .. 50 ]
Default: 10

每个标签返回数量（最大 50）

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

获取指定用户的公开图片列表

获取指定用户的公开图片（仅返回公开且审核通过的图片）

Authorizations:
None
path Parameters
userId
required
string^[0-9a-fA-F]{24}$

用户 ID

query Parameters
page
integer >= 1
Default: 1

页码，从1开始

pageSize
integer [ 1 .. 100 ]
Default: 10

每页数量（最大 100）

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "pagination": {
    }
}

收藏图片

将指定的图片添加到用户的收藏列表

Authorizations:
None
path Parameters
imageId
required
string^[0-9a-fA-F]{24}$

图片 ID

Responses

Response samples

Content type
application/json
{
  • "success": true
}

取消收藏图片

将指定的图片从用户的收藏列表中移除

Authorizations:
None
path Parameters
imageId
required
string^[0-9a-fA-F]{24}$

图片 ID

Responses

Response samples

Content type
application/json
{
  • "success": true
}

获取用户收藏列表

获取当前用户收藏的所有图片列表（分页）

Authorizations:
None
query Parameters
page
integer >= 1
Default: 1

页码，从1开始

pageSize
integer [ 1 .. 100 ]
Default: 10

每页数量（最大 100）

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "pagination": {
    }
}

user-assets

用户资产相关接口

获取用户资产列表

获取用户的 episodes 和 images 合并列表，按创建时间降序排序。 使用基于索引的游标分页，前端每次请求带回上次返回的 episodeIndex 和 imageIndex。

Authorizations:
None
query Parameters
pageSize
integer [ 1 .. 50 ]
Default: 20

每页数量，默认20，最大50

episodeIndex
integer >= 0
Default: 0

Episode 起始索引，首次请求传0

imageIndex
integer >= 0
Default: 0

Image 起始索引，首次请求传0

Responses

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string",
  • "data": {
    }
}

获取用户正在生成的任务数量

返回当前登录用户在 AI 图片、AI 视频、AI 语音三条产品线中"正在生成"的任务数量， 供前端侧边栏角标轮询展示。图片以 status=pending 计数；视频/语音以 pending/generating/uploading 计数。

Authorizations:
None

Responses

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string",
  • "data": {
    }
}

zhihu

知乎播客相关接口

获取知乎播客列表

获取知乎播客列表，支持分页和状态筛选

Authorizations:
None
query Parameters
status
string
Enum: "pending" "processing" "success" "failed"

播客状态筛选

page
integer >= 1
Default: 1

页码，从1开始

limit
integer [ 1 .. 100 ]
Default: 20

每页数量

Responses

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string",
  • "data": {
    }
}

获取单个知乎播客详情

获取指定ID的知乎播客详细信息

Authorizations:
None
path Parameters
id
required
string

播客ID

Responses

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string",
  • "data": {
    }
}

music

音乐生成相关接口

创建音乐生成任务

异步创建音乐生成任务，返回 taskId 用于后续查询。

默认 provider：default 当前解析为 Mureka。

模型：model 使用 provider-neutral 合同。Mureka 支持 auto、mureka-7.6、mureka-8、mureka-9、mureka-o2；Suno 支持 V4、V4_5、V4_5PLUS、V4_5ALL、V5、V5_5。

积分消耗：按 model 档位扣费。 积分在创建时预占，生成成功后确认扣除，失败则自动退回。

异步流程：

  1. 创建任务，返回 202 + taskId
  2. 系统调用音乐生成服务
  3. 服务通过回调通知结果
  4. 系统下载音频转存 S3
  5. 客户端轮询 GET /v1/music/tasks/{taskId} 获取结果
Authorizations:
None
Request Body schema: application/json
required
provider
string
Default: "default"
Enum: "default" "mureka" "suno"

音乐生成服务提供商

model
string
Default: "auto"
Enum: "auto" "mureka-7.6" "mureka-8" "mureka-9" "mureka-o2" "V4" "V4_5" "V4_5PLUS" "V4_5ALL" "V5" "V5_5"

模型版本。Mureka/default 默认 auto；Suno 默认 V5_5。

prompt
string <= 1024 characters

生成提示/风格描述。 Mureka provider 时映射到 Mureka prompt；Suno provider 保持既有语义。

lyrics
string <= 3000 characters

歌词文本。 Mureka provider 非纯器乐生成时必填，映射到 Mureka lyrics。

style
string <= 200 characters

音乐风格标签。Mureka provider 下作为 prompt 的 fallback。

title
string <= 100 characters

歌曲标题

customMode
boolean
Default: true

自定义模式（可指定 style/title/prompt）vs 简单模式（仅 prompt）

instrumental
boolean
Default: false

是否为纯器乐（无人声）

vocalId
string

Mureka Vocal ID（平台配置或 vocal-clone 产物，仅 Mureka generate 支持）

object

Provider 特有参数

Responses

Request samples

Content type
application/json
{
  • "provider": "default",
  • "model": "auto",
  • "prompt": "r&b, slow, passionate, male vocal\n",
  • "lyrics": "[verse]\nWalking down the empty street at night\n[chorus]\nFeel the rhythm, feel the light\n",
  • "style": "jazz, mellow, acoustic",
  • "title": "Night Walk",
  • "customMode": true,
  • "instrumental": false,
  • "vocalId": "string",
  • "providerParams": {
    }
}

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string",
  • "data": {
    }
}

创建翻唱任务

上传一段音频，用新风格重新演绎，保留核心旋律。

积分消耗：与 generate 一致，按 model 档位扣费。

uploadUrl：支持外部可访问 URL 或通过 POST /v1/files 获取的内部 GCS URL。 内部 URL 会自动校验文件归属并生成临时下载链接。

异步流程：与 generate 一致。

Authorizations:
None
Request Body schema: application/json
required
provider
required
string
Value: "default"
uploadUrl
required
string <uri>

音频文件 URL（外部可访问或内部 GCS）

model
required
string
Enum: "V4" "V4_5" "V4_5PLUS" "V4_5ALL" "V5" "V5_5"
customMode
required
boolean
instrumental
required
boolean
prompt
string

歌词（customMode=true + instrumental=false 时必填）

style
string

音乐风格（customMode=true 时必填）

title
string

歌曲标题（customMode=true 时必填）

providerParams
object

Provider 特有参数（negativeTags, vocalGender, personaId, personaModel, styleWeight, weirdnessConstraint, audioWeight）

Responses

Request samples

Content type
application/json
{
  • "provider": "default",
  • "uploadUrl": "http://example.com",
  • "model": "V4",
  • "customMode": true,
  • "instrumental": true,
  • "prompt": "string",
  • "style": "string",
  • "title": "string",
  • "providerParams": { }
}

Response samples

Content type
application/json
{
  • "code": 0,
  • "data": {
    }
}

[DISCONTINUED] 创建混音任务 Deprecated

此接口已停用，返回 410 Gone。

原功能：混合两段音频，生成全新音轨。该功能已不再支持。

Authorizations:
None

Responses

创建 remix 任务

上传音频并提供新歌词，通过 Mureka 生成 remix。

音频来源（三选一，必须且只能选一）：

  • audio — 直接上传音频文件（mp3/m4a，最大 10MB）
  • audioUrl — 内部 ListenHub 音频 URL（须归属当前用户或公开）
  • providerSongId — Mureka song_id（来自之前的生成结果）
Authorizations:
None
Request Body schema: multipart/form-data
audio
string <binary>

音频文件（mp3/m4a，最大 10MB）。与 providerSongId 和 audioUrl 互斥。

providerSongId
string

Mureka song_id（来自之前的生成结果）。与 audio 和 audioUrl 互斥。

audioUrl
string

内部 ListenHub 音频 URL（须归属当前用户或公开）。与 audio 和 providerSongId 互斥。

lyrics
required
string

新歌词（必填）

prompt
string

风格/流派描述

Responses

Response samples

Content type
application/json
{
  • "taskId": "string",
  • "taskType": "GENERATE",
  • "status": "pending"
}

创建音乐延伸任务

基于一段已有音频，从指定时间点继续延伸生成新内容。

积分消耗：与 generate 一致，按 model 档位扣费。

音频来源（三选一）：

  • uploadUrl / audio（文件上传）— Suno provider 使用 uploadUrl（URL），Mureka 可用 audio 文件上传或 providerSongId
  • providerSongId — Mureka provider，直接引用之前生成的 song_id

异步流程：与 generate 一致。

Authorizations:
None
Request Body schema:
required
provider
string
Default: "default"
Enum: "default" "mureka" "suno"

音乐生成服务提供商

audio
string <binary>

音频文件（mp3/m4a，最大 10MB）。Mureka provider 专用，与 providerSongId / uploadUrl 互斥。

uploadUrl
string <uri>

音频文件 URL（任意可访问的外部链接或内部 GCS URL）。Suno provider 必填。

providerSongId
string

Mureka provider 的 song_id（来自之前的生成结果）。与 audio / uploadUrl 互斥。

model
string
Enum: "auto" "mureka-7.6" "mureka-8" "V4" "V4_5" "V4_5PLUS" "V4_5ALL" "V5" "V5_5"

Mureka 支持 auto/mureka-7.6/mureka-8；Suno 支持 V4...V5_5

continueAt
number > 0

Suno provider — 从音频的哪个时间点（秒）开始延伸

extendAt
number [ 8 .. 420 ]

Mureka provider — 从音频的哪个时间点（秒）开始延伸

extendType
string
Default: "tail"
Enum: "tail" "head"

Mureka provider — 延伸方向（tail 向后 / head 向前，head 仅 mureka-8）

lyrics
string

Mureka provider — 新增段落的歌词

prompt
string

歌词（Suno provider）或风格描述

style
string

音乐风格

title
string

歌曲标题

instrumental
boolean

是否纯器乐（无人声）

negativeTags
string

排除的风格标签（逗号分隔）

vocalGender
string
Enum: "m" "f"

人声性别

styleWeight
number [ 0 .. 1 ]

风格权重

weirdnessConstraint
number [ 0 .. 1 ]

创意约束度

audioWeight
number [ 0 .. 1 ]

参考音频权重

Responses

Request samples

Content type
No sample

Response samples

Content type
application/json
{
  • "code": 0,
  • "data": {
    }
}

识别歌词

上传音频，转写带时间戳的歌词分段。同步返回。

Authorizations:
None
Request Body schema: multipart/form-data
audio
required
string <binary>

音频文件（mp3/m4a，最大 10MB）

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

分析音频

上传音频，返回音乐描述、标签、流派与乐器。同步返回。

Authorizations:
None
Request Body schema: multipart/form-data
audio
required
string <binary>

待分析音频文件（mp3/m4a，最大 10MB）

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

分离音轨（stem）

上传音频，分离为人声/贝斯/鼓/其他等音轨，返回 ZIP 下载地址。同步返回。

Authorizations:
None
Request Body schema: multipart/form-data
audio
required
string <binary>

待分离音频文件（mp3/m4a，最大 10MB）

model
string
Default: "audio-separation-1"
Enum: "audio-separation-1" "audio-separation-2"

分离模型；audio-separation-2 额外产出 MIDI

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

生成纯音乐（伴奏）

通过 prompt 或参考音频生成纯音乐。prompt 与 referenceAudio 二选一，互斥。 异步任务，通过 GET /v1/music/tasks/{taskId} 轮询结果。

Authorizations:
None
Request Body schema: multipart/form-data
prompt
string

风格/流派描述。与 referenceAudio 互斥。

referenceAudio
string <binary>

参考音频文件（mp3/m4a，最大 10MB）。与 prompt 互斥。

model
string
Default: "auto"
Enum: "auto" "mureka-7.6" "mureka-8" "mureka-o2"

模型版本（instrumental 不支持 mureka-9）

Responses

Response samples

Content type
application/json
{
  • "taskId": "string",
  • "taskType": "GENERATE",
  • "status": "pending"
}

图片/视频生成配乐

根据图片或视频生成配乐。image 与 video 二选一，互斥。 异步任务，通过 GET /v1/music/tasks/{taskId} 轮询结果。

Authorizations:
None
Request Body schema: multipart/form-data
image
string <binary>

图片文件（jpg/jpeg/png/webp）。与 video 互斥。

video
string <binary>

视频文件（mp4/mov/avi/mkv/webm）。与 image 互斥。

prompt
string
model
string
Default: "auto"
Enum: "auto" "mureka-7.6" "mureka-8" "mureka-9"

Responses

Response samples

Content type
application/json
{
  • "taskId": "string",
  • "taskType": "GENERATE",
  • "status": "pending"
}

生成单条乐器音轨

基于参考音频或已有 song_id 生成单条乐器/人声音轨。 audio 与 providerSongId 二选一，互斥。异步任务，轮询 GET /v1/music/tasks/{taskId}。

Authorizations:
None
Request Body schema: multipart/form-data
audio
string <binary>

参考音频文件（mp3/m4a/wav，最大 10MB）。与 providerSongId 互斥。

providerSongId
string

Mureka song_id（来自之前的生成结果）。与 audio 互斥。

generateType
required
string
Enum: "Vocals" "Instrumental" "Drums" "Bass" "Guitar" "Keyboard" "Percussion" "Strings" "Synth" "FX" "Brass" "Woodwinds"

目标乐器/音轨类型

prompt
string

风格/流派描述（必填）

lyrics
string

当 generateType 为 Vocals 时必填

vocalGender
string
Enum: "male" "female"

人声性别（仅 generateType=Vocals）

generateStart
number

起始时间（秒，可选）

generateEnd
number

结束时间（秒，可选）

Responses

Response samples

Content type
application/json
{
  • "taskId": "string",
  • "taskType": "GENERATE",
  • "status": "pending"
}

查询音乐任务列表

分页查询当前用户的音乐生成任务列表，按创建时间倒序。

Authorizations:
None
query Parameters
page
integer >= 1
Default: 1
pageSize
integer [ 1 .. 50 ]
Default: 20
status
string
Enum: "pending" "generating" "uploading" "success" "failed"

按状态过滤

keyword
string

搜索当前用户自己的视频任务标题；当前标题由文本 prompt 派生，大小写不敏感；服务端会 trim 并截断到 100 字符

Responses

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string",
  • "data": [
    ]
}

查询音乐任务详情

查询指定任务的详细信息，只能查询自己的任务。

Authorizations:
None
path Parameters
taskId
required
string

音乐任务 ID

Responses

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string",
  • "data": {
    }
}

音乐生成回调端点

供音乐生成服务异步回调使用，无需用户认证（skipAuth）。 通过 URL query 参数中的 HMAC token 验证请求合法性。 中间回调（如 TEXT_SUCCESS）静默处理，仅最终结果触发状态变更。

Authorizations:
None
query Parameters
token
required
string

HMAC 验证 token（创建任务时生成）

Request Body schema: application/json
required
object

回调 payload（格式由 provider 定义）

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string",
  • "data": {
    }
}

Suno 音乐生成回调端点

供 Suno 音乐生成服务异步回调使用，无需用户认证（skipAuth）。 通过 URL query 参数中的 HMAC token 验证请求合法性。 中间回调（如 TEXT_SUCCESS）静默处理，仅最终结果触发状态变更。

Authorizations:
None
query Parameters
token
required
string

HMAC 验证 token（创建任务时生成）

Request Body schema: application/json
required
object

回调 payload（格式由 Suno provider 定义）

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string",
  • "data": {
    }
}

video-generation

AI 视频生成相关接口

创建视频生成任务

异步创建视频生成任务，返回 taskId 用于后续轮询。

支持四种模式：

  • 文生视频：content 仅含 text
  • 图生视频：content 含 image_url（role: first_frame/last_frame）
  • 多模态参考生视频：content 含 image_url/video_url/audio_url（role: reference_*）
  • 视频生视频：content 含 video_url（role: reference_video），需指定 inputVideoDuration

积分消耗：按 model × resolution × duration 计费，创建时即时扣除，失败自动退还。

频率限制：按用户和模型族限流，SeedDance 为 2 RPM，HappyHorse 为 5 RPM。

异步流程：

  1. 创建任务，返回 202 + taskId
  2. 系统提交至 SeeDance / HappyHorse API
  3. 系统异步轮询生成结果
  4. 生成完成后转存 GCS
  5. 客户端轮询 GET /v1/video-generation/tasks/{taskId} 获取结果
Authorizations:
None
Request Body schema: application/json
required
model
string
Default: "fast"
Enum: "pro" "fast" "happyhorse"

模型档位（pro 高质量，fast 快速，happyhorse HappyHorse 模型）

required
Array of objects or objects or objects or objects [ 1 .. 16 ] items

输入内容数组，支持混合类型：

  • text: 文本提示词（最多 1 个，max 2500 字符；Seedance 模型限 1500 字符）
  • image_url: 图片 URL（最多 9 个，role: first_frame/last_frame/reference_image）
  • video_url: 视频 URL（最多 3 个，role: reference_video）
  • audio_url: 音频 URL（最多 3 个，role: reference_audio，需搭配 image 或 video）
resolution
string
Default: "720p"
Enum: "480p" "720p" "1080p"

视频分辨率

ratio
string
Default: "16:9"
Enum: "16:9" "4:3" "1:1" "3:4" "9:16" "21:9" "4:5" "5:4"

视频宽高比

duration
integer [ 3 .. 15 ]
Default: 5

生成视频时长（秒）

generateAudio
boolean
Default: true

是否同时生成音频

seed
integer [ -1 .. 4294967295 ]
Default: -1

随机种子（-1 为随机）

inputVideoDuration
integer [ 0 .. 60 ]
Default: 0

输入视频时长（秒），有 video_url 输入时必须 >= 2；Seedance 最大 15 秒，HappyHorse 最大 60 秒

audioSetting
string
Default: "auto"
Enum: "auto" "origin"

音频设置（仅 video-edit 有效）。auto=模型生成音频，origin=保留原视频音频

Array of objects <= 9 items

参考图尺寸元数据。Seedance 2.0 reference_image 官方要求 width/height 单边在 (300, 6000)，宽高比在 (0.4, 2.5)，单图小于 30 MB；不做图片总像素下限校验。

Array of objects <= 3 items

参考视频尺寸元数据。Seedance 2.0 reference_video 官方要求单边 [300, 6000]、宽高比 [0.4, 2.5]、总像素 [409600, 8295044]、单个 [2, 15] 秒、总时长不超过 15 秒、FPS [24, 60]、单个不超过 200 MB。

Responses

Request samples

Content type
application/json
{
  • "model": "pro",
  • "content": [
    ],
  • "resolution": "480p",
  • "ratio": "16:9",
  • "duration": 5,
  • "generateAudio": true,
  • "seed": -1,
  • "inputVideoDuration": 0,
  • "audioSetting": "auto",
  • "referenceImages": [
    ],
  • "referenceVideos": [
    ]
}

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string",
  • "data": {
    }
}

查询视频生成任务列表

分页查询当前用户的视频生成任务列表，按创建时间倒序。

Authorizations:
None
query Parameters
page
integer >= 1
Default: 1
pageSize
integer [ 1 .. 100 ]
Default: 20
status
string
Enum: "pending" "generating" "uploading" "success" "failed"

按状态过滤

Responses

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string",
  • "data": {
    }
}

查询视频生成任务详情

查询指定任务的详细信息，只能查询自己的任务。

Authorizations:
None
path Parameters
taskId
required
string

视频生成任务 ID

Responses

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string",
  • "data": {
    }
}

预估视频生成所需积分

根据模型、分辨率、时长等参数预估生成视频所需的积分。

Authorizations:
None
Request Body schema: application/json
required
model
required
string
Enum: "pro" "fast" "happyhorse"

模型档位

resolution
required
string
Enum: "480p" "720p" "1080p"

视频分辨率

duration
required
integer [ 3 .. 15 ]

生成视频时长（秒）

hasVideoInput
boolean
Default: false

是否有视频输入

inputVideoDuration
integer [ 0 .. 60 ]
Default: 0

输入视频时长（秒），hasVideoInput=true 时必须 >= 2

ratio
string
Default: "16:9"
Enum: "16:9" "4:3" "1:1" "3:4" "9:16" "21:9" "4:5" "5:4"

视频宽高比

Array of objects <= 9 items

参考图尺寸元数据。Seedance 2.0 reference_image 官方要求 width/height 单边在 (300, 6000)，宽高比在 (0.4, 2.5)，单图小于 30 MB；不做图片总像素下限校验。

Array of objects <= 3 items

参考视频尺寸元数据。Seedance 2.0 reference_video 官方要求单边 [300, 6000]、宽高比 [0.4, 2.5]、总像素 [409600, 8295044]、单个 [2, 15] 秒、总时长不超过 15 秒、FPS [24, 60]、单个不超过 200 MB。

Responses

Request samples

Content type
application/json
{
  • "model": "pro",
  • "resolution": "480p",
  • "duration": 3,
  • "hasVideoInput": false,
  • "inputVideoDuration": 0,
  • "ratio": "16:9",
  • "referenceImages": [
    ],
  • "referenceVideos": [
    ]
}

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string",
  • "data": {
    }
}

创建 PixVerse 视频生成任务

创建 PixVerse 视频生成任务。v1 同时支持原子能力和营销 Agent，默认走国际站服务；传 language=zh 时走国内站。

  • 原子能力：text_to_video、image_to_video、transition、multi_transition、fusion、restyle、mimic、lip_sync。
  • language=en（默认）：国际站 https://app-api.pixverse.ai，使用国际站 API Key 和国际站 Agent ID。
  • language=zh：国内站 https://app-api.pixverseai.cn，使用国内 API Key 和国内 Agent ID。
  • 默认模型：V6 覆盖 text_to_video、image_to_video、transition、fusion；multi_transition、restyle、mimic、lip_sync 和 Agent 按各自接口/计费表处理。
  • ad_master：至少 1 张商品图，当前不接受视频素材。
  • promo_mix：至少 4 张商品图，最多 2 段视频素材。
  • restyle / lip_sync 可通过 sourceTaskId 复用当前用户已有 PixVerse 成功任务的 providerTaskId。
  • 生成结果继续通过现有视频任务详情、列表、分享、删除接口查询。
  • PixVerse API Key、上传得到的 img_id / media_id、trace id 和 raw provider response 不会返回给客户端。
Authorizations:
None
Request Body schema: application/json
required
model
string
Default: "pixverse"
Enum: "pixverse" "v6" "v5" "v4.5"

PixVerse provider model version；不传时按 capability 使用服务端默认值。

language
string
Default: "en"
Enum: "zh" "en"

PixVerse 服务区域选择；默认 en 走国际站，zh 走国内站。

capability
required
string
Enum: "text_to_video" "image_to_video" "transition" "multi_transition" "fusion" "restyle" "mimic" "lip_sync" "agent"
prompt
string <= 2048 characters
duration
integer [ 1 .. 60 ]
Default: 5
aspectRatio
string
Default: "16:9"
Enum: "9:16" "16:9" "1:1" "4:3" "3:4"
quality
string
Default: "720p"
Enum: "360p" "540p" "720p" "1080p"
sourceTaskId
string

已有 ListenHub PixVerse 成功任务 id；restyle / lip_sync 优先使用该字段解析 source_video_id。

Array of objects <= 10 items
Array of objects <= 2 items
Array of objects <= 1 items
object

Responses

Request samples

Content type
application/json
{
  • "model": "pixverse",
  • "language": "zh",
  • "capability": "text_to_video",
  • "prompt": "string",
  • "duration": 5,
  • "aspectRatio": "9:16",
  • "quality": "360p",
  • "sourceTaskId": "string",
  • "images": [],
  • "videos": [],
  • "audios": [],
  • "pixverse": {
    }
}

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string",
  • "data": {
    }
}

预估 PixVerse 视频生成所需积分

根据 PixVerse capability、Agent 类型、清晰度和时长预估 ListenHub 预扣积分。默认按国内站/V6 可覆盖能力计费；PixVerse 返回的 provider credits 只作为成本观测，不自动补扣或退款。

Authorizations:
None
Request Body schema: application/json
required
model
string
Default: "pixverse"
Enum: "pixverse" "v6" "v5" "v4.5"

PixVerse provider model version；不传时按 capability 使用服务端默认值。

language
string
Default: "en"
Enum: "zh" "en"

PixVerse 服务区域选择；默认 en 走国际站，zh 走国内站。

capability
required
string
Enum: "text_to_video" "image_to_video" "transition" "multi_transition" "fusion" "restyle" "mimic" "lip_sync" "agent"
duration
integer [ 1 .. 60 ]
Default: 5
quality
string
Default: "720p"
Enum: "360p" "540p" "720p" "1080p"
object

Responses

Request samples

Content type
application/json
{
  • "model": "pixverse",
  • "language": "zh",
  • "capability": "text_to_video",
  • "duration": 5,
  • "quality": "360p",
  • "pixverse": {
    }
}

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string",
  • "data": {
    }
}

按 episodeId 查询视频任务详情（需登录）

通过 episodeId 查询当前用户拥有的视频生成任务详情。

Authorizations:
None
path Parameters
episodeId
required
string

Episode ID

Responses

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string",
  • "data": {
    }
}

[DEPRECATED] 按 episodeId 删除视频任务 Deprecated

软删除视频任务及关联的 episode。进行中的任务会退还积分。该单删端点已废弃，视频删除请改走批量 DELETE /v1/episodes。

Authorizations:
None
path Parameters
episodeId
required
string

Episode ID

Responses

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string",
  • "data": {
    }
}

按 episodeId 切换分享状态

切换视频任务及关联 episode 的分享状态。

Authorizations:
None
path Parameters
episodeId
required
string

Episode ID

Request Body schema: application/json
required
enabledShare
boolean
Default: true

Responses

Request samples

Content type
application/json
{
  • "enabledShare": true
}

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string",
  • "data": {
    }
}

公开查看分享的视频（无需登录）

通过 episodeId 查看已分享的视频任务。无需认证（skipAuth）。 要求任务 enabledShare=true 且 status=success。

path Parameters
episodeId
required
string

Episode ID

Responses

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string",
  • "data": {
    }
}

listenhub-voice

ListenHub Voice 音频生成相关接口

创建 ListenHub Voice 音频生成任务

异步创建 ListenHub Voice 音频生成任务，返回 taskId 用于后续轮询。

音色：统一用 voices 数组（0-3 项，每项二选一类型）。不传/空 = 纯文本/音效直出（不卡音色选择）。

  • { "type": "speaker", "id": "..." }：已注册音色。id 可以是 ListenHub 音色代号 （来自 GET /v1/speakers/list）或官方预置 voice_type（来自 GET /v1/listenhub-voice/voices， 如 zh_female_vv_uranus_bigtts），由服务端自动判别。
  • { "type": "reference", "url": "..." }：自定义参考音频 URL（克隆这段音色）。 每条 ≤30s、≤10MB，格式 wav/mp3/pcm/ogg_opus，须公开可访问的 http(s) URL。

1 项 = 单音色朗读全文；多项 = 多音色对白，脚本里用 @音频1 / @音频2 按 voices 数组顺序指派每行台词归属（@音频1 = voices[0]）。

⚠️ 多音色（>1 项）每项必须能进参考音频——官方预置 voice_type 顶级原生路径进不了 多音色（第三方硬限制），仅在单音色（voices 仅 1 项）时启用，音质最佳。多音色里若包含 已注册的官方预置音色（带示例音频），会自动降级走示例音频参考克隆与其他音色混排 （音质略逊于原生，换取可用）；若是裸 voice_type（无参考音频可降级）仍会被拒 （33004 参数无效）。ListenHub 音色与自定义参考音频可自由混合多音色对白。

⚠️ 图片参考与音色互斥：传 image 时不能再传 voices（参考图片不能与 audio_url/audio_data/speaker 同时使用，官方硬限制），二者只能选一个，同传会被拒。

计费：按实际生成时长（秒）真扣，0.1125 积分/秒，向上取整、最低 1 积分。 创建时只做余额预检，不预占积分；出片后按真实音频时长结算。 可先调 POST /v1/listenhub-voice/estimate-credits 获取预估值。

频率限制：用户级 60 秒 / 5 次。

异步流程：

  1. 创建任务，返回 202 + taskId（status=pending）
  2. 系统提交至 ListenHub Voice 服务并轮询生成结果
  3. 生成完成后转存 GCS 公开桶
  4. 客户端轮询 GET /v1/listenhub-voice/tasks/{taskId} 获取结果
Authorizations:
None
Request Body schema: application/json
required
model
string
Default: "listenhub-voice-1.0"
Value: "listenhub-voice-1.0"

模型版本

text
required
string <= 1400 characters

待合成文本（首尾空白会被裁剪）。多音色对白用 @音频1 / @音频2 前缀指派台词

Array of objects [ 0 .. 3 ] items

音色列表（0-3 项）。不传/空=纯文本/音效（不卡音色选择）；1 项=单音色， 多项=多音色对白（@音频N 按顺序指派）。多音色每项必须能进参考音频——官方预置 voice_type 仅限单音色。

object

参考图片（端到端「图片→音频」）。url / data 二选一。最多 1 张， ≤10MB，格式 jpeg/png/webp。与 voices 互斥：图片参考不能与 音色/参考音频同传（官方硬限制），二者只能选一个。

object

音频参数（可选）

durationHint
number [ 1 .. 110 ]

目标时长（秒），用于积分预估并提示模型生成「约 N 秒」的音频

watermark
boolean

是否添加水印

Responses

Request samples

Content type
application/json
{
  • "model": "listenhub-voice-1.0",
  • "text": "string",
  • "voices": [],
  • "image": {},
  • "audioConfig": {
    },
  • "durationHint": 1,
  • "watermark": true
}

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string",
  • "data": {
    }
}

查询 ListenHub Voice 任务列表

分页查询当前用户的 ListenHub Voice 任务列表，按创建时间倒序。

Authorizations:
None
query Parameters
page
integer >= 1
Default: 1
pageSize
integer [ 1 .. 100 ]
Default: 20
status
string
Enum: "pending" "generating" "uploading" "success" "failed"

按状态过滤

Responses

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string",
  • "data": {
    }
}

列出官方预置音色

返回官方预置在线音色列表（596 个）。这些 voiceType 可作为 POST /v1/listenhub-voice/generate 的 voices: [{ type: "speaker", id: "<voiceType>" }] 传入（服务端自动识别为官方预置音色，走第三方顶级 speaker 字段）。 ListenHub 自有音色仍走 GET /v1/speakers/list。

Authorizations:
None
query Parameters
keyword
string <= 64 characters

按名称 / voiceType / 语种模糊过滤（可选）

Responses

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string",
  • "data": {
    }
}

查询 ListenHub Voice 任务详情

查询指定任务的详细信息，只能查询自己的任务。

Authorizations:
None
path Parameters
taskId
required
string

ListenHub Voice 音频生成任务 ID

Responses

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string",
  • "data": {
    }
}

预估 ListenHub Voice 音频生成所需积分

根据 durationHint 预估生成音频所需的积分。 缺省时按 120 秒上限估算；最终以实际生成时长结算，预估值仅供参考。

Authorizations:
None
Request Body schema: application/json
required
durationHint
number [ 1 .. 110 ]

目标时长（秒），缺省按 120 秒上限估算

Responses

Request samples

Content type
application/json
{
  • "durationHint": 1
}

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string",
  • "data": {
    }
}

internal

内部服务接口（仅供内部服务调用）

内部审核接口

内部服务调用的审核接口，支持文本和图片审核。

注意：此接口仅供内部服务调用，需要使用内部 API Key 进行认证

认证方式：

  • Header: Authorization: Bearer <internal_api_key>
  • 内部 API Key 配置在 config.internalApiKeys

功能特性：

  • 支持文本审核（超过 10000 字符自动分段）
  • 支持图片审核
  • 审核服务异常时返回默认通过状态（容错机制）
  • 建议策略：只要 isRejected 不是 true，就允许通过
Authorizations:
None
Request Body schema: application/json
required
type
required
string
Enum: "text" "image"

审核类型

text
string

待审核的文本内容（type=text 时必填）

imageUrl
string <uri>

待审核的图片 URL（type=image 时必填）

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
Example
{
  • "success": true,
  • "data": {
    }
}