接口参考 / 介绍

介绍

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

基准 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	相关参数名称（可选）

异步任务与回调

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

完整闭环

1
提交任务，从响应的 data.task_id 拿到任务编号。
2
轮询任务详情接口查看进度，直到状态进入终态。四种状态的含义见任务状态
3
任务完成后，从 data.output 里取产物地址；字段随任务类型不同。
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，请求体里没有失败原因字段；要拿原因请再调一次任务详情接口。
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	每秒查询数限制

ApiKey:

Get ApiKey

Base URL:

curl -X GET "https://api.oiiyao.com/v1/account/balance"

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:

curl -X GET "https://api.oiiyao.com/v1/account/usage?limit=20"

GET

定价查询

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

响应参数

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

ApiKey:

Get ApiKey

Base URL:

curl -X GET "https://api.oiiyao.com/v1/account/pricing"

任务

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	消耗积分
data.created_at	创建时间（ISO 8601）
data.completed_at	完成时间（ISO 8601）
data.error_message	错误信息（仅失败时返回）

ApiKey:

Get ApiKey

Base URL:

curl -X GET "https://api.oiiyao.com/v1/tasks/551"

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:

curl -X GET "https://api.oiiyao.com/v1/tasks?status=completed&limit=20"

视频

POST

视频翻译

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

请求参数

video_urlstring必填

源视频 URL（HTTPS）

source_languagestring必填

源语言代码语言代码

target_languagestring必填

目标语言代码语言代码

voice_cloneboolean

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

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:

curl -X POST "https://api.oiiyao.com/v1/videos/translate" \
  -H "Content-Type: application/json" \
  -d '{
  "video_url": "https://example.com/demo.mp4",
  "source_language": "zh",
  "target_language": "en"
}'

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

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:

curl -X POST "https://api.oiiyao.com/v1/videos/subtitle-remove" \
  -H "Content-Type: application/json" \
  -d '{
  "video_url": "https://example.com/demo.mp4",
  "erasure_mode": "manual",
  "normalized_regions": [
    {
      "x": 0.1,
      "y": 0.8,
      "width": 0.8,
      "height": 0.15
    }
  ]
}'

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

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:

curl -X POST "https://api.oiiyao.com/v1/videos/subtitle-translate" \
  -H "Content-Type: application/json" \
  -d '{
  "video_url": "https://example.com/demo.mp4",
  "source_language": "zh",
  "target_language": "en"
}'

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

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:

curl -X POST "https://api.oiiyao.com/v1/videos/face-swap" \
  -H "Content-Type: application/json" \
  -d '{
  "video_url": "https://example.com/source.mp4",
  "image_url": "https://example.com/face.png"
}'

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

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:

curl -X POST "https://api.oiiyao.com/v1/videos/lip-sync" \
  -H "Content-Type: application/json" \
  -d '{
  "video_url": "https://example.com/video.mp4",
  "audio_url": "https://example.com/audio.wav"
}'

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

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:

curl -X POST "https://api.oiiyao.com/v1/videos/multi-speaker-translate" \
  -H "Content-Type: application/json" \
  -d '{
  "video_url": "https://example.com/drama-video.mp4",
  "source_language": "zh",
  "target_language": "en"
}'

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

音频

POST

声音克隆

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

请求参数

audio_urlstring必填

音频文件 URL（HTTPS）

namestring必填

声音名称

响应参数

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

ApiKey:

Get ApiKey

Base URL:

curl -X POST "https://api.oiiyao.com/v1/audio/voice-clone" \
  -H "Content-Type: application/json" \
  -d '{
  "audio_url": "https://example.com/voice.mp3",
  "name": "my-voice"
}'

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

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

ApiKey:

Get ApiKey

Base URL:

curl -X POST "https://api.oiiyao.com/v1/audio/text-to-speech" \
  -H "Content-Type: application/json" \
  -d '{
  "text": "Hello, welcome to Oiiyao.",
  "voice_id": "voice_abc123",
  "language": "en",
  "emotion": "auto",
  "text_normalization": "auto"
}'

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

音色库

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:

curl -X GET "https://api.oiiyao.com/v1/voices?language=zh"

文件

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:

curl -X POST "https://api.oiiyao.com/v1/files/upload-url" \
  -H "Content-Type: application/json" \
  -d '{
  "file_name": "demo.mp4",
  "file_size": 12345678
}'

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

POST

确认上传

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

请求参数

file_idstring必填

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

响应参数

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

ApiKey:

Get ApiKey

Base URL:

curl -X POST "https://api.oiiyao.com/v1/files/confirm" \
  -H "Content-Type: application/json" \
  -d '{
  "file_id": "123456"
}'

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

POST

刷新下载地址

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

请求参数

file_idstring必填

文件 ID

响应参数

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

ApiKey:

Get ApiKey

Base URL:

curl -X POST "https://api.oiiyao.com/v1/files/refresh-url" \
  -H "Content-Type: application/json" \
  -d '{
  "file_id": "123456"
}'

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

错误类型

类型	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	视频换脸
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	威尔士语