API Reference / Introduction

Introduction

The Oiiyao API reference, with endpoint documentation, code examples, and request parameters. Integrate video processing such as video translation, multi-speaker translation, smart erasure, subtitle translation, face swap, and lip sync, alongside audio processing such as voice cloning and text-to-speech.

Base URL

https://api.oiiyao.com

Authentication

All API requests must include your API Key in the Authorization header, format: Bearer .

Need an API Key?

Go to the Developer Console to apply for your API Key.

Go to Console

Header	Description
Authorization	Format: Bearer

Response Format

All API responses use a unified JSON envelope format.

Success Response

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

Error Response

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

Response Fields

Field	Type	Description
success	boolean	Whether the request was successful
data	object	Business data object
usage	object	Credits usage info (only returned when credits are consumed)
usage.credits_used	integer	Credits consumed by this request
usage.credits_remaining	integer	Remaining credits
error	object	Error info object (only returned on failure)
error.type	string	Error type identifier
error.code	string	Error code
error.message	string	Error description
error.param	string	Related parameter name (optional)

Async tasks and callbacks

Every generation endpoint is asynchronous: the call returns a task_id right away, and you get the result either by polling the task or by waiting for a callback to your callback_url.

End-to-end flow

1
Submit the task and read the task id from data.task_id in the response.
2
Poll the task endpoint until the status reaches a terminal state. SeeTask Statuses
3
When the task completes, read the result URLs from data.output; the fields vary by task type.
4
Result URLs are temporary signed links; get a fresh one when it expires:Refresh URL

Callback protocol

Item	Value
Method	POST
Content type	application/json
Field naming	snake_case
Success	Any 2xx response from your endpoint
Per-attempt timeout	15s
Retries	Up to 3 retries after the first attempt, spaced 1s, 5s and 30s (4 attempts in total)

Callback body example

{
  "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/..."
  }
}

Before you wire it up

The fields inside output depend on the task type: vocals_url and background_url for audio separation, audio_url for text-to-speech, and video_url plus subtitle_url for everything else.
A failed callback only carries status: failed — the body has no error reason. Call the task endpoint to find out why.
callback_url must be a publicly reachable http(s) URL. A URL that fails our security check is skipped silently, with no notice.
The result URLs inside a callback are temporary signed links too, and the body carries no expiry time — copy them to your own storage promptly.
Callbacks are not signed. Use an unguessable callback_url, and confirm each notification by looking its task_id up through the API.

Account

GET

Get Balance

Query current account credit balance and rate limit information.

Response

Field	Description
data.credits_remaining	Remaining credits
data.plan	Current plan
data.expires_at	Plan expiration time
data.rate_limits	Rate limit information
data.rate_limits.requests_per_minute	Requests per minute limit
data.rate_limits.queries_per_second	Queries per second limit

ApiKey:

Get ApiKey

Base URL:

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

GET

Usage History

Query account credit usage history with date range filtering and cursor pagination.

Query Parameters

start_datestring

Start date (format: yyyy-MM-dd)

end_datestring

End date (format: yyyy-MM-dd)

cursorstring

Pagination cursor (from previous response's next_cursor)

limitinteger

Items per page (max 100, default 20)

Response

Field	Description
data.records	Usage records list
data.records[].task_id	Task ID
data.records[].task_type	Task type
data.records[].credits_used	Credits consumed
data.records[].created_at	Created at (ISO 8601)
data.total_credits_used	Total credits consumed
data.next_cursor	Next page cursor
data.has_more	Whether more data exists

ApiKey:

Get ApiKey

Base URL:

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

GET

Pricing

Query credit pricing for all task types.

Response

Field	Description
data.pricing	Pricing list
data.pricing[].task_type	Task type
data.pricing[].credits_per_minute	Credits per minute
data.pricing[].description	Description
data.pricing[].language	Language

ApiKey:

Get ApiKey

Base URL:

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

Tasks

GET

Get Task

Query task details by task ID, including processing status and result files.

Path Parameters

task_idstringREQUIRED

Task ID

Response

Field	Description
data.task_id	Task ID
data.task_type	Task type
data.status	Task status (pending / processing / completed / failed)
data.progress	Processing progress (0-100)
data.name	Task name
data.source_language	Source language
data.target_language	Target language
data.output	Output file information
data.output.video_url	Result video URL
data.output.subtitle_url	Subtitle file URL
data.output.audio_url	Audio file URL (returned for text_to_speech tasks)
data.output.expires_at	Output URL expiration time (ISO 8601). URLs are valid for 2 hours. Use POST /files/refresh-url to get new URLs after expiration
data.credits_used	Credits consumed
data.created_at	Created at (ISO 8601)
data.completed_at	Completed at (ISO 8601)
data.error_message	Error message (only on failure)

ApiKey:

Get ApiKey

Base URL:

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

GET

List Tasks

Query task list with status and type filtering, using cursor pagination.

Query Parameters

statusstring

Filter by status (pending / processing / completed / failed)

task_typestring

Filter by task type

cursorstring

Pagination cursor

limitinteger

Items per page (max 100, default 20)

Response

Field	Description
data.tasks	Task list
data.next_cursor	Next page cursor
data.has_more	Whether more data exists

ApiKey:

Get ApiKey

Base URL:

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

Videos

POST

Video Translation

Create a video translation task with multi-language support and dubbing.

Request Body

video_urlstringREQUIRED

Source video URL (HTTPS)

source_languagestringREQUIRED

Source language codeLanguage Codes

target_languagestringREQUIRED

Target language codeLanguage Codes

voice_cloneboolean

Clone the original speaker's voice (default: false). When true, voice_id is ignored and a flat 20-credit clone fee is added per task (independent of video length)

voice_idstring

Voice ID (required when voice_clone is false). Use GET /voices to list available voices

namestring

Task name

callback_urlstring

Task completion callback URL

idempotency_keystring

Idempotency key (prevents duplicate submissions)

Response

Field	Description
data.task_id	Task ID
data.task_type	Task type
data.status	Task 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"
}'

Requests go to the live API: a successful call creates a task on your account and spends credits.

POST

Smart Eraser

Create a subtitle/watermark removal task.

Request Body

video_urlstringREQUIRED

Source video URL (HTTPS)

namestring

Task name

normalized_regionsarray<object>

Erasure regions array (required when erasure_mode is manual/protect; currently only the first region is used). Each item: x (left edge, 0-1), y (top edge, 0-1), width (0-1), height (0-1). Coordinates are relative to video dimensions

erasure_modestring

Erasure mode (default: auto). auto=auto-detect and erase subtitles/watermarks, no normalized_regions needed; manual=erase content within specified region, normalized_regions required; protect=protect specified region from erasure (erase subtitles/watermarks outside the region), normalized_regions required

callback_urlstring

Task completion callback URL

idempotency_keystring

Idempotency key

Response

Field	Description
data.task_id	Task ID
data.task_type	Task type
data.status	Task 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
    }
  ]
}'

Requests go to the live API: a successful call creates a task on your account and spends credits.

POST

Subtitle Translation

Create a subtitle translation task to extract speech and translate to subtitles.

Request Body

video_urlstringREQUIRED

Source video URL (HTTPS)

source_languagestringREQUIRED

Source language codeLanguage Codes

target_languagestringREQUIRED

Target language codeLanguage Codes

namestring

Task name

callback_urlstring

Task completion callback URL

idempotency_keystring

Idempotency key

Response

Field	Description
data.task_id	Task ID
data.task_type	Task type
data.status	Task 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"
}'

Requests go to the live API: a successful call creates a task on your account and spends credits.

POST

Face Swap

Create a face swap task to replace faces in video with a source image.

Request Body

video_urlstringREQUIRED

Source video URL (HTTPS)

image_urlstringREQUIRED

Target face image URL (HTTPS)

namestring

Task name

callback_urlstring

Task completion callback URL

idempotency_keystring

Idempotency key

Response

Field	Description
data.task_id	Task ID
data.task_type	Task type
data.status	Task 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"
}'

Requests go to the live API: a successful call creates a task on your account and spends credits.

POST

Lip Sync

Create a lip sync task to synchronize lip movements with audio.

Request Body

video_urlstringREQUIRED

Source video URL (HTTPS)

audio_urlstringREQUIRED

Audio file URL (HTTPS)

namestring

Task name

callback_urlstring

Task completion callback URL

idempotency_keystring

Idempotency key

Response

Field	Description
data.task_id	Task ID
data.task_type	Task type
data.status	Task 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"
}'

Requests go to the live API: a successful call creates a task on your account and spends credits.

POST

Multi-Speaker Video Translation

Submit a multi-speaker video translation task. The system automatically identifies speakers and assigns individual voices for translated dubbing.

Request Body

video_urlstringREQUIRED

Video file URL (S3 presigned URL or publicly accessible URL)

source_languagestringREQUIRED

Source language codeLanguage Codes

target_languagestringREQUIRED

Target language codeLanguage Codes

expected_speaker_countinteger

Expected number of speakers (auto-detect if not provided)

namestring

Task name (optional)

callback_urlstring

Callback URL for task completion notification

idempotency_keystring

Idempotency key (prevents duplicate submissions)

Response

Field	Description
data.task_id	Task ID
data.task_type	Task type
data.status	Task 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"
}'

Requests go to the live API: a successful call creates a task on your account and spends credits.

Audio

POST

Voice Clone

Clone a voice from an audio sample. Synchronous API, returns voice ID.

Request Body

audio_urlstringREQUIRED

Audio file URL (HTTPS)

namestringREQUIRED

Voice name

Response

Field	Description
data.voice_id	Voice ID
data.name	Voice name
data.type	Voice 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"
}'

Requests go to the live API: a successful call creates a task on your account and spends credits.

POST

Text to Speech

Create a text-to-speech task, processed asynchronously.

Request Body

textstringREQUIRED

Text to convert

voice_idstringREQUIRED

Voice ID

languagestring

Language codeLanguage Codes

namestring

Task name

callback_urlstring

Task completion callback URL

idempotency_keystring

Idempotency key

emotionstring

Delivery tone. Allowed values: auto / neutral / happy / sad / angry / surprised / fearful / calm. Default: auto. Both auto and neutral mean no tone is applied (it is no longer inferred from the text). Note: whether a tone can be performed depends on the model behind the voice; unsupported voices read the text as written — check the voice lookup endpoint first.

text_normalizationstring

Number / date pronunciation. Allowed values: auto / on / off. Default: auto. on = read as full words (e.g., "$5" → "five dollars"); off = read literal characters.

Response

Field	Description
data.task_id	Task ID
data.task_type	Task type
data.status	Task 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"
}'

Requests go to the live API: a successful call creates a task on your account and spends credits.

Voices

GET

List Voices

Query available voices with language and gender filtering.

Query Parameters

languagestring

Filter by language (e.g., zh-CN)

genderstring

Filter by gender (male / female)

Response

Field	Description
data[].voice_id	Voice ID
data[].name	Voice name
data[].language	Language
data[].gender	Gender
data[].accent	Accent
data[].age_range	Age range
data[].preview_url	Preview URL
data[].type	Voice type (system / cloned)

ApiKey:

Get ApiKey

Base URL:

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

Files

POST

Get Upload URL

Get a pre-signed upload URL for direct file upload to object storage.

Request Body

file_namestringREQUIRED

File name

file_sizeintegerREQUIRED

File size in bytes

content_md5string

File MD5 (optional, for deduplication)

Response

Field	Description
data.file_id	File ID
data.upload_url	Pre-signed upload URL
data.upload_method	Upload method (PUT)
data.upload_headers	Required upload headers
data.expires_at	Upload URL expiration time
data.url	File download URL (returned immediately for duplicates)

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
}'

Requests go to the live API: a successful call creates a task on your account and spends credits.

POST

Confirm Upload

Confirm file upload completion and get download URL.

Request Body

file_idstringREQUIRED

File ID (from Get Upload URL response)

Response

Field	Description
data.file_id	File ID
data.url	File download URL
data.expires_at	URL expiration time (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"
}'

Requests go to the live API: a successful call creates a task on your account and spends credits.

POST

Refresh URL

Refresh file download URL (use when URL has expired).

Request Body

file_idstringREQUIRED

File ID

Response

Field	Description
data.file_id	File ID
data.url	New file download URL
data.expires_at	URL expiration time (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"
}'

Requests go to the live API: a successful call creates a task on your account and spends credits.

Error Types

Type	HTTP Status	Description
authentication_error	401	API Key missing, invalid, or disabled
validation_error	400	Invalid parameters, missing fields, or URL validation failure
rate_limit_error	429	Rate limit exceeded
permission_error	403	HTTPS required or insufficient permissions
insufficient_credits	402	Insufficient credits
not_found	404	Resource not found
internal_error	500	Internal server error

Task Statuses

Status	Description
pending	Pending — Task submitted, waiting to be processed
processing	Processing — Task is being executed
completed	Completed — Task finished successfully
failed	Failed — Task execution failed

Task Types

Task Type	Description
video_translation	Video Translation
multi_speaker_translation	Multi-Speaker Translation
lip_sync	Lip Sync
smart_erasure	Smart Eraser
subtitle_translation	Subtitle Translation
face_swap	Face Swap
text_to_speech	Text to Speech

Language Codes

The API accepts ISO 639-1 standard language codes. Source languages reflect speech-recognition (ASR) coverage; target languages reflect text-to-speech (TTS) coverage. The supported lists are below.

Source Languages (source_language)

Code	Language
zh	Chinese
en	English
ja	Japanese
ko	Korean
ru	Russian
de	German
fr	French
ar	Arabic
es	Spanish
it	Italian
vi	Vietnamese
pt	Portuguese
ms	Malay
tl	Filipino
id	Indonesian
nl	Dutch
th	Thai
no	Norwegian
ca	Catalan
bn	Bengali
sr	Serbian
yue	Cantonese
hi	Hindi
tr	Turkish
pl	Polish
uk	Ukrainian
fa	Persian
ur	Urdu
sv	Swedish
da	Danish
fi	Finnish
cs	Czech
hu	Hungarian
ro	Romanian
el	Greek
bg	Bulgarian
hr	Croatian
sk	Slovak
sl	Slovenian
et	Estonian
lv	Latvian
lt	Lithuanian
bs	Bosnian
mk	Macedonian
is	Icelandic
sw	Swahili
ta	Tamil
te	Telugu
ml	Malayalam
kn	Kannada
gu	Gujarati
mr	Marathi
pa	Punjabi
km	Khmer
lo	Lao
my	Burmese
mn	Mongolian
ne	Nepali
he	Hebrew
az	Azerbaijani
kk	Kazakh
uz	Uzbek
ky	Kyrgyz
af	Afrikaans
am	Amharic
as	Assamese
ast	Asturian
be	Belarusian
ceb	Cebuano
cy	Welsh
ff	Fula
ga	Irish
gl	Galician
ha	Hausa
hy	Armenian
ig	Igbo
jv	Javanese
ka	Georgian
kea	Kabuverdianu
ku	Kurdish
lb	Luxembourgish
lg	Ganda
ln	Lingala
luo	Luo
mi	Maori
mt	Maltese
nso	Northern Sotho
ny	Nyanja
oc	Occitan
or	Odia
ps	Pashto
sd	Sindhi
sn	Shona
so	Somali
tg	Tajik
umb	Umbundu
wo	Wolof
xh	Xhosa
zu	Zulu

Target Languages (target_language)

Code	Language
zh	Chinese
en	English
ja	Japanese
ko	Korean
ru	Russian
de	German
fr	French
ar	Arabic
es	Spanish
it	Italian
vi	Vietnamese
pt	Portuguese
id	Indonesian
ms	Malay
tl	Filipino
nl	Dutch
th	Thai
tr	Turkish
pl	Polish
uk	Ukrainian
sv	Swedish
cs	Czech
el	Greek
hi	Hindi
fi	Finnish
da	Danish
no	Norwegian
hu	Hungarian
ro	Romanian
sk	Slovak
hr	Croatian
bg	Bulgarian
sr	Serbian
ca	Catalan
fa	Persian
ta	Tamil
bn	Bengali
af	Afrikaans
hy	Armenian
as	Assamese
az	Azerbaijani
be	Belarusian
bs	Bosnian
ceb	Cebuano
ny	Nyanja
et	Estonian
gl	Galician
ka	Georgian
gu	Gujarati
ha	Hausa
he	Hebrew
is	Icelandic
ga	Irish
jv	Javanese
kn	Kannada
kk	Kazakh
ky	Kyrgyz
lv	Latvian
ln	Lingala
lt	Lithuanian
lb	Luxembourgish
mk	Macedonian
ml	Malayalam
mr	Marathi
ne	Nepali
ps	Pashto
pa	Punjabi
sd	Sindhi
sl	Slovenian
so	Somali
sw	Swahili
te	Telugu
ur	Urdu
cy	Welsh