接口参考 / 介绍

介绍

Oiiyao API 接口参考,包含端点文档、代码示例和请求参数说明。通过 API 接入视频翻译、多人翻译、智能擦除、字幕翻译、视频换脸、口型同步等视频处理能力,以及声音克隆、文本转语音等音频处理能力。

基准 URL

https://api.oiiyao.com

身份认证

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

需要 API Key?

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

前往控制台
请求头描述
Authorization格式:Bearer YOUR_API_KEY
Accept-Language可选。报错信息与显示名(如 age_range、声音名称、计价说明)的语言:传 en 返回英文,不传默认中文。程序判断请用 error.code、task_type、age_range_code、voice_id 等编码字段,不要比较这些文本。官方 SDK(Java、Python、JavaScript)暂无语言选项,也不会发送这个请求头;需要英文返回时,请直接调用 HTTP 接口并带上 Accept-Language: en。

响应格式

所有 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"
  }
}

响应字段说明

字段类型描述
successboolean请求是否成功
dataobject业务数据对象
usageobject积分使用信息(仅在消耗积分时返回)
usage.credits_usedinteger本次预计消耗积分(提交时的预估值)。视频类任务提交时还没探测时长,可能不返回;实际扣除以任务结束后任务详情里的 credits_used 为准
usage.credits_remaininginteger剩余积分
errorobject错误信息对象(仅在失败时返回)
error.typestring错误类型标识
error.codestring错误代码,供程序分支处理。常见取值:missing_field / invalid_param(请求参数问题)、business_error(业务校验未通过)、insufficient_credits(积分不足)、rate_limit_exceeded(请求过于频繁)、duplicate_request(同一个 idempotency_key 的上一次请求还在处理:HTTP 200 且 success 为 false,稍后用同一个键原样重试即可拿到第一次的结果,不要换键重提,否则会重复扣费)、10100(服务端内部错误,与请求参数无关,可稍后原样重试);鉴权与 URL 校验失败为数字代码
error.messagestring错误描述,可直接展示给用户;按请求头 Accept-Language 返回中文或英文,不带时为中文
error.paramstring相关参数名称(可选)

异步任务与回调

所有生成类接口都是异步的:提交后立刻返回 task_id,成品要么靠轮询任务详情拿到,要么等我们把结果回调到你的 callback_url。

完整闭环

  1. 1

    提交任务,从响应的 data.task_id 拿到任务编号。

  2. 2

    轮询任务详情接口查看进度,直到状态进入终态。四种状态的含义见任务状态

  3. 3

    任务完成后,从 data.output 里取产物地址;字段随任务类型不同。

  4. 4

    产物地址是有时效的临时签名地址,过期后换一个新地址:刷新下载地址

回调协议

项目取值
请求方式POST
内容类型application/json
字段命名snake_case
成功判据你的服务返回 2xx 即视为送达
单次超时15s
失败重试失败后重试 3 次,间隔 1 秒、5 秒、30 秒(含首次共 4 次)

回调请求体样例

{
  "event": "task.completed",
  "task_id": "551",
  "status": "completed",
  "timestamp": "2026-01-01T12:00:00Z",
  "task_type": "video_translation",
  "output": {
    "video_url": "https://files.oiiyao.com/...",
    "subtitle_url": "https://files.oiiyao.com/..."
  }
}

接入前请注意

  • output 的字段随任务类型不同:人声分离是 vocals_url 与 background_url,文本配音是 audio_url,其余任务是 video_url 与 subtitle_url。
  • 失败回调只带 status 为 failed,请求体里没有失败原因字段;要拿原因请再调一次任务详情接口,看返回的 error_message。
  • callback_url 必须是公网可达的 http(s) 地址;没通过安全校验的地址会被直接跳过,且不会有任何通知。
  • 回调里的产物地址同样是临时签名地址,且请求体里不带过期时间,请收到后尽快转存。
  • 回调请求没有签名。建议把 callback_url 设成一个不可猜测的地址,并在收到后按 task_id 反查任务详情确认。

账户

GET

查询余额

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

响应参数

字段描述
data.credits_remaining剩余积分
data.plan当前套餐
data.expires_at套餐到期时间
data.rate_limits速率限制信息
data.rate_limits.requests_per_minute每分钟请求数限制
data.rate_limits.queries_per_second每秒查询数限制
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是否有更多数据
GET

定价查询

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

响应参数

字段描述
data.pricing定价列表
data.pricing[].task_type任务类型
data.pricing[].credits_per_minute每分钟消耗积分
data.pricing[].description任务类型的显示名(随 Accept-Language)
data.pricing[].language语言

任务

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),URL 有效期为 2 小时,过期后可通过 POST /files/refresh-url 刷新
data.credits_used实际扣除的积分(以结算为准)。仅 completed / failed 时返回:completed 为最终结算值,可能与提交时 usage.credits_used 的预估不同;failed 时冻结的积分已退回,一般为 0(多人翻译角色精配里已经克隆成功的角色音色费不退,会计入)
data.created_at创建时间(ISO 8601)
data.completed_at完成时间(ISO 8601)
data.error_message失败原因(仅 failed 时返回),可直接展示给用户;按请求头 Accept-Language 返回中文或英文,不带时为中文
GET

任务列表

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

查询参数

statusstring

按状态筛选(pending / processing / completed / failed)

task_typestring

按任务类型筛选

cursorstring

分页游标

limitinteger

每页数量(最大 100,默认 20)

响应参数

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

视频

POST

视频翻译

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

请求参数

video_urlstring必填

源视频 URL(HTTPS)

source_languagestring必填

源语言代码语言代码

target_languagestring必填

目标语言代码语言代码

voice_cloneboolean

是否克隆原视频说话人声音(默认 false)。为 true 时忽略 voice_id,并加收克隆费 20 积分/次(按次计费,与视频时长无关)

voice_idstring

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

burn_subtitlesboolean

是否把译文字幕烧录进成片视频(默认 true)。为 false 时成片不带字幕,处理更快,长视频尤其明显

erase_original_subtitlesboolean

是否先擦掉原视频画面里烧录的字幕再合成(默认 false)。原片带硬字幕却不擦,新旧字幕会叠在一起。按字幕擦除附加费另计。源视频需不超过 1080P(长边不超过 1920 像素),更高分辨率请先压到 1080P 再提交

subtitle_sourcestring

原字幕从哪里取(默认 audio):audio=识别语音;screen=识别画面里烧录的字幕,适合没有人声、只有画面文字的视频。screen 仅支持 source_language 为 zh 或 en,且不能与 voice_clone=true 同用

lip_syncboolean

是否按译文配音重做口型(默认 false),适合出镜人对着镜头说话的视频。按口型同步附加费另计,处理时间更长

namestring

任务名称

callback_urlstring

任务完成回调 URL

idempotency_keystring

幂等键(防止重复提交)

响应参数

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

请求直达正式环境,提交成功即在你的账户下创建任务并扣除积分。

POST

智能擦除

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

请求参数

video_urlstring必填

源视频 URL(HTTPS)

namestring

任务名称

normalized_regionsarray<object>

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

erasure_modestring

擦除模式(默认 auto):auto=自动识别字幕/水印位置并擦除,无需传 normalized_regions;manual=擦除指定区域内的内容,必须传 normalized_regions

callback_urlstring

任务完成回调 URL

idempotency_keystring

幂等键

响应参数

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

请求直达正式环境,提交成功即在你的账户下创建任务并扣除积分。

POST

字幕翻译

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

请求参数

video_urlstring必填

源视频 URL(HTTPS)

source_languagestring必填

源语言代码语言代码

target_languagestring必填

目标语言代码语言代码

namestring

任务名称

callback_urlstring

任务完成回调 URL

idempotency_keystring

幂等键

响应参数

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

请求直达正式环境,提交成功即在你的账户下创建任务并扣除积分。

POST

视频换脸

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

请求参数

video_urlstring必填

源视频 URL(HTTPS)

image_urlstring必填

目标人脸图片 URL(HTTPS)

namestring

任务名称

callback_urlstring

任务完成回调 URL

idempotency_keystring

幂等键

响应参数

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

请求直达正式环境,提交成功即在你的账户下创建任务并扣除积分。

POST

口型同步

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

请求参数

video_urlstring必填

源视频 URL(HTTPS)

audio_urlstring必填

音频文件 URL(HTTPS)

namestring

任务名称

callback_urlstring

任务完成回调 URL

idempotency_keystring

幂等键

响应参数

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

请求直达正式环境,提交成功即在你的账户下创建任务并扣除积分。

POST

多人视频翻译

提交多人视频翻译任务。系统自动识别说话人并为每个说话人分配独立音色进行翻译配音。本接口不支持 subtitle_source 与 lip_sync 参数。

请求参数

video_urlstring必填

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

source_languagestring必填

源语言代码语言代码

target_languagestring必填

目标语言代码语言代码

burn_subtitlesboolean

是否把译文字幕烧录进成片视频(默认 true)。为 false 时成片不带字幕,处理更快,长视频尤其明显

erase_original_subtitlesboolean

是否先擦掉原视频画面里烧录的字幕再合成(默认 false),语义同视频翻译接口。按字幕擦除附加费另计。源视频需不超过 1080P(长边不超过 1920 像素)

namestring

任务名称(可选)

callback_urlstring

任务完成回调URL

idempotency_keystring

幂等性键(防重复提交)

响应参数

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

请求直达正式环境,提交成功即在你的账户下创建任务并扣除积分。

音频

POST

声音克隆

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

请求参数

audio_urlstring必填

音频文件 URL(HTTPS)

namestring必填

声音名称

响应参数

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

请求直达正式环境,提交成功即在你的账户下创建任务并扣除积分。

POST

文本转语音

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

请求参数

textstring必填

待转换文本

voice_idstring必填

声音 ID

languagestring

语言代码语言代码

namestring

任务名称

callback_urlstring

任务完成回调 URL

idempotency_keystring

幂等键

emotionstring

语气。可选值:auto / neutral / happy / sad / angry / surprised / fearful / calm,默认 auto。auto 与 neutral 都表示不做语气演绎(不再从文本自动推断)。注:能否演绎取决于声音背后的模型,不支持时会按原样朗读,可先用查询声音接口确认。

text_normalizationstring

数字 / 日期读法。可选值:auto / on / off,默认 auto。on = 朗读为完整词(例:"$5" 朗读为 "five dollars");off = 按原文朗读字符。

响应参数

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

请求直达正式环境,提交成功即在你的账户下创建任务并扣除积分。

音色库

GET

声音列表

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

查询参数

languagestring

按语言筛选,用语言码表里的两字母码(如 zh);写成 zh-CN 会返回空列表

genderstring

按性别筛选(male / female)

响应参数

字段描述
data[].voice_id声音 ID
data[].name声音名称(显示名,随 Accept-Language:传 en 时中文名的系统声音返回拼音名,其余不变)。引用声音请用 voice_id
data[].language语言
data[].gender性别
data[].age_range年龄段(显示名,随 Accept-Language)
data[].age_range_code年龄段编码:child / young_adult / middle_aged_senior(与语言无关)
data[].preview_url试听 URL
data[].type声音类型:此接口只列系统声音,恒为 system

文件

POST

获取上传地址

获取文件上传预签名 URL,用于直传文件到对象存储。上传后 30 天内没有被任何任务使用的文件会被自动清理,请在此期间提交任务。

请求参数

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(秒传时直接返回)

请求直达正式环境,提交成功即在你的账户下创建任务并扣除积分。

POST

确认上传

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

请求参数

file_idstring必填

文件 ID(由获取上传地址接口返回)

响应参数

字段描述
data.file_id文件 ID
data.url文件下载 URL
data.expires_atURL 过期时间(ISO 8601)

请求直达正式环境,提交成功即在你的账户下创建任务并扣除积分。

POST

刷新下载地址

刷新文件下载 URL(URL 过期后使用)。

请求参数

file_idstring必填

文件 ID

响应参数

字段描述
data.file_id文件 ID
data.url新的文件下载 URL
data.expires_atURL 过期时间(ISO 8601)

请求直达正式环境,提交成功即在你的账户下创建任务并扣除积分。

错误类型

类型HTTP 状态码描述
authentication_error401API Key 缺失、无效或已禁用
validation_error400参数无效、字段缺失、URL 校验失败,或业务校验未通过(code 为 business_error,message 说明具体原因,如不支持的语言)
rate_limit_error429请求频率超限
permission_error403需要 HTTPS 或权限不足
insufficient_credits402积分余额不足(code 为 insufficient_credits),提交时按预估费用校验。视频类任务的积分在下载素材、确定时长后才冻结,此时余额不足任务会以 failed 结束,原因见任务详情的 error_message
not_found404资源不存在
internal_error500服务器内部错误

任务状态

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

任务类型

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

语言代码

API 接受 ISO 639-1 标准语言代码。源语言为语音识别(ASR)支持范围,目标语言为语音合成(TTS)支持范围。以下为支持列表。

源语言(source_language)

代码语言
zh中文
en英语
ja日语
ko韩语
ru俄语
de德语
fr法语
ar阿拉伯语
es西班牙语
it意大利语
vi越南语
pt葡萄牙语
ms马来语
tl菲律宾语
id印尼语
nl荷兰语
th泰语
no挪威语
ca加泰罗尼亚语
bn孟加拉语
sr塞尔维亚语
yue广东话
hi印地语
tr土耳其语
pl波兰语
uk乌克兰语
fa波斯语
ur乌尔都语
sv瑞典语
da丹麦语
fi芬兰语
cs捷克语
hu匈牙利语
ro罗马尼亚语
el希腊语
bg保加利亚语
hr克罗地亚语
sk斯洛伐克语
sl斯洛文尼亚语
et爱沙尼亚语
lv拉脱维亚语
lt立陶宛语
bs波斯尼亚语
mk马其顿语
is冰岛语
sw斯瓦希里语
ta泰米尔语
te泰卢固语
ml马拉雅拉姆语
kn卡纳达语
gu古吉拉特语
mr马拉地语
pa旁遮普语
km高棉语
lo老挝语
my缅甸语
mn蒙古语
ne尼泊尔语
he希伯来语
az阿塞拜疆语
kk哈萨克语
uz乌兹别克语
ky吉尔吉斯语
af南非荷兰语
am阿姆哈拉语
as阿萨姆语
ast阿斯图里亚斯语
be白俄罗斯语
ceb宿务语
cy威尔士语
ff富拉语
ga爱尔兰语
gl加利西亚语
ha豪萨语
hy亚美尼亚语
ig伊博语
jv爪哇语
ka格鲁吉亚语
kea卡布佛得鲁语
ku库尔德语
lb卢森堡语
lg卢干达语
ln林加拉语
luo卢奥语
mi毛利语
mt马耳他语
nso北索托语
ny齐切瓦语
oc奥克语
or奥里亚语
ps普什图语
sd信德语
sn绍纳语
so索马里语
tg塔吉克语
umb翁本杜语
wo沃洛夫语
xh科萨语
zu祖鲁语

目标语言(target_language)

代码语言
zh中文
en英语
ja日语
ko韩语
ru俄语
de德语
fr法语
ar阿拉伯语
es西班牙语
it意大利语
vi越南语
pt葡萄牙语
id印尼语
ms马来语
tl菲律宾语
nl荷兰语
th泰语
tr土耳其语
pl波兰语
uk乌克兰语
sv瑞典语
cs捷克语
el希腊语
hi印地语
fi芬兰语
da丹麦语
no挪威语
hu匈牙利语
ro罗马尼亚语
sk斯洛伐克语
hr克罗地亚语
bg保加利亚语
sr塞尔维亚语
ca加泰罗尼亚语
fa波斯语
ta泰米尔语
bn孟加拉语
af南非荷兰语
hy亚美尼亚语
as阿萨姆语
az阿塞拜疆语
be白俄罗斯语
bs波斯尼亚语
ceb宿务语
ny齐切瓦语
et爱沙尼亚语
gl加利西亚语
ka格鲁吉亚语
gu古吉拉特语
ha豪萨语
he希伯来语
is冰岛语
ga爱尔兰语
jv爪哇语
kn卡纳达语
kk哈萨克语
ky吉尔吉斯语
lv拉脱维亚语
ln林加拉语
lt立陶宛语
lb卢森堡语
mk马其顿语
ml马拉雅拉姆语
mr马拉地语
ne尼泊尔语
ps普什图语
pa旁遮普语
sd信德语
sl斯洛文尼亚语
so索马里语
sw斯瓦希里语
te泰卢固语
ur乌尔都语
cy威尔士语

© 2026 Oiiyao Tech. 保留所有权利。