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>
  • 受保护请求若在业务 handler 执行前因认证失败被拒绝，响应头包含 x-auth-failed-before-handler: 1；该响应头可作为刷新会话后最多重放一次写请求的无副作用证据，缺失时不得自动重放

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": {
    }
}

web 第三方登录初始化 v2

与 v1 的区别：redirect_uri 由后端按 platform 与发起 origin 决定并登记在 身份提供方，前端不再传入，因此不存在前端回调 route。

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

平台类型

platform
string

应用平台，缺省 listenhub

appOrigin
string

发起登录的前端 origin。命中受理域名列表时整条登录链路（redirect_uri 与回跳地址）留在该域，否则落回服务端配置值。

Responses

Response samples

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

web 第三方登录回调 v2（Google，302 重定向回前端）

身份提供方直接回调本端点。成功后 302 重定向到该 platform 配置的前端地址： 列在 webAuthCodeExchangePlatforms 里的平台只在 URL fragment 带一次性 code（#code=...，前端用 /v2/auth/web/session 兑换；fragment 不发往 服务端也不进 Referer），其余平台仍在 query 带 accessToken / refreshToken / expiresIn / firstLogin。失败时重定向带 errorCode 与 errorDescription。回跳地址的 origin 跟随本次回调落地的 API 域名， 从镜像域发起的登录全程停在该镜像域。

Authorizations:
None
path Parameters
platform
required
string

应用平台

query Parameters
code
required
any

第三方登录授权码

state
required
any

第三方登录状态

Responses

web 第三方登录回调 v2（Apple form_post）

Apple 使用 response_mode=form_post，回调为 urlencoded POST。 行为与同路径 GET 完全一致。

Authorizations:
None
path Parameters
platform
required
string

应用平台

Request Body schema: application/x-www-form-urlencoded
required
code
required
string

第三方登录授权码

state
required
string

第三方登录状态

Responses

用一次性 code 兑换登录令牌

code 由 v2 回调签发，TTL 120 秒且只能消费一次，重放返回错误。 令牌因此不必出现在重定向 URL 里（#356）。

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

v2 回调签发的一次性登录 code

Responses

Request samples

Content type
application/json
{
  • "code": "f5d62b05-370e-48be-a755-8675ca146431"
}

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 字符

speakerScene
string
Enum: "single" "multi"

按作品归类筛选(可选)。single=朗读，multi=多角色配音；不传则不筛。 以创建时声明的 template.speakerScene 为准；没有该字段的历史单集回落到 template.speakers 的元素个数（2 个及以上算 multi）。

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

来源

speed
number <float> decimal places <= 2 [ 0.5 .. 2 ]
Default: 1

生成语速倍率（可选）。直接表示生成语速，不是播放器倍速。范围 0.5-2.0，最多两位小数，默认 1。

object

模板配置（可选）

Responses

Request samples

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

Response samples

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

编辑单集

编辑单集内容并重新生成音频。 传 sourceEpisodeId：就地改版。不新建单集，也不改动这条单集的在播音频—— 服务端只登记一条改版记录并对它生成，生成成功后才把新音频整体切换过去； 失败则单集完全不变，旧音频照常可播。响应额外返回 revisionId。 同一条单集上一次编辑还在生成时再次提交会被拒（errno 26023）。 已公开或已进画廊的单集被编辑后会重新进入审核并暂时退出画廊。 不传 sourceEpisodeId：按脚本从零创建，行为不变，仍然新建一条单集。

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
Enum: "en" "zh" "ja" "es" "pt" "fr" "de" "tr" "ko" "it" "th" "vi"

语言

required
Array of objects

脚本数组

sourceEpisodeId
string

源单集ID（可选）

speakerScene
string
Enum: "single" "multi"

作品归类（可选）。single=朗读，multi=多角色配音； 落到新建单集的 template.speakerScene，供单集列表的 speakerScene 过滤使用。 不传则该字段缺席，列表按 template.speakers 元素个数推断。 就地改版（传了 sourceEpisodeId）不改写已有单集的归类。

speed
number <float> decimal places <= 2 [ 0.5 .. 2 ]
Default: 1

生成语速倍率（可选）。直接表示生成语速，不是播放器倍速。范围 0.5-2.0，最多两位小数，默认 1。

Responses

Request samples

Content type
application/json
{
  • "type": "podcast",
  • "speakers": [
    ],
  • "language": "en",
  • "scripts": [
    ],
  • "sourceEpisodeId": "string",
  • "speakerScene": "single",
  • "speed": 1.25
}

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

来源列表

speed
number <float> decimal places <= 2 [ 0.5 .. 2 ]
Default: 1

生成语速倍率（可选）。直接表示生成语速，不是播放器倍速。范围 0.5-2.0，最多两位小数，默认 1。

object

模板配置（可选）

Responses

Request samples

Content type
application/json
{
  • "query": "string",
  • "type": "podcast-solo",
  • "sources": [
    ],
  • "speed": 1.25,
  • "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: "en" "zh" "ja" "es" "pt" "fr" "de" "tr" "ko" "it" "th" "vi"

语言

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" "ja"

语言

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" "ja"

语言

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

fileName
string <= 255 characters

可选下载文件名；符合图片附件签名条件时由服务端清洗后写入 Content-Disposition

Responses

Response samples

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

获取 Banana 参考图片上传地址

获取预签名 PUT 地址和稳定的私有对象引用。稳定引用仅能由对象所属用户提交；服务端在 provider 边界校验精确命名空间并短时签名，私有桶不会公开。

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

sourceOrigin
string <uri>

发起支付的站点 origin。仅接受当前环境白名单中的完整 origin， 用于让 Stripe 完成或取消后回到同一站点；缺省或无效时保持现有回跳地址。

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

Response samples

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

获取用户订阅管理页

获取用户订阅管理页

Authorizations:
None
query Parameters
sourceOrigin
string <uri>

发起请求的站点 origin。仅接受当前环境白名单中的完整 origin； 缺省或无效时保持现有回跳地址。

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（可选）

sourceOrigin
string <uri>

发起支付的站点 origin。仅接受当前环境白名单中的完整 origin， 用于让 Stripe 完成或取消后回到同一站点；缺省或无效时保持现有回跳地址。

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

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

语言；传 all 时一次返回全部语言（音色目录用，避免逐语言请求扇出）

Responses

Response samples

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

按语言统计公开音色数量

音色目录页语言 tag 的数字来源；只统计公开与付费音色，不含私有音色

Authorizations:
None
query Parameters
status
integer

音色状态，默认已发布

Responses

添加 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": {
    }
}

获取运营配置（福利数字）

下发运营在 manager 后台配置的福利数字，供前端展示。前端展示的赠送/奖励 积分一律读这个接口，不再各自硬编码——同一份数字同时驱动后端实际发放， 避免文案与实发漂移。

平台维度由请求头 x-listenhub-client-id / x-marswave-client-id 解析， 未识别时按 listenhub 处理；显式传 application 时以它为准（manager 后台按平台读「当前生效值」用，它没有各平台的 client-id 头）。

配置缺失、异常或存储不可用时逐项回落到服务端代码默认值，接口不会失败。

Authorizations:
None
query Parameters
application
string
Enum: "listenhub" "nextlab" "banana-lab"

指定按哪个平台解析配置；不传则按 client-id 头推导

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；12 种支持语言均返回该语言的预生成引导音频（Base64 data URI）；缺少预生成音频时降级返回本地化文字引导且 audioUrl 为空
  2. 后续调用：用户录音后直接上传原始音频文件 (multipart/form-data)
  3. API 处理：接收文件 → 读取 Buffer → 通过 Synapse 传 base64 给 multimodal-engine
  4. Engine 处理：解码 base64 → ASR 识别 → LLM 生成回复 → TTS 转语音 → Base64 编码
  5. 返回响应：后续对话返回可播放音频；无预生成音频的降级首轮引导返回空 audioUrl
  6. 达到阈值：端调用 /clone 接口上传合并后的音频文件，触发克隆
Authorizations:
None
Request Body schema: multipart/form-data
required
language
required
string
Enum: "en" "zh" "ja" "es" "pt" "fr" "de" "tr" "ko" "it" "th" "vi"

语言类型

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 克隆链路 → 下载试听音频上传到 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: "en" "zh" "ja" "es" "pt" "fr" "de" "tr" "ko" "it" "th" "vi"

音频语言

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
}

获取示例音色列表

获取预设的示例音色列表，用于展示克隆前后对比效果。 示例数据由后端写死，不需要用户创建。 支持按 12 种站点语言筛选，默认返回中文示例。 每种语言最多返回 4 个真实案例；当前有多少就返回多少，不使用其他语言案例补齐。

Authorizations:
None
query Parameters
language
string
Default: "zh"
Enum: "en" "zh" "ja" "es" "pt" "fr" "de" "tr" "ko" "it" "th" "vi"
Example: language=zh

12 种站点语言之一，默认 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（重试时必填）

batchId
string <= 64 characters

一次多图生成的分组 ID（n 个并行请求共享同一 UUID），供 Featured/Trending 折叠。

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",
  • "batchId": "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）

modelName
string
Enum: "gemini-3-pro-image" "gemini-3.1-flash-image" "gpt-image-2" "gpt-image-2-official" "wan2.7-image-pro" "wan2.7-image"

按模型过滤（umbrella slug，gpt-image-2 含 lite/official 整族）。不传则不过滤。

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 图片详情

返回本人图片，或公开且审核通过的图片。不传 promptLanguage 时保持原始 prompt； 传入时按“目标语言 → 英文 → 原始 prompt”回退。响应只暴露最终 prompt，不暴露译文字段。

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

图片 ID

query Parameters
promptLanguage
string
Enum: "en" "zh" "zh-Hant" "fr" "de" "es" "pt" "ja" "ko" "ru" "it" "nl" "tr" "ar" "hi" "id" "vi"

Prompt 内容语言

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "prompt": "string",
  • "referenceImageUrls": [
    ],
  • "aspectRatio": "string",
  • "imageSize": "string",
  • "imageUrl": "string",
  • "thumbnailUrl": "string",
  • "modelName": "string"
}

获取 Banana 当下趋势图片

按 favoriteCount 时间衰减打分排序的公开图趋势榜（越新权重越高），运营 pin 强制置顶、 hide 强制排除，同 batch 组折叠只露代表图。默认排除 NSFW，可选 tag / modelName 收窄。 排名只处理最近 1000 个合格候选和全部安全可见的运营置顶；pagination 不返回全历史 total。 locale=en 时候选上限不变，缺少英文译文的记录会被跳过而不回退原文。 promptLanguage 只在排序与分页完成后投影 prompt，按“目标语言 → 英文 → 原始 prompt”回退， 不改变图片 ID、顺序、数量或分页。promptLanguage 与 locale 不能同时传入。

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

有界候选集合内的页码，从1开始；超出集合返回空数组

pageSize
integer [ 1 .. 100 ]
Default: 20

每页数量（最大 100）

tag
string

按内容分类过滤（对齐 explore.tags 的 active key）

modelName
string
Enum: "gemini-3-pro-image" "gemini-3.1-flash-image" "gpt-image-2" "gpt-image-2-official" "wan2.7-image-pro" "wan2.7-image"

按模型过滤（umbrella slug）

locale
string
Value: "en"

显式请求扁平的英文 prompt；不传时继续返回原始 prompt

promptLanguage
string
Enum: "en" "zh" "zh-Hant" "fr" "de" "es" "pt" "ja" "ko" "ru" "it" "nl" "tr" "ar" "hi" "id" "vi"

在最终趋势结果上投影 prompt；缺译回退英文后再回退原文，与 locale 互斥

Responses

Response samples

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

更新 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 视频生成相关接口

创建 Labnana 视频生成任务

请求体与 /v1/video-generation/generate 完全一致（同一份 Joi schema）。

模型准入：Seedance 2.0 Pro / Fast、HappyHorse 1.1 与 Wan 3.0 / Wan 3.0 Prime 对所有活跃登录用户开放，按积分扣费，无订阅门槛。

可见性：任务写入 application=banana-lab 且 isPublic=false，默认仅所有者可见；普通请求不能写 isPublic。只有审核运营脚本可以按精确任务改变公开状态。ListenHub 侧看不到，也不生成 ListenHub episode（响应不含 episodeId）。

Authorizations:
None
Request Body schema: application/json
required
model
string
Default: "doubao-seedance-2-pro"
Enum: "doubao-seedance-2-pro" "doubao-seedance-2-fast" "happyhorse" "wan3.0-video" "wan3.0-video-prime"

Seedance Pro/Fast 为付费模型；HappyHorse 与 Wan 3.0 支持免费积分。

  • wan3.0-video（展示名 Wan 3.0，供应商 Alibaba）与 wan3.0-video-prime（Wan 3.0 Prime）能力对齐，Prime 端到端速度显著提升、单价为标准版 1.5 倍。
  • Wan 3.0 原生音画同出，generateAudio 默认 true；关闭音频不降价。
  • Wan 3.0 支持 first_frame 与 last_frame（传 last_frame 必须同时传 first_frame），reference_image 最多 9 张，frame 角色与 reference 角色互斥。
  • Wan 3.0 支持扩展输入 reference_video / reference_audio；带参考视频时须传 inputVideoDuration（1–15 秒整数），且输入 + 输出总时长不超过 30 秒。计费按输入 + 输出总秒数（与上游 usage.duration 同口径）。
required
Array of objects or objects or objects or objects [ 1 .. 16 ] items

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

  • text: 文本提示词（最多 1 个，max 2500 字符；Seedance 模型限 1500 字符，Wan 3.0 为 2500 字符，纯图生视频可不传）
  • 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；Wan 3.0 允许只配 prompt）
resolution
string
Default: "720p"
Enum: "480p" "720p" "1080p"

视频分辨率，按模型分档：

  • Seedance Pro：480p / 720p / 1080p；Seedance Fast 不支持 1080p
  • HappyHorse：720p / 1080p（不支持 480p）
  • Wan 3.0 / Wan 3.0 Prime：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"

视频宽高比，枚举为全集，实际支持面按模型收窄，不支持时返回 errno 32011：

  • Seedance Pro/Fast：16:9、4:3、1:1、3:4、9:16、21:9
  • HappyHorse：全部 8 档
  • Wan 3.0 / Wan 3.0 Prime：只有 16:9、4:3、1:1、3:4、9:16 五档（不支持 21:9、4:5、5:4）
duration
integer [ 2 .. 30 ]
Default: 5

生成视频时长（秒）。枚举范围为全集，按模型分档校验，超出所选模型档位返回 400：

  • Seedance Pro/Fast：4–15
  • HappyHorse：3–15
  • Wan 3.0 / Wan 3.0 Prime：2–30
generateAudio
boolean
Default: true

是否同时生成音频。Wan 3.0 原生音画同出，关闭音频不降价。

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；不做图片总像素下限校验。服务端只校验实际提供的字段——未提供 width/height 时不做尺寸预校验，由 provider 判定，被拒时返回 32004。

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。服务端只校验实际提供的字段——未提供 width/height 时不做尺寸预校验，由 provider 判定，被拒时返回 32004。

Responses

Request samples

Content type
application/json
{
  • "model": "doubao-seedance-2-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": {
    }
}

预估 Labnana 视频生成所需积分

请求体与响应与 /v1/video-generation/estimate-credits 一致。

Authorizations:
None
Request Body schema: application/json
required
model
required
string
Enum: "doubao-seedance-2-pro" "doubao-seedance-2-fast" "happyhorse" "wan3.0-video" "wan3.0-video-prime"

Seedance Pro/Fast 为付费模型；HappyHorse 720p 每 15 个计费秒 100 积分，1080p 每 15 个计费秒 135 积分。

Wan 3.0 按「积分/秒 × 时长」计价，对总额向上取整；关闭音频不降价：

分辨率 wan3.0-video 积分/秒 5s 10s 30s wan3.0-video-prime 积分/秒 5s 10s 30s
480p 5.625 29 57 169 8.4375 43 85 254
720p 11.25 57 113 338 16.875 85 169 507
1080p 22.5 113 225 675 33.75 169 338 1013
resolution
required
string
Enum: "480p" "720p" "1080p"

视频分辨率，按模型分档：Seedance Pro 三档全开、Seedance Fast 不支持 1080p、HappyHorse 不支持 480p、Wan 3.0 三档全开。

duration
required
integer [ 2 .. 30 ]

生成视频时长（秒）。按模型分档校验：Seedance 4–15、HappyHorse 3–15、Wan 3.0 2–30。

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"

视频宽高比，枚举为全集，实际支持面按模型收窄：Seedance 6 档（含 21:9）、HappyHorse 全部 8 档、Wan 3.0 只有 16:9、4:3、1:1、3:4、9:16 五档。

Array of objects <= 9 items

参考图尺寸元数据（可选）。Seedance 2.0 reference_image 官方要求 width/height 单边在 (300, 6000)，宽高比在 (0.4, 2.5)，单图小于 30 MB；不做图片总像素下限校验。服务端只校验实际提供的字段——未提供 width/height 时不做尺寸预校验，由 provider 判定，被拒时返回 32004。

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。服务端只校验实际提供的字段——未提供 width/height 时不做尺寸预校验，由 provider 判定，被拒时返回 32004。

Responses

Request samples

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

Response samples

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

查询 Labnana 视频生成任务列表

分页查询当前用户在 Labnana 产生的视频任务，按创建时间倒序。ListenHub 侧的任务不会出现在这里。成功任务的视频与封面保存在私有任务命名空间，所有者鉴权通过后返回 15 分钟短签 URL；不会返回第三方原始视频 URL。

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

Responses

Response samples

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

查询 Labnana 视频生成任务详情

成功任务的视频与封面保存在私有任务命名空间，所有者鉴权通过后返回 15 分钟短签 URL；不会返回第三方原始视频 URL。

Authorizations:
None
path Parameters
taskId
required
string

Responses

Response samples

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

删除 Labnana 视频生成任务

软删除。仍在生成中的任务会退还已扣积分（幂等）。

Authorizations:
None
path Parameters
taskId
required
string

Responses

Response samples

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

匿名查询已审核的 Labnana 公开视频示例

仅返回 application=banana-lab、isPublic=true、status=success、deletedAt=0 且视频和封面均为已验证私有任务资产的任务。通过全部条件后，列表为该任务的视频与封面即时签发 15 分钟 URL；任一校验或签名失败时整条请求失败。列表只返回摘要，不返回也不签发任何输入素材 URL。

query Parameters
page
integer >= 1
Default: 1
pageSize
integer [ 1 .. 50 ]
Default: 20

Responses

Response samples

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

匿名查询一个已审核的 Labnana 公开视频示例

点击复刻时按任务 ID 即时读取。通过公开读取条件后，详情为私有任务视频、封面和该任务所有者命名空间中的精确输入对象签发 15 分钟 URL；任一资产校验或签名失败时整条请求失败，不回落稳定私有 URL。私有、失败、已删除及其他产品线任务统一按不存在处理。

path Parameters
taskId
required
string

Responses

Response samples

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

创建视频生成任务

异步创建视频生成任务，返回 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 计费，创建时即时扣除，失败自动退还。

模型准入：Seedance Pro/Fast 仅限当前有效订阅或历史付费用户；HappyHorse 与 Wan 3.0 / Wan 3.0 Prime 可由活跃免费用户使用免费积分创建。

HappyHorse 促销计价：720p 每 15 个计费秒 100 积分（3–15 秒按比例向上取整）；1080p 15 秒 135 积分。视频编辑按输入与输出总秒数计费，不是固定按输出时长计费。

Wan 3.0 计价：按「积分/秒 × 时长」计费，对总额向上取整；原生音画同出，关闭 generateAudio 不降价。

分辨率 wan3.0-video 积分/秒 5s 10s 30s wan3.0-video-prime 积分/秒 5s 10s 30s
480p 5.625 29 57 169 8.4375 43 85 254
720p 11.25 57 113 338 16.875 85 169 507
1080p 22.5 113 225 675 33.75 169 338 1013

Wan 3.0 参数边界：时长为 2–30 秒整数（默认 5）；分辨率 480p / 720p / 1080p 三档全开；画面比例只有 16:9、4:3、1:1、3:4、9:16 五档，传 21:9 / 4:5 / 5:4 会被拒绝；提示词上限 2500 字符，纯图生视频可不传 prompt；支持 first_frame 与 last_frame（last_frame 必须与 first_frame 同时传），reference_image 最多 9 张，frame 角色与 reference 角色互斥；扩展输入 reference_video / reference_audio 已开放，参考视频须同时传 inputVideoDuration（1–15 秒整数），且「输入时长 + 输出时长」不得超过 30 秒。生成耗时较长，480p/5s 实测约 5 分钟。

频率限制：按用户和模型族限流，SeedDance 为 2 RPM，HappyHorse 为 5 RPM，Wan 3.0 默认为每分钟 5 次。

异步流程：

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

Seedance Pro/Fast 为付费模型；HappyHorse 与 Wan 3.0 支持免费积分。

  • wan3.0-video（展示名 Wan 3.0，供应商 Alibaba）与 wan3.0-video-prime（Wan 3.0 Prime）能力对齐，Prime 端到端速度显著提升、单价为标准版 1.5 倍。
  • Wan 3.0 原生音画同出，generateAudio 默认 true；关闭音频不降价。
  • Wan 3.0 支持 first_frame 与 last_frame（传 last_frame 必须同时传 first_frame），reference_image 最多 9 张，frame 角色与 reference 角色互斥。
  • Wan 3.0 支持扩展输入 reference_video / reference_audio；带参考视频时须传 inputVideoDuration（1–15 秒整数），且输入 + 输出总时长不超过 30 秒。计费按输入 + 输出总秒数（与上游 usage.duration 同口径）。
required
Array of objects or objects or objects or objects [ 1 .. 16 ] items

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

  • text: 文本提示词（最多 1 个，max 2500 字符；Seedance 模型限 1500 字符，Wan 3.0 为 2500 字符，纯图生视频可不传）
  • 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；Wan 3.0 允许只配 prompt）
resolution
string
Default: "720p"
Enum: "480p" "720p" "1080p"

视频分辨率，按模型分档：

  • Seedance Pro：480p / 720p / 1080p；Seedance Fast 不支持 1080p
  • HappyHorse：720p / 1080p（不支持 480p）
  • Wan 3.0 / Wan 3.0 Prime：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"

视频宽高比，枚举为全集，实际支持面按模型收窄，不支持时返回 errno 32011：

  • Seedance Pro/Fast：16:9、4:3、1:1、3:4、9:16、21:9
  • HappyHorse：全部 8 档
  • Wan 3.0 / Wan 3.0 Prime：只有 16:9、4:3、1:1、3:4、9:16 五档（不支持 21:9、4:5、5:4）
duration
integer [ 2 .. 30 ]
Default: 5

生成视频时长（秒）。枚举范围为全集，按模型分档校验，超出所选模型档位返回 400：

  • Seedance Pro/Fast：4–15
  • HappyHorse：3–15
  • Wan 3.0 / Wan 3.0 Prime：2–30
generateAudio
boolean
Default: true

是否同时生成音频。Wan 3.0 原生音画同出，关闭音频不降价。

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；不做图片总像素下限校验。服务端只校验实际提供的字段——未提供 width/height 时不做尺寸预校验，由 provider 判定，被拒时返回 32004。

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。服务端只校验实际提供的字段——未提供 width/height 时不做尺寸预校验，由 provider 判定，被拒时返回 32004。

Responses

Request samples

Content type
application/json
{
  • "model": "doubao-seedance-2-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: "doubao-seedance-2-pro" "doubao-seedance-2-fast" "happyhorse" "wan3.0-video" "wan3.0-video-prime"

Seedance Pro/Fast 为付费模型；HappyHorse 720p 每 15 个计费秒 100 积分，1080p 每 15 个计费秒 135 积分。

Wan 3.0 按「积分/秒 × 时长」计价，对总额向上取整；关闭音频不降价：

分辨率 wan3.0-video 积分/秒 5s 10s 30s wan3.0-video-prime 积分/秒 5s 10s 30s
480p 5.625 29 57 169 8.4375 43 85 254
720p 11.25 57 113 338 16.875 85 169 507
1080p 22.5 113 225 675 33.75 169 338 1013
resolution
required
string
Enum: "480p" "720p" "1080p"

视频分辨率，按模型分档：Seedance Pro 三档全开、Seedance Fast 不支持 1080p、HappyHorse 不支持 480p、Wan 3.0 三档全开。

duration
required
integer [ 2 .. 30 ]

生成视频时长（秒）。按模型分档校验：Seedance 4–15、HappyHorse 3–15、Wan 3.0 2–30。

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"

视频宽高比，枚举为全集，实际支持面按模型收窄：Seedance 6 档（含 21:9）、HappyHorse 全部 8 档、Wan 3.0 只有 16:9、4:3、1:1、3:4、9:16 五档。

Array of objects <= 9 items

参考图尺寸元数据（可选）。Seedance 2.0 reference_image 官方要求 width/height 单边在 (300, 6000)，宽高比在 (0.4, 2.5)，单图小于 30 MB；不做图片总像素下限校验。服务端只校验实际提供的字段——未提供 width/height 时不做尺寸预校验，由 provider 判定，被拒时返回 32004。

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。服务端只校验实际提供的字段——未提供 width/height 时不做尺寸预校验，由 provider 判定，被拒时返回 32004。

Responses

Request samples

Content type
application/json
{
  • "model": "doubao-seedance-2-pro",
  • "resolution": "480p",
  • "duration": 2,
  • "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 时走国内站。

PixVerse 对活跃免费用户开放，可使用免费积分创建。

  • 原子能力：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"

PixVerse 支持的画面比例；传入其他已知比例（如 21:9 / 4:5 / 5:4）返回 errno 32011

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、≤4MB，格式 wav/mp3/pcm/ogg_opus，须为 provider 可访问的 http(s) URL。 API 仅鉴权下载 ListenHub 私有存储对象并检查空内容、单条 4MB 和合计 6MB； 公开/外部 URL 由 provider 拉取，其可达性、时长和可解码性由 provider 最终判定。

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": {
    }
}

audio-transcription

音频转文字相关接口

创建音频转文字私有直传地址

为当前用户创建一个私有 GCS 对象地址。客户端必须使用返回的 presignedUrl 直接 PUT 原始文件，并保持 Content-Type 与本请求一致；不得把外部 URL 作为 fileKey 提交。直传完成后，再调用 POST /v1/audio-transcriptions 创建任务。

支持 aac、amr、avi、flac、flv、m4a、mkv、mov、mp3、mp4、mpeg、ogg、 opus、wav、webm、wma、wmv。单文件最大 50 MiB；服务端会按 GCS 元数据再次 校验实际大小、类型与归属。2 小时限制在创建时按浏览器媒体元数据预检，并在 模型结果返回后按模型给出的原始时长最终校验。

Authorizations:
None
Request Body schema: application/json
required
fileName
required
string <= 255 characters

原始文件名；扩展名必须是支持的 17 种格式之一

contentType
required
string <= 255 characters

原文件 MIME 类型；支持 audio/*、video/*、application/ogg 或 application/octet-stream

fileSize
required
integer <int64> [ 1 .. 52428800 ]

客户端声明的文件字节数；服务端在创建任务时按 GCS 元数据再次校验

Responses

Request samples

Content type
application/json
{
  • "fileName": "interview.m4a",
  • "contentType": "audio/mp4",
  • "fileSize": 1
}

Response samples

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

创建音频转文字任务

使用当前用户已完成的私有 GCS 直传对象创建异步转写任务。服务端会校验对象 归属、扩展名、元数据、客户端时长边界与可用积分，校验通过后任务以 queued 状态入队并立即返回；后台 worker 随后把源文件转传到转写服务的临时存储并提交， 提交成功后任务进入 transcribing。 durationMs 来自浏览器媒体元数据，用于提交前校验和逻辑预留；模型成功返回后， 服务端以模型结果中的原始时长再次校验 2 小时边界并计算最终结算积分。

idempotencyKey 必须由客户端为一次逻辑创建稳定生成；网络重试必须复用同一个值， 相同用户与幂等键返回同一任务。terms 最多 50 个，服务端会去除首尾空白并按 大小写不敏感去重。语言由服务自动识别，无需也不接受语言参数。所需积分按原文件 每个开始分钟 1 积分计算（至少 1 积分）：提交后只做逻辑预留，成功结算时才实际扣除。

Authorizations:
None
Request Body schema: application/json
required
fileKey
required
string <= 512 characters ^audio-transcriptions/[^/]+/[^/]+$

由私有直传接口返回、且已完成上传的对象键；不接受 URL

fileName
required
string <= 255 characters

原始文件名；扩展名必须与 fileKey 一致

durationMs
required
integer <int64> [ 1 .. 7200000 ]

浏览器从媒体元数据读取的原始时长（毫秒），用于提交前边界校验和积分预留；最终结算以模型结果原始时长为准

terms
Array of strings <= 50 items [ items <= 100 characters ]
Default: []

可选的专有名词或人名；每项最长 100 字符、去重后总长最多 2000 字符，服务端去空白并按大小写不敏感去重

idempotencyKey
required
string [ 1 .. 128 ] characters

客户端生成的一次逻辑创建键；网络重试必须复用原值

Responses

Request samples

Content type
application/json
{
  • "fileKey": "string",
  • "fileName": "interview.m4a",
  • "durationMs": 183000,
  • "terms": [ ],
  • "idempotencyKey": "atx_20260812_7b4f688f"
}

Response samples

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

查询音频转文字任务列表

分页查询当前用户的任务，按创建时间倒序返回。可选 keyword 对文件名和已转写 全文做大小写不敏感的模糊匹配。列表条目会裁掉句级时间戳并截断预览全文， 完整结果请查询任务详情。

Authorizations:
None
query Parameters
page
integer >= 1
Default: 1
pageSize
integer [ 1 .. 100 ]
Default: 20
keyword
string <= 64 characters

按文件名或转写全文模糊搜索

Responses

Response samples

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

批量删除音频转文字任务

批量软删当前用户的终态任务（completed / failed），删除后不再出现在列表与 详情中，源音频由后台回收。进行中的任务、不属于当前用户的任务和已删除的任务 会被静默跳过，整批仍返回成功。

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

Responses

Request samples

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

Response samples

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

查询音频转文字任务详情

查询当前用户拥有的任务。进行中的任务可轮询此接口；服务端返回已持久化的任务状态与结果。

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

音频转文字任务 ID

Responses

Response samples

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

下载音频转文字 TXT 或 SRT

下载当前用户已完成任务的精确持久化结果。format=txt（默认）返回 UTF-8 text/plain 全文；format=srt 用已落库的句级时间戳现场生成 SubRip 字幕， 不会重新调用转写服务。响应是附件，文件名使用原文件名并改为对应扩展名； 接口不返回临时下载 URL。任务尚未完成、结果不存在或任务不属于当前用户时 返回资源不存在；结果没有句级时间戳时 format=srt 同样返回资源不存在。

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

音频转文字任务 ID

query Parameters
format
string
Default: "txt"
Enum: "txt" "srt"

导出格式

Responses

Response samples

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

重试失败的音频转文字任务

provider 转写失败时，基于未变化的原私有 GCS 对象创建新任务；provider 结果已 持久化但最终余额不足时，只重试原结果结算，不会重新提交 ASR。提交或扣费结果 不确定的 submission_unknown / settlement_unknown 均禁止重试。服务端按原任务幂等。

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

音频转文字任务 ID

Responses

Response samples

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

internal

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

获取 Web 年付统一活动配置

manager-server 内部接口，使用专用 Bearer API Key。返回当前活动选择的 计划记录 ID，以及全部可选择的启用中 Web 付费年付套餐。 consistent=false 表示存量数据不一致，此时活动不会生效。

Authorizations:
None

Responses

Response samples

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

更新 Web 年付统一活动配置

manager-server 内部接口，使用专用 Bearer API Key。启用时必须通过 targetPlanIds 选择活动适用的 Web 付费年付套餐；同一内部 name 的 地区记录必须全部选择，且目标 Stripe Product 不得被未选 Web 付费套餐共用。 活动价按对应月付原价 × 12 再乘活动折扣计算，不与套餐原有年付优惠叠加。 后端会先验证 Stripe promotion code 的状态、核销后的精确实付金额、适用客户、适用产品、无限总次数、 一次性 duration，以及 promotion / coupon 的失效时刻是否彼此一致、且至少 晚于活动结束 3 天（只用于恢复活动期内已获得资格的延迟续费）； 无法完整证明安全时拒绝写入。enabled=false 会清空活动效果， 不修改基础价格或 Stripe 资产。新购与升级仍严格按 [startAt,endAt) 创建交易，窗口外即使拿到活动码也会被服务端拒绝。请求体拒绝未知字段。

Authorizations:
None
Request Body schema: application/json
required
enabled
required
boolean
discountPercent
number ( 0 .. 100 )

启用时必填。活动展示比例，以同档月付原价 × 12 为基准； Stripe coupon 可以是 percent_off 或 amount_off，但核销后的年付实付金额 必须与该比例计算出的活动价精确一致。

startAt
integer <int64>

启用时必填，活动开始时间戳（毫秒，含）

endAt
integer <int64>

启用时必填，活动结束时间戳（毫秒，不含），必须大于 startAt

stripePromotionCode
string [ 1 .. 200 ] characters

启用时必填，Stripe 客户可见 promotion code

targetPlanIds
Array of strings non-empty unique

启用时必填。实际计划记录 ID；同一内部 name 的全部地区记录 必须一起提交。停用时省略。

Responses

Request samples

Content type
application/json
{
  • "enabled": true,
  • "discountPercent": 0,
  • "startAt": 0,
  • "endAt": 0,
  • "stripePromotionCode": "string",
  • "targetPlanIds": [
    ]
}

Response samples

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

后台一键发布 Labnana 图片

manager-server 内部接口，使用专用 Bearer API Key。

置公开 + 私桶→公桶迁移 + reviewStatus=approved 走用户侧 PUT /v1/banana/images/public 的同一条链路，只跳过订阅墙与所有者校验， 因此 manager 不必（也不允许）直写 isPublic——直写会漏掉桶迁移， 结果是库里公开、CDN 上取不到图。

后台一键即人工终审：不触发 AI 审核，reviewStatus=rejected 的图也会被改判为 approved，改判会打 banana:image:internalPublish:reviewOverride 日志。

认证方式：

  • Header: Authorization: Bearer <internal_api_key>
  • Key 取 config.internalApiKeys.managerServer，未配置时一律 401（fail closed）
Authorizations:
None
Request Body schema: application/json
required
imageId
required
string^[0-9a-fA-F]{24}$

Labnana 图片 ID

Responses

Request samples

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

Response samples

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

内部审核接口

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

注意：此接口仅供内部服务调用，需要使用内部 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": {
    }
}