接口参考 / 介绍

介绍

探索 Qavix API 接口参考，包含全面的指南、代码示例和端点文档。将强大的 AI 视频翻译、语音合成和智能剪辑集成到您的应用中。

基准 URL

https://qavixi.com/qavix

身份认证

所有 OpenAPI 请求必须在 `Authorization` 请求头中包含您的 API Key 进行身份验证，格式为 `Bearer `。

需要 API Key？

前往开发者控制台申请您的 API Key。

前往控制台

请求头	描述
Authorization	格式：Bearer

通用说明

请求约定

Item	Value	Description
Method	POST	本页列出的所有 OpenAPI 接口均使用 POST 请求。
Content-Type	application/json	请求体统一使用 JSON 格式。
Response	WebResult<T>	所有接口响应均使用统一包裹结构。
Auth	OpenAPI Signature	鉴权/签名方式沿用现有 OpenAPI 规则。

通用响应包裹结构（WebResult<T>）

Name	Type	Required	Description	Example
code	integer	是	返回码，成功通常为 0。	0
message	string	是	返回信息。	success
result	object / null	否	业务返回对象（不同接口字段不同）。	{...}

通用接口

POST

音色列表

获取公共音色列表（无请求参数，POST 空请求体即可）。

响应参数

Field	Description
result	音色列表（array，result: TimbreInfoDto[]；无数据时可能为 null）。
result[].id	音色 ID（integer(int64)）。
result[].name	音色名称。
result[].lang	语种代码。
result[].langName	语种名称。
result[].gender	性别代码（integer(int32)）。
result[].genderStr	性别描述（派生字段）。
result[].accent	口音代码（integer(int32)）。
result[].accentStr	口音描述（派生字段）。
result[].ageRange	年龄段代码（integer(int32)）。
result[].ageRangeStr	年龄段描述（派生字段）。
result[].emotion	情绪代码（integer(int32)）。
result[].emotionStr	情绪描述（派生字段）。
result[].categoryList	品类代码列表（array<integer>）。
result[].categoryStrList	品类描述列表（array<string>，派生字段）。
result[].remark	描述。
result[].source	音色来源（integer(int32)，如 0 其他，1 tk）。
result[].type	音色类型（integer(int32)，如系统/个人/业务克隆）。
result[].auditionUrl	试听地址。
result[].status	状态（integer(int32)，0 启用，1 禁用）。
result[].updateTime	更新时间（yyyy-MM-dd HH:mm:ss）。
result[].createTime	创建时间（yyyy-MM-dd HH:mm:ss）。
result[].hotCount	热度（integer(int32)）。
result[].useCount	使用量（integer(int32)）。
result[].collectCount	收藏量（integer(int32)）。

ApiKey:

Get ApiKey

Base URL:

POST

声音克隆

创建声音克隆（同步接口，返回音色 ID）。

请求参数

audioUrlstringREQUIRED

音频可下载 URL。

namestringREQUIRED

音色名称。

formatstring

音频格式（未传默认 mp3）。

响应参数

Field	Description
result.timbreId	音色 ID（integer(int64)），后续可用于 TTS。

ApiKey:

Get ApiKey

Base URL:

文件接口

POST

获取上传权限

获取对象存储直传权限（上传凭证）。

请求参数

fileNamestringREQUIRED

原始文件名（仅用于展示/后缀判断，实际上传名由后端返回）。

fileMd5stringREQUIRED

文件 MD5（32位，大小写均可）。

fileSizeinteger(int64)REQUIRED

文件大小，单位字节。

sourcestring

业务来源（可不传，服务端默认 openapi）。

formatstring

文件格式（可不传，服务端可从 fileName 推导）。

响应参数

Field	Description
result.fileId	文件记录 ID（integer(int64)），后续 upload/complete / url/refresh 使用。
result.bucketName	存储桶名称。
result.endPoint	存储区域地址。
result.dirPath	文件目录路径（string / null，可能为空）。
result.randomName	后端生成的随机对象名。
result.originalName	原始文件名。
result.uploadComplete	是否已存在同文件（秒传命中）。
result.temporaryAccessKey	临时上传凭证（object / null；秒传命中时可能为空）。
result.temporaryAccessKey.expiresAt	凭证失效时间（通常为 UTC 格式字符串）。
result.temporaryAccessKey.access	临时 Access Key。
result.temporaryAccessKey.secret	临时 Secret Key。
result.temporaryAccessKey.securitytoken	临时安全令牌。
result.temporaryAccessKey.endPoint	存储服务地址。
result.temporaryAccessKey.bucketName	存储桶名称（部分场景可能为空）。

ApiKey:

Get ApiKey

Base URL:

POST

上传完成（返回临时下载 URL）

通知服务端上传完成，并返回临时可下载 URL（推荐后续任务接口直接使用该 URL）。

请求参数

fileIdinteger(int64)REQUIRED

upload/privilege 返回的 fileId。

响应参数

Field	Description
result.fileId	文件记录 ID（integer(int64)）。
result.url	推荐使用：临时可下载 URL。
result.expiresAt	URL 过期时间（UTC ISO-8601）。
result.tmpUrl	兼容字段（与 result.url 含义一致）。

ApiKey:

Get ApiKey

Base URL:

POST

刷新临时下载 URL

刷新文件临时下载 URL（不改变文件记录，仅重新签发临时 URL）。

请求参数

fileIdinteger(int64)REQUIRED

文件记录 ID。

响应参数

Field	Description
result.fileId	文件记录 ID（integer(int64)）。
result.url	新签发的临时下载 URL（推荐使用）。
result.expiresAt	新 URL 过期时间。
result.tmpUrl	兼容字段。

ApiKey:

Get ApiKey

Base URL:

音频任务接口

POST

文本转语音创建

提交 TTS 任务，返回任务 ID。

请求参数

textstringREQUIRED

待合成文本。

timbreinteger(int64)REQUIRED

音色 ID（可由音色列表接口获取）。

langstring

语言代码（不传可自动检测）。

响应参数

Field	Description
result.taskId	TTS 任务 ID（string）。

ApiKey:

Get ApiKey

Base URL:

POST

文本转语音结果查询

查询 TTS 任务状态与结果。

请求参数

taskIdinteger(int64)REQUIRED

任务 ID。

响应参数

Field	Description
result.taskId	任务 ID（integer(int64)）。
result.lang	文本语言。
result.destFileId	生成音频文件 ID（integer(int64)）。
result.destFileTmpUrl	生成音频临时访问 URL。
result.timbre	音色 ID（integer(int64)）。
result.timbreName	音色名称。
result.status	任务状态（integer(int32)）：-1 删除，0 初始，1 完成，2 失败。
result.process	处理进度（integer(int32)，0-100）。

ApiKey:

Get ApiKey

Base URL:

视频任务接口

POST

视频翻译

创建视频翻译任务。

请求参数

videoUrlstringREQUIRED

源视频可下载 URL。

originalLangstringREQUIRED

原始语言代码。

destLangstringREQUIRED

目标语言代码。

timbrestring

音色标识（TTS）。

videoNamestring

任务显示名称。

formatstring

视频格式（可自动探测）。

llmModelinteger(int32)

大模型类型（平台定义）。

sizeinteger(int32)

文件大小（字节）。

timeSpanstring

视频时长（秒，自动探测失败时建议传）。

响应参数

Field	Description
result.taskId	任务 ID（TaskIdDto.taskId，string 返回，避免精度问题）。

ApiKey:

Get ApiKey

Base URL:

POST

智能擦除

创建字幕/水印擦除任务。

请求参数

videoUrlstringREQUIRED

源视频可下载 URL。

videoNamestring

任务显示名称。

regionarray<array<number>>

单区域矩形坐标（4个点，顺时针）。

multiRegionsarray<object>

多区域擦除配置（带类型）。

multiRegions[].regionarray<array<number>>REQUIRED

区域坐标（4点矩形）。

multiRegions[].typeinteger(int32)REQUIRED

区域擦除类型：1=水印（logo_erase），2=字幕（text_erase）。

formatstring

视频格式（可自动探测）。

sizeinteger(int32)

文件大小（字节）。

timeSpanstring

视频时长（秒，自动探测失败时建议传）。

modelTypeinteger(int32)

旧版模式字段（兼容）。参考值：-2 不需要去除，1 自动模式，2 手动框选，3 保护模式。

subtitleRemovalinteger(int32)

新版擦除模式（建议传），优先级高于 modelType。参考值：-2 不需要去除，1 自动模式，2 手动框选，3 保护模式。

erasureTypeinteger(int32)

擦除类型（Polaris 场景）。参考值：1 字幕，2 水印，3 字幕 + 水印。

响应参数

Field	Description
result.taskId	任务 ID（TaskIdDto.taskId，string 返回，避免精度问题）。

ApiKey:

Get ApiKey

Base URL:

POST

字幕翻译

创建字幕翻译/提取任务。

请求参数

videoUrlstringREQUIRED

源视频可下载 URL。

originalLangstringREQUIRED

原始语言代码。

destLangstringREQUIRED

目标语言代码。

videoNamestring

任务显示名称。

videoWidthnumber(double)

视频宽度（像素）。

videoHeightnumber(double)

视频高度（像素）。

formatstring

视频格式（可自动探测）。

sizeinteger(int32)

文件大小（字节）。

timeSpanstring

视频时长（秒，自动探测失败时建议传）。

embedSubtitleToVideoboolean

是否将字幕压制到视频，默认 true。

响应参数

Field	Description
result.taskId	任务 ID（TaskIdDto.taskId，string 返回，避免精度问题）。

ApiKey:

Get ApiKey

Base URL:

POST

口型同步

创建口型同步任务。

请求参数

videoUrlstringREQUIRED

源视频可下载 URL。

audioUrlstringREQUIRED

源音频可下载 URL。

videoNamestring

任务显示名称。

formatstring

视频格式（可自动探测）。

sizeinteger(int32)

视频大小（字节）。

响应参数

Field	Description
result.taskId	任务 ID（TaskIdDto.taskId，string 返回，避免精度问题）。

ApiKey:

Get ApiKey

Base URL:

POST

视频换脸

创建视频换脸任务。

请求参数

videoUrlstringREQUIRED

源视频可下载 URL（待换脸视频）。

imageUrlstringREQUIRED

人脸图片可下载 URL（目标人脸图片）。

videoNamestring

任务显示名称。

formatstring

视频格式（未传时服务端会尝试自动探测）。

sizeinteger(int32)

视频大小（字节）。

响应参数

Field	Description
result.taskId	任务 ID（通常与其他视频任务创建接口一致，TaskIdDto.taskId，string 返回）。

ApiKey:

Get ApiKey

Base URL:

任务查询接口

POST

任务查询

查询任务信息（适用于视频类任务结果查询）。

请求参数

taskIdinteger(int64)REQUIRED

任务 ID（创建任务接口返回）。

响应参数

Field	Description
result.taskId	任务 ID（integer(int64)）。
result.name	视频名称。
result.format	文件格式。
result.coverUrl	封面图 URL。
result.originalLang	原始语言。
result.destLang	翻译语言。
result.destFileId	翻译后视频文件 ID（integer(int64)）。
result.destFileTmpUrl	翻译后视频临时访问 URL。
result.timbre	音色 ID / 克隆音色标识。
result.soundCloneId	实际 TTS 合成使用的音色 ID。
result.destSrtFileId	字幕文件 ID（JSON 中按字符串输出）。
result.destStrTmpUrl	字幕文件临时访问 URL（历史字段名拼写为 Str）。
result.originalRtasrInfo	音轨转写信息（通常为 JSON 字符串）。
result.destRtasrInfo	转写 + 翻译信息（通常为 JSON 字符串）。
result.status	整体状态（integer(int32)）。
result.process	处理进度（integer(int32)，通常 0~100）。

ApiKey:

Get ApiKey

Base URL:

URL 安全校验

服务端会对用户传入的 videoUrl、audioUrl 等 URL 做统一安全校验（SSRF 防护）。校验失败返回 HTTP 400。

仅允许 http / https 协议。
禁止 URL 中包含 user:pass@host。
拦截 localhost / 内网 / 链路本地 / metadata 地址。
支持配置域名白名单（额外收紧，不绕过内网拦截）。

Code	Name	Description
10020	URL_INVALID	URL 格式不合法
10021	URL_SCHEME_NOT_ALLOWED	协议不允许（非 http/https 或缺少协议）
10022	URL_USERINFO_NOT_ALLOWED	URL 包含 user:pass@host
10023	URL_HOST_INVALID	主机名非法或缺失
10024	URL_HOST_BLOCKED	localhost / .local / metadata 等被拦截
10025	URL_HOST_UNRESOLVED	域名无法解析
10026	URL_ADDRESS_BLOCKED	DNS 解析到内网/本地地址
10027	URL_HOST_NOT_ALLOWED	未命中配置白名单
10028	URL_TOO_LONG	URL 长度超限

状态码说明

Status	Description
-1	已删除
0	初始状态/处理中
1	处理完成
2	处理失败
3	编辑中
10	内容违规

错误码

Code	Description
0	成功
4001	用户未登录
4002	功能已禁用
4003	数量达到上限
4004	资源不存在或无权限
4005	参数不能为空
429	请求频率过快
5000	系统异常
5001	操作失败