接口参考 / 介绍

介绍

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

基准 URL

https://qavixi.com/qavix

身份认证

所有 API 请求必须在 Authorization 请求头中包含您的 API Key，格式为 Bearer 。

需要 API Key？

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

前往控制台

请求头	描述
Authorization	格式：Bearer

响应格式

所有 API 响应使用统一的 JSON 格式包裹。

成功响应

{
  "success": true,
  "data": {
    "task_id": "551",
    "task_type": "video_translation",
    "status": "pending",
    "estimated_credits": 60
  },
  "usage": {
    "credits_used": 60,
    "credits_remaining": 10000
  }
}

错误响应

{
  "success": false,
  "error": {
    "type": "validation_error",
    "code": "missing_field",
    "message": "video_url is required",
    "param": "video_url"
  }
}

响应字段说明

字段	类型	描述
success	boolean	请求是否成功
data	object	业务数据对象
usage	object	积分使用信息（仅在消耗积分时返回）
usage.credits_used	integer	本次消耗积分
usage.credits_remaining	integer	剩余积分
error	object	错误信息对象（仅在失败时返回）
error.type	string	错误类型标识
error.code	string	错误代码
error.message	string	错误描述信息
error.param	string	相关参数名称（可选）

账户

GET

查询余额

查询当前账户积分余额和速率限制信息。

响应参数

字段	描述
data.credits_remaining	剩余积分
data.plan	当前套餐
data.expires_at	套餐到期时间
data.rate_limits	速率限制信息
data.rate_limits.requests_per_minute	每分钟请求数限制
data.rate_limits.queries_per_second	每秒查询数限制

ApiKey:

Get ApiKey

Base URL:

GET

使用记录

查询账户积分使用记录，支持按日期范围筛选和游标分页。

查询参数

start_datestring

开始日期（格式：yyyy-MM-dd）

end_datestring

结束日期（格式：yyyy-MM-dd）

cursorstring

分页游标（从上一次响应的 next_cursor 获取）

limitinteger

每页数量（最大 100，默认 20）

响应参数

字段	描述
data.records	使用记录列表
data.records[].task_id	任务 ID
data.records[].task_type	任务类型
data.records[].credits_used	消耗积分
data.records[].created_at	创建时间（ISO 8601）
data.total_credits_used	总消耗积分
data.next_cursor	下一页游标
data.has_more	是否有更多数据

ApiKey:

Get ApiKey

Base URL:

GET

定价查询

查询所有任务类型的积分定价。

响应参数

字段	描述
data.pricing	定价列表
data.pricing[].task_type	任务类型
data.pricing[].credits_per_minute	每分钟消耗积分
data.pricing[].description	描述
data.pricing[].language	语言

ApiKey:

Get ApiKey

Base URL:

任务

GET

查询任务

根据任务 ID 查询任务详情，包括处理状态和结果文件。

路径参数

task_idstring必填

任务 ID

响应参数

字段	描述
data.task_id	任务 ID
data.task_type	任务类型
data.status	任务状态（pending / processing / completed / failed）
data.progress	处理进度（0-100）
data.name	任务名称
data.source_language	源语言
data.target_language	目标语言
data.output	输出文件信息
data.output.video_url	结果视频 URL
data.output.subtitle_url	字幕文件 URL
data.output.audio_url	音频文件 URL
data.output.expires_at	URL 过期时间（ISO 8601）
data.credits_used	消耗积分
data.created_at	创建时间（ISO 8601）
data.completed_at	完成时间（ISO 8601）
data.error_message	错误信息（仅失败时返回）

ApiKey:

Get ApiKey

Base URL:

GET

任务列表

查询任务列表，支持按状态和类型筛选，使用游标分页。

查询参数

statusstring

按状态筛选（pending / processing / completed / failed）

task_typestring

按任务类型筛选

cursorstring

分页游标

limitinteger

每页数量（最大 100，默认 20）

响应参数

字段	描述
data.tasks	任务列表
data.next_cursor	下一页游标
data.has_more	是否有更多数据

ApiKey:

Get ApiKey

Base URL:

视频

POST

视频翻译

创建视频翻译任务，支持多语言翻译和配音。

请求参数

video_urlstring必填

源视频 URL（HTTPS）

source_languagestring必填

源语言代码

target_languagestring必填

目标语言代码

voice_idstring

配音声音 ID

namestring

任务名称

callback_urlstring

任务完成回调 URL

idempotency_keystring

幂等键（防止重复提交）

响应参数

字段	描述
data.task_id	任务 ID
data.task_type	任务类型
data.status	任务状态
data.estimated_credits	预估消耗积分

ApiKey:

Get ApiKey

Base URL:

POST

智能擦除

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

请求参数

video_urlstring必填

源视频 URL（HTTPS）

namestring

任务名称

normalized_regionsarray<object>

擦除区域数组（归一化坐标 0-1），每项含 x, y, width, height, type（1=水印, 2=字幕）

erasure_modestring

擦除模式：auto / manual / protect

callback_urlstring

任务完成回调 URL

idempotency_keystring

幂等键

响应参数

字段	描述
data.task_id	任务 ID
data.task_type	任务类型
data.status	任务状态
data.estimated_credits	预估消耗积分

ApiKey:

Get ApiKey

Base URL:

POST

字幕翻译

创建字幕翻译任务，提取视频语音并翻译为字幕。

请求参数

video_urlstring必填

源视频 URL（HTTPS）

source_languagestring必填

源语言代码

target_languagestring必填

目标语言代码

namestring

任务名称

embed_subtitleboolean

是否将字幕压制到视频（默认 true）

callback_urlstring

任务完成回调 URL

idempotency_keystring

幂等键

响应参数

字段	描述
data.task_id	任务 ID
data.task_type	任务类型
data.status	任务状态
data.estimated_credits	预估消耗积分

ApiKey:

Get ApiKey

Base URL:

POST

视频换脸

创建视频换脸任务，将视频中人脸替换为指定图片中的人脸。

请求参数

video_urlstring必填

源视频 URL（HTTPS）

image_urlstring必填

目标人脸图片 URL（HTTPS）

namestring

任务名称

callback_urlstring

任务完成回调 URL

idempotency_keystring

幂等键

响应参数

字段	描述
data.task_id	任务 ID
data.task_type	任务类型
data.status	任务状态
data.estimated_credits	预估消耗积分

ApiKey:

Get ApiKey

Base URL:

POST

口型同步

创建口型同步任务，使视频中人物口型与音频同步。

请求参数

video_urlstring必填

源视频 URL（HTTPS）

audio_urlstring必填

音频文件 URL（HTTPS）

namestring

任务名称

callback_urlstring

任务完成回调 URL

idempotency_keystring

幂等键

响应参数

字段	描述
data.task_id	任务 ID
data.task_type	任务类型
data.status	任务状态
data.estimated_credits	预估消耗积分

ApiKey:

Get ApiKey

Base URL:

音频

POST

声音克隆

从音频样本克隆声音，同步接口，返回声音 ID。

请求参数

audio_urlstring必填

音频文件 URL（HTTPS）

namestring必填

声音名称

响应参数

字段	描述
data.voice_id	声音 ID
data.name	声音名称
data.type	声音类型

ApiKey:

Get ApiKey

Base URL:

POST

文本转语音

创建文本转语音任务，异步处理。

请求参数

textstring必填

待转换文本

voice_idstring必填

声音 ID

languagestring

语言代码

callback_urlstring

任务完成回调 URL

idempotency_keystring

幂等键

响应参数

字段	描述
data.task_id	任务 ID
data.task_type	任务类型
data.status	任务状态
data.estimated_credits	预估消耗积分

ApiKey:

Get ApiKey

Base URL:

声音库

GET

声音列表

查询可用的声音列表，支持按语言和性别筛选。

查询参数

languagestring

按语言筛选（如 zh-CN）

genderstring

按性别筛选（male / female）

响应参数

字段	描述
data[].voice_id	声音 ID
data[].name	声音名称
data[].language	语言
data[].gender	性别
data[].accent	口音
data[].age_range	年龄段
data[].preview_url	试听 URL
data[].type	声音类型（system / cloned）

ApiKey:

Get ApiKey

Base URL:

文件

POST

获取上传地址

获取文件上传预签名 URL，用于直传文件到对象存储。

请求参数

file_namestring必填

文件名

file_sizeinteger必填

文件大小（字节）

content_md5string

文件 MD5（可选，用于秒传检测）

响应参数

字段	描述
data.file_id	文件 ID
data.upload_url	预签名上传 URL
data.upload_method	上传方法（PUT）
data.upload_headers	上传所需请求头
data.expires_at	上传 URL 过期时间
data.url	文件下载 URL（秒传时直接返回）

ApiKey:

Get ApiKey

Base URL:

POST

确认上传

确认文件上传完成，获取文件下载 URL。

请求参数

file_idstring必填

文件 ID（由获取上传地址接口返回）

响应参数

字段	描述
data.file_id	文件 ID
data.url	文件下载 URL
data.expires_at	URL 过期时间（ISO 8601）

ApiKey:

Get ApiKey

Base URL:

POST

刷新下载地址

刷新文件下载 URL（URL 过期后使用）。

请求参数

file_idstring必填

文件 ID

响应参数

字段	描述
data.file_id	文件 ID
data.url	新的文件下载 URL
data.expires_at	URL 过期时间（ISO 8601）

ApiKey:

Get ApiKey

Base URL:

错误类型

类型	HTTP 状态码	描述
authentication_error	401	API Key 缺失、无效或已禁用
validation_error	400	参数无效、字段缺失或 URL 校验失败
rate_limit_error	429	请求频率超限
permission_error	403	需要 HTTPS 或权限不足
insufficient_credits	402	积分不足
not_found	404	资源不存在
internal_error	500	服务器内部错误

任务状态

状态	描述
pending	待处理 — 任务已提交，等待处理
processing	处理中 — 任务正在执行
completed	已完成 — 任务成功完成
failed	已失败 — 任务执行失败

任务类型

任务类型	描述
video_translation	视频翻译
lip_sync	口型同步
smart_erasure	智能擦除
subtitle_translation	字幕翻译
face_swap	视频换脸
voice_clone	声音克隆
text_to_speech	文本转语音