API Reference / Introduction

Introduction

Explore the Qavix 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://qavixi.com/qavix

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",
    "estimated_credits": 60
  },
  "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
data.output.expires_at	URL expiration time (ISO 8601)
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 code

target_languagestringREQUIRED

Target language code

voice_idstring

Dubbing voice ID

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
data.estimated_credits	Estimated credits consumption

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 (normalized 0-1 coordinates), each with x, y, width, height, type (1=watermark, 2=subtitle)

erasure_modestring

Erasure mode: auto / manual / protect

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
data.estimated_credits	Estimated credits consumption

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 code

target_languagestringREQUIRED

Target language code

namestring

Task name

embed_subtitleboolean

Whether to embed subtitles into video (default: true)

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
data.estimated_credits	Estimated credits consumption

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
data.estimated_credits	Estimated credits consumption

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
data.estimated_credits	Estimated credits consumption

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 code

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
data.estimated_credits	Estimated credits consumption

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