API Reference / Introduction

Introduction

Explore the Oiiyao API reference with comprehensive guides, code examples, and endpoint documentation. Integrate powerful AI video translation, voice synthesis, and smart editing into your applications.

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)

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:

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:

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:

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.vocals_url	Vocals file URL (returned for audio_separation tasks only)
data.output.background_url	Background music file URL (returned for audio_separation tasks only)
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:

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:

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

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:

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:

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:

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:

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:

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:

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:

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

Emotional tone. Allowed values: auto / neutral / happy / sad / angry / surprised. Default: auto (inferred from text). Note: some cloned voices do not support emotion override and will silently fall back to auto.

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:

POST

Audio Separation

Separate an audio file into vocals and background music as two independent files.

Request Body

audio_urlstringREQUIRED

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

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:

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:

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:

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:

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:

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
voice_clone	Voice Clone
text_to_speech	Text to Speech
audio_separation	Audio Separation

Language Codes

The API accepts ISO 639-1 standard language codes. Below are the supported source and target languages.

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

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
pt-BR	Brazilian Portuguese
ms	Malay
tl	Filipino
id	Indonesian
nl	Dutch
th	Thai
no	Norwegian
ca	Catalan
bn	Bengali
sr	Serbian
cs	Czech
bg	Bulgarian
pl	Polish
ro	Romanian
sv	Swedish
ta	Tamil
tr	Turkish
uk	Ukrainian
el	Greek
hi	Hindi
fi	Finnish
hr	Croatian
sk	Slovak
da	Danish
hu	Hungarian
fa	Persian