接口参考 / 介绍

介绍

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

基准 URL

https://api.oiiyao.com

身份认证

所有 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"
  },
  "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.vocals_url	人声文件 URL（仅 audio_separation 任务返回）
data.output.background_url	背景音乐文件 URL（仅 audio_separation 任务返回）
data.output.expires_at	结果文件 URL 过期时间（ISO 8601），URL 有效期为 2 小时，过期后可通过 POST /files/refresh-url 刷新
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_cloneboolean

是否克隆原视频说话人声音（默认 false）。为 true 时忽略 voice_id

voice_idstring

音色 ID（voice_clone 为 false 时必填）。可通过 GET /voices 获取可用音色列表

namestring

任务名称

callback_urlstring

任务完成回调 URL

idempotency_keystring

幂等键（防止重复提交）

响应参数

字段	描述
data.task_id	任务 ID
data.task_type	任务类型
data.status	任务状态

ApiKey:

Get ApiKey

Base URL:

POST

智能擦除

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

请求参数

video_urlstring必填

源视频 URL（HTTPS）

namestring

任务名称

normalized_regionsarray<object>

擦除区域数组（erasure_mode 为 manual/protect 时必填，当前仅使用第一个区域）。每项包含：x（左边缘，0-1）、y（上边缘，0-1）、width（宽度，0-1）、height（高度，0-1）。坐标相对于视频宽高的比例

erasure_modestring

擦除模式（默认 auto）：auto=自动识别字幕/水印位置并擦除，无需传 normalized_regions；manual=擦除指定区域内的内容，必须传 normalized_regions；protect=保护指定区域不被擦除（擦除区域外的字幕/水印），必须传 normalized_regions

callback_urlstring

任务完成回调 URL

idempotency_keystring

幂等键

响应参数

字段	描述
data.task_id	任务 ID
data.task_type	任务类型
data.status	任务状态

ApiKey:

Get ApiKey

Base URL:

POST

字幕翻译

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

请求参数

video_urlstring必填

源视频 URL（HTTPS）

source_languagestring必填

源语言代码语言代码

target_languagestring必填

目标语言代码语言代码

namestring

任务名称

callback_urlstring

任务完成回调 URL

idempotency_keystring

幂等键

响应参数

字段	描述
data.task_id	任务 ID
data.task_type	任务类型
data.status	任务状态

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	任务状态

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	任务状态

ApiKey:

Get ApiKey

Base URL:

POST

多人视频翻译

提交多人视频翻译任务。系统自动识别说话人并为每个说话人分配独立音色进行翻译配音。

请求参数

video_urlstring必填

视频文件URL（S3预签名URL或公开可访问的URL）

source_languagestring必填

源语言代码语言代码

target_languagestring必填

目标语言代码语言代码

expected_speaker_countinteger

预期说话人数量（不传则自动检测）

namestring

任务名称（可选）

callback_urlstring

任务完成回调URL

idempotency_keystring

幂等性键（防重复提交）

响应参数

字段	描述
data.task_id	任务 ID
data.task_type	任务类型
data.status	任务状态

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

语言代码语言代码

namestring

任务名称

callback_urlstring

任务完成回调 URL

idempotency_keystring

幂等键

emotionstring

情绪倾向。可选值：auto / neutral / happy / sad / angry / surprised，默认 auto（自动从文本推断）。注：部分克隆声音不支持情绪修改，设置后将自动回退到 auto。

text_normalizationstring

数字 / 日期读法。可选值：auto / on / off，默认 auto。on = 朗读为完整词（例："$5" 朗读为 "five dollars"）；off = 按原文朗读字符。

响应参数

字段	描述
data.task_id	任务 ID
data.task_type	任务类型
data.status	任务状态

ApiKey:

Get ApiKey

Base URL:

POST

人声分离

将音频文件分离为人声和背景音乐两个独立文件。

请求参数

audio_urlstring必填

音频文件URL（S3预签名URL或公开可访问的URL）

namestring

任务名称（可选）

callback_urlstring

任务完成回调URL

idempotency_keystring

幂等性键（防重复提交）

响应参数

字段	描述
data.task_id	任务 ID
data.task_type	任务类型
data.status	任务状态

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	视频翻译
multi_speaker_translation	多人视频翻译
lip_sync	口型同步
smart_erasure	智能擦除
subtitle_translation	字幕翻译
face_swap	视频换脸
voice_clone	声音克隆
text_to_speech	文本转语音
audio_separation	人声分离

语言代码

API 接受 ISO 639-1 标准语言代码。以下为支持的源语言和目标语言列表。

源语言（source_language）

代码	语言
zh	中文
en	英语
ja	日语
ko	韩语
ru	俄语
de	德语
fr	法语
ar	阿拉伯语
es	西班牙语
it	意大利语
vi	越南语
pt	葡萄牙语
ms	马来语
tl	菲律宾语
id	印尼语
nl	荷兰语
th	泰语
no	挪威语
ca	加泰罗尼亚语
bn	孟加拉语
sr	塞尔维亚语
yue	广东话

目标语言（target_language）

代码	语言
zh	中文
en	英语
ja	日语
ko	韩语
ru	俄语
de	德语
fr	法语
ar	阿拉伯语
es	西班牙语
it	意大利语
vi	越南语
pt	葡萄牙语
pt-BR	巴西葡萄牙语
ms	马来语
tl	菲律宾语
id	印尼语
nl	荷兰语
th	泰语
no	挪威语
ca	加泰罗尼亚语
bn	孟加拉语
sr	塞尔维亚语
cs	捷克语
bg	保加利亚语
pl	波兰语
ro	罗马尼亚语
sv	瑞典语
ta	泰米尔语
tr	土耳其语
uk	乌克兰语
el	希腊语
hi	印地语
fi	芬兰语
hr	克罗地亚语
sk	斯洛伐克语
da	丹麦语
hu	匈牙利语
fa	波斯语