API Reference / Introduction
Introduction
Explore the Qavix API reference with comprehensive guides, code examples, and endpoint documentation. Integrate powerful AI video translation, voice synthesis, and smart editing into your applications.
Base URL
https://qavixi.com/qavixAuthentication
All OpenAPI requests must include your API Key in the `Authorization` header for authentication, format: `Bearer `.
| Header | Description |
|---|---|
| Authorization | Format: 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 空请求体即可）。
Response
| 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)）。 |
POST
声音克隆
创建声音克隆（同步接口，返回音色 ID）。
Request Parameters
audioUrlstringREQUIRED
音频可下载 URL。
namestringREQUIRED
音色名称。
formatstring
音频格式（未传默认 mp3）。
Response
| Field | Description |
|---|---|
| result.timbreId | 音色 ID（integer(int64)），后续可用于 TTS。 |
文件接口
POST
获取上传权限
获取对象存储直传权限（上传凭证）。
Request Parameters
fileNamestringREQUIRED
原始文件名（仅用于展示/后缀判断，实际上传名由后端返回）。
fileMd5stringREQUIRED
文件 MD5（32位，大小写均可）。
fileSizeinteger(int64)REQUIRED
文件大小，单位字节。
sourcestring
业务来源（可不传，服务端默认 openapi）。
formatstring
文件格式（可不传，服务端可从 fileName 推导）。
Response
| 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 | 存储桶名称（部分场景可能为空）。 |
POST
上传完成（返回临时下载 URL）
通知服务端上传完成，并返回临时可下载 URL（推荐后续任务接口直接使用该 URL）。
Request Parameters
fileIdinteger(int64)REQUIRED
upload/privilege 返回的 fileId。
Response
| Field | Description |
|---|---|
| result.fileId | 文件记录 ID（integer(int64)）。 |
| result.url | 推荐使用：临时可下载 URL。 |
| result.expiresAt | URL 过期时间（UTC ISO-8601）。 |
| result.tmpUrl | 兼容字段（与 result.url 含义一致）。 |
POST
刷新临时下载 URL
刷新文件临时下载 URL（不改变文件记录，仅重新签发临时 URL）。
Request Parameters
fileIdinteger(int64)REQUIRED
文件记录 ID。
Response
| Field | Description |
|---|---|
| result.fileId | 文件记录 ID（integer(int64)）。 |
| result.url | 新签发的临时下载 URL（推荐使用）。 |
| result.expiresAt | 新 URL 过期时间。 |
| result.tmpUrl | 兼容字段。 |
音频任务接口
POST
文本转语音创建
提交 TTS 任务，返回任务 ID。
Request Parameters
textstringREQUIRED
待合成文本。
timbreinteger(int64)REQUIRED
音色 ID（可由音色列表接口获取）。
langstring
语言代码（不传可自动检测）。
Response
| Field | Description |
|---|---|
| result.taskId | TTS 任务 ID（string）。 |
POST
文本转语音结果查询
查询 TTS 任务状态与结果。
Request Parameters
taskIdinteger(int64)REQUIRED
任务 ID。
Response
| 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）。 |
视频任务接口
POST
视频翻译
创建视频翻译任务。
Request Parameters
videoUrlstringREQUIRED
源视频可下载 URL。
originalLangstringREQUIRED
原始语言代码。
destLangstringREQUIRED
目标语言代码。
timbrestring
音色标识（TTS）。
videoNamestring
任务显示名称。
formatstring
视频格式（可自动探测）。
llmModelinteger(int32)
大模型类型（平台定义）。
sizeinteger(int32)
文件大小（字节）。
timeSpanstring
视频时长（秒，自动探测失败时建议传）。
Response
| Field | Description |
|---|---|
| result.taskId | 任务 ID（TaskIdDto.taskId，string 返回，避免精度问题）。 |
POST
智能擦除
创建字幕/水印擦除任务。
Request Parameters
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 字幕 + 水印。
Response
| Field | Description |
|---|---|
| result.taskId | 任务 ID（TaskIdDto.taskId，string 返回，避免精度问题）。 |
POST
字幕翻译
创建字幕翻译/提取任务。
Request Parameters
videoUrlstringREQUIRED
源视频可下载 URL。
originalLangstringREQUIRED
原始语言代码。
destLangstringREQUIRED
目标语言代码。
videoNamestring
任务显示名称。
videoWidthnumber(double)
视频宽度（像素）。
videoHeightnumber(double)
视频高度（像素）。
formatstring
视频格式（可自动探测）。
sizeinteger(int32)
文件大小（字节）。
timeSpanstring
视频时长（秒，自动探测失败时建议传）。
embedSubtitleToVideoboolean
是否将字幕压制到视频，默认 true。
Response
| Field | Description |
|---|---|
| result.taskId | 任务 ID（TaskIdDto.taskId，string 返回，避免精度问题）。 |
POST
口型同步
创建口型同步任务。
Request Parameters
videoUrlstringREQUIRED
源视频可下载 URL。
audioUrlstringREQUIRED
源音频可下载 URL。
videoNamestring
任务显示名称。
formatstring
视频格式（可自动探测）。
sizeinteger(int32)
视频大小（字节）。
Response
| Field | Description |
|---|---|
| result.taskId | 任务 ID（TaskIdDto.taskId，string 返回，避免精度问题）。 |
POST
视频换脸
创建视频换脸任务。
Request Parameters
videoUrlstringREQUIRED
源视频可下载 URL（待换脸视频）。
imageUrlstringREQUIRED
人脸图片可下载 URL（目标人脸图片）。
videoNamestring
任务显示名称。
formatstring
视频格式（未传时服务端会尝试自动探测）。
sizeinteger(int32)
视频大小（字节）。
Response
| Field | Description |
|---|---|
| result.taskId | 任务 ID（通常与其他视频任务创建接口一致，TaskIdDto.taskId，string 返回）。 |
任务查询接口
POST
任务查询
查询任务信息（适用于视频类任务结果查询）。
Request Parameters
taskIdinteger(int64)REQUIRED
任务 ID（创建任务接口返回）。
Response
| 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）。 |
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 Codes
| Status | Description |
|---|---|
| -1 | Deleted |
| 0 | Initial/Processing |
| 1 | Completed |
| 2 | Failed |
| 3 | Editing |
| 10 | Violation |
Error Codes
| Code | Description |
|---|---|
| 0 | Success |
| 4001 | User not logged in |
| 4002 | Feature disabled |
| 4003 | Limit reached |
| 4004 | Resource not found or no permission |
| 4005 | Parameter required |
| 429 | Rate limit exceeded |
| 5000 | System error |
| 5001 | Operation failed |