Wizstar Video API

This document is intended for developers integrating Wizstar's video capabilities, covering APIs for Text-to-Video, Image-to-Video, Video Translation, Lip Sync, Product Image-to-Video, Video Reference, Digital Human Video, Avatar/Voice Retrieval, Task Query, and more.

All API Keys, asset IDs, product information, return links, and similar data in this document are sample placeholder values. Please replace them with your own actual values.

General Instructions

The following conventions apply to all APIs in this document and will not be repeated in individual API sections, unless explicitly stated otherwise.

General Request Conventions

Item	Description
Authentication	All APIs require an API Key in the request header, formatted as Authorization: Bearer <YOUR_API_KEY>
Request Format	Task submission APIs use application/json (POST); task query APIs use GET
File Parameters	All file-type fields accept an asset_id string (pre-generated by the asset upload service), not a direct binary upload
Callback Notification	Task-type APIs support an optional callback_url parameter; a callback will be triggered once the task reaches its final state

General Response Structure

Video generation is asynchronous. The submission API immediately returns a task_id, and you can obtain the final result via the Task Query API or by waiting for the callback. The overall flow: Submission API → Returns task_id → Poll the Task Query API or wait for callback → Retrieve the video result. It is recommended to set a polling interval of ≥3 seconds to avoid rate limiting. The maximum generation wait time is 24 hours; tasks that exceed this limit will be considered failed and refunded.

Successful task submission response (consistent across all submission-type APIs):

JSON

{
  "errno": 0,
  "message": "success",
  "logid": "xxx",
  "timestamp": 1717401600,
  "data": {
    "tasks": [
      {
        "task_id": "oat_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
        "status": "success",
        "points_consumed": 10,
        "queue_position": 3,
        "estimated_wait_seconds": 120
      }
    ]
  }
}

Field	Description
errno	0 indicates success; non-zero values refer to the Error Codes section
data[].task_id	Task ID, prefixed with oat_, used for subsequent queries
data[].points_consumed	Credits (usage) consumed by this call, for billing reconciliation
data[].queue_position	Current position in the queue
data[].estimated_wait_seconds	Estimated wait time in seconds

Task Status Enumeration:

Status	Description
asset_checking	Asset risk control check in progress (not charged)
pending	Asset ready, queued for concurrency/rate-limit conditions (not charged)
queued	Charged, waiting for generation
generating	Generating
completed	All succeeded
failed	Failed (risk control rejection / insufficient balance / generation failure)

Common Error Codes

Code	Meaning	Troubleshooting
30400201	Invalid parameter	Check parameter enum values, length, range, and conditional requirements
30400202	Asset is required	Missing required asset_id
30400203	File size exceeds limit	Asset file exceeds the maximum size limit
30400204	Unsupported file format	Asset file format is not supported
30400301	Insufficient points	Insufficient credits balance, please top up and retry
30400302	Insufficient rights for this feature	Current membership tier does not have access to this feature
30400303	Rate limit exceeded	Rate limit triggered, reduce request frequency and retry
30400304	Concurrent task limit exceeded	Concurrent task limit reached, wait for in-progress tasks to complete
30400401	Task not found	task_id does not exist or no access permission
30400402	Task generation failed	Task generation failed; resubmit
30400601	Content rejected by risk control	Content rejected by risk control
30400602	Text content contains prohibited content	Text contains prohibited content
30400603	File content contains prohibited content	File contains prohibited content
30400901	Internal server error	Internal server error, retry later or contact support
20610101	File request parameter error	File request parameter error
10100001	Authentication invalid or missing	Invalid or missing authentication
20610104	Storage quota exceeded	Insufficient storage quota
20610103	Unsupported file format	File format not supported
10110002	Internal server error	Internal server error

General Billing & Limitations

Item	Description
Billing Model	Charged per task or per duration in credits; refer to the Console billing page for specific rates. Charges are applied upon successful submission (queued)
Failure Refund	Credits are automatically refunded if generation fails
Risk Control / Balance Block	No charge if rejected by risk control or if balance is insufficient
Asset Reference	Files must first be uploaded to the file asset service to obtain an asset_id; this service only accepts references
Callback Retry	A 2xx response is considered successful

I. File Asset Management

Image, video, and audio used in video generation must first be uploaded to the file asset service to obtain a file_id (which serves as the asset_id in video APIs), after which files are referenced via asset_id.

1. Upload File

URL: POST https://wizstar.ai/wizstar/openapi/common/files/upload
Authentication: Authorization: Bearer <YOUR_API_KEY> (same as video APIs)
Request Format: multipart/form-data

Field	Required	Type	Description
file	Yes	file	File to upload.

Supported formats:

Image: JPEG (.JPG/.JPEG), PNG
Video: MP4, MOV
Audio: WAV, MP3

The above only represents the upload scope of the asset library; actual requirements depend on the specific tool's limitations.

Successful upload response:

JSON

{
  "errno": 0,
  "message": "success",
  "timestamp": 1782198346,
  "data": {
    "file_id": "2722637227394bc1b547bc4314777a25",
    "filename": "sample.jpeg",
    "content_type": "image/jpeg",
    "size_bytes": 205632,
    "status": 1,
    "expires_at": "2026-07-08T07:05:46Z"
  },
  "logid": "396982511",
  "lang": "en-US"
}

Quota Limits:

Item	Limit
Max files	500
Total capacity	1 GB
Single file size (image)	20 MB
Single file size (video)	200 MB
Single file size (audio)	200 MB
File validity	15 days

The above quotas are subject to change at any time, but the validity period of already uploaded files will not be affected and shall be determined by the expires_at field in the response.

2. Query File Metadata

URL: GET https://wizstar.ai/wizstar/openapi/common/files?file_id={file_id}
Authentication: Authorization: Bearer <YOUR_API_KEY>

The response structure is the same as the data field in the upload success response.

3. List User Files

URL: GET https://wizstar.ai/wizstar/openapi/common/files
Authentication: Authorization: Bearer <YOUR_API_KEY>

Parameter	Type	Required	Description
limit	integer	No	Maximum number of items to return. Values exceeding 200 will be downgraded to the default of 20. Valid range: 1–200
cursor	string	No	Pagination cursor, taken from the cursor field of the previous page's response
created_after	integer	No	Lower bound for creation time (Unix millisecond timestamp); 0 indicates no limit
created_before	integer	No	Upper bound for creation time (Unix millisecond timestamp); 0 indicates no limit

The list is sorted by creation time in descending order. Only returns files belonging to the current user with status=1 that have not expired and have not been deleted.

Response structure:

JSON

{
  "errno": 0,
  "message": "success",
  "timestamp": 1782198015,
  "data": {
    "items": [
      {
        "file_id": "645230c9acfc43c59c1f1cec2f8156a2",
        "filename": "sample.jpeg",
        "content_type": "image/jpeg",
        "size_bytes": 205632,
        "status": 1,
        "expires_at": "2026-07-08T06:49:41Z"
      }
    ],
    "limit": 5,
    "cursor": "1782198346251_27226372...",
    "has_more": true
  },
  "logid": "396982756",
  "lang": "en-US"
}

Field	Description
items	File list
limit	The actual return limit applied by the server
cursor	Cursor token for the next page; empty indicates the last page
has_more	Whether more data is available; false indicates the last page

4. Delete File

URL: DELETE https://wizstar.ai/wizstar/openapi/common/files?file_id={file_id}
Authentication: Authorization: Bearer <YOUR_API_KEY>

5. File Asset Management Notes

file_id is a 32-character hex string without hyphens. It is passed as asset_id in subsequent video APIs.
Expired files are inaccessible and must be re-uploaded. Querying or deleting expired files will return errno 10110002.
Use errno as the sole criterion for determining request success. The HTTP status code is always 200.
Do not include a trailing slash in the URL: Query (GET), List (GET), and Delete (DELETE) have no trailing slash; Upload (POST /upload) has a trailing slash.

II. Text-to-Video

1. Overview

Generates a video from a text prompt. Suitable for scenarios without existing assets where the output is purely creativity-driven. Input the text and generation parameters to produce one or more videos.

2. Basic Request & Authentication

URL: POST https://wizstar.com/wizstar/openapi/video/text-to-video
Authentication: Authorization: Bearer <YOUR_API_KEY>

3. Request Parameters

Field	Required	Type	Description
prompt	Yes	string	Text prompt, ≤800 characters
model	Yes	string	Generation model: seedance2.0 / seedance1.5 / kling
video_ratio	Yes	string	Video aspect ratio: 9:16 / 16:9
video_duration	Yes	int	Video duration (seconds): 5 / 10
video_resolution	Yes	string	Resolution, e.g. 720P
video_num	Yes	int	Number of videos to generate: 1–4
callback_url	No	string	Callback URL for task completion

4. Response Structure

Returns the standard task submission response (see General Instructions → General Response Structure)

5. Code Example

cURL:

bash

curl -X POST 'https://wizstar.com/wizstar/openapi/video/text-to-video' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <YOUR_API_KEY>' \
  -d '{
    "prompt": "Two puppies dancing on the grass, cinematic quality",
    "model": "seedance2.0",
    "video_ratio": "9:16",
    "video_duration": 5,
    "video_resolution": "720P",
    "video_num": 1
  }'

III. Image-to-Video

1. Overview

Uses an image as the first frame / reference, combined with a text prompt to generate a dynamic video. Suitable for bringing static images to life.

2. Basic Request & Authentication

URL: POST https://wizstar.com/wizstar/openapi/video/image-to-video
Authentication: Authorization: Bearer <YOUR_API_KEY>

3. Request Parameters

Field	Required	Type	Description
image_asset_id	Yes	string	Image asset ID, JPG/PNG, ≤10MB
prompt	Yes	string	Text prompt, ≤800 characters
model	Yes	string	Generation model: seedance2.0 / seedance1.5 / kling
video_ratio	Yes	string	Video aspect ratio: 9:16 / 16:9
video_duration	Yes	int	Video duration (seconds): 5 / 10
video_resolution	Yes	string	Resolution: 720P
video_num	Yes	int	Number of videos to generate: 1–4
callback_url	No	string	Callback URL

4. Response Structure

Returns the standard task submission response (see General Instructions → General Response Structure).

5. Code Example

cURL:

bash

curl -X POST 'https://wizstar.com/wizstar/openapi/video/image-to-video' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <YOUR_API_KEY>' \
  -d '{
    "image_asset_id": "<image_asset_id>",
    "prompt": "Camera slowly pulls back, clouds flowing in the sky, cinematic quality",
    "model": "seedance2.0",
    "video_ratio": "9:16",
    "video_duration": 5,
    "video_resolution": "720P",
    "video_num": 1
  }'

IV. Video Translation

1. Overview

Translates a video into a target language. Supports two modes: lip_sync_audio (lip sync + dubbing) and audio_only (replace audio track only). Suitable for multilingual content localization for overseas markets.

2. Basic Request & Authentication

URL: POST https://wizstar.com/wizstar/openapi/video/video-translate
Authentication: Authorization: Bearer <YOUR_API_KEY>

3. Request Parameters

Field	Required	Type	Description
video_asset_id	Yes	string	Video asset ID, ≤200MB, ≤5min
source_lang	Yes	string	Source language. Enum: auto / zh-CN / en-US
target_lang	Yes	string	Target language. Enum: en-US / es-ES / zh-CN / pt-PT / id-ID / de-DE / fr-FR / th-TH / vi-VN / ja-JP / ko-KR / ar-SA
translation_mode	Yes	string	Translation mode: lip_sync_audio / audio_only
callback_url	No	string	Callback URL

4. Response Structure

Returns the standard task submission response (see General Instructions → General Response Structure).

5. Code Examples

cURL (Lip Sync mode):

bash

curl -X POST 'https://wizstar.com/wizstar/openapi/video/video-translate' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <YOUR_API_KEY>' \
  -d '{
    "video_asset_id": "<video_asset_id>",
    "source_lang": "zh-CN",
    "target_lang": "en-US",
    "translation_mode": "lip_sync_audio"
  }'

cURL (Audio-only mode):

bash

curl -X POST 'https://wizstar.com/wizstar/openapi/video/video-translate' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <YOUR_API_KEY>' \
  -d '{
    "video_asset_id": "<video_asset_id>",
    "source_lang": "zh-CN",
    "target_lang": "en-US",
    "translation_mode": "audio_only"
  }'

V. Lip Sync

1. Overview

Makes a person in a video or image 'lip-sync' to speech. Audio sources support uploaded audio or text-to-speech (TTS). Supports 4 combinations: video + uploaded audio, video + TTS, image + uploaded audio, image + TTS.

2. Basic Request & Authentication

URL: POST https://wizstar.com/wizstar/openapi/video/lip-sync
Authentication: Authorization: Bearer <YOUR_API_KEY>

3. Request Parameters

Field	Required	Type	Description
video_asset_id	One of two	string	Video asset ID, ≤200MB, ≤5min (mutually exclusive with image_asset_id)
image_asset_id	One of two	string	Image asset ID, JPG/PNG/WEBP, ≤10MB
audio_asset_id	One of two	string	Audio asset ID, MP3/WAV, ≥16kHz, ≤5min, ≤50MB (mutually exclusive with script)
script	One of two	string	Text for TTS, ≤1000 characters
voice_id	Conditional	string	Required when using script; voice ID
prompt	Conditional	string	Required for image lip-sync
video_ratio	Conditional	string	Video aspect ratio: 9:16 / 16:9. Required for image lip-sync
video_resolution	Conditional	string	Resolution: 720P. Required for image lip-sync
callback_url	No	string	Callback URL

4. Response Structure

Returns the standard task submission response (see General Instructions → General Response Structure).

5. Code Examples

cURL (Video + uploaded audio):

bash

curl -X POST 'https://wizstar.com/wizstar/openapi/video/lip-sync' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <YOUR_API_KEY>' \
  -d '{
    "video_asset_id": "<video_asset_id>",
    "audio_asset_id": "<audio_asset_id>"
  }'

cURL (Video + TTS audio):

bash

curl -X POST 'https://wizstar.com/wizstar/openapi/video/lip-sync' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <YOUR_API_KEY>' \
  -d '{
    "video_asset_id": "<video_asset_id>",
    "script": "Hello everyone, welcome to our livestream.",
    "voice_id": "<voice_id>"
  }'

cURL (Image + TTS audio):

bash

curl -X POST 'https://wizstar.com/wizstar/openapi/video/lip-sync' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <YOUR_API_KEY>' \
  -d '{
    "image_asset_id": "<image_asset_id>",
    "script": "Hello everyone, welcome to our livestream.",
    "voice_id": "<voice_id>",
    "prompt": "Generate a product introduction video based on the reference image",
    "video_ratio": "9:16",
    "video_resolution": "720P"
  }'

VI. Product Image-to-Video

1. Overview

Generates product marketing / shoppable short videos based on the product main image, detail images, scene images, and a text prompt.

2. Basic Request & Authentication

URL: POST https://wizstar.com/wizstar/openapi/video/product-to-video
Authentication: Authorization: Bearer <YOUR_API_KEY>

3. Request Parameters

Field	Required	Type	Description
product_image_asset_id	Yes	string	Product main image asset ID, JPG/PNG
detail_image_asset_ids	No	string[]	Detail image asset ID array, max 2 images
scene_image_asset_ids	No	string[]	Scene image asset ID array, max 2 images
prompt	Yes	string	Text prompt, ≤800 characters
model	Yes	string	Generation model: kling
video_ratio	Yes	string	Video aspect ratio: 9:16 / 16:9
video_duration	Yes	int	Video duration (seconds), enum: 5 / 10
video_resolution	Yes	string	Resolution: 720P
video_num	Yes	int	Number of videos to generate: 1–4
callback_url	No	string	Callback URL

4. Response Structure

Returns the standard task submission response (see General Instructions → General Response Structure).

5. Code Example

cURL:

bash

curl -X POST 'https://wizstar.com/wizstar/openapi/video/product-to-video' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <YOUR_API_KEY>' \
  -d '{
    "product_image_asset_id": "<product_image_asset_id>",
    "detail_image_asset_ids": [],
    "scene_image_asset_ids": [],
    "prompt": "Show the product being used outdoors, highlighting portability",
    "model": "kling",
    "video_ratio": "9:16",
    "video_duration": 5,
    "video_resolution": "720P",
    "video_num": 1
  }'

VII. Video Reference

Generates a final video based on product information and a reference video. Supports providing a product_url, or custom product info + user-uploaded reference video.

Video Reference - Generate

1. Overview

Generates a final video based on a reference video. Supports three methods: referencing recommended results, passing a product_url, or user-uploaded reference video.

2. Basic Request & Authentication

URL: POST https://wizstar.com/wizstar/openapi/video/reference/create
Authentication: Authorization: Bearer <YOUR_API_KEY>

3. Request Parameters

Field	Required	Type	Description
product_url	Conditional	string	Product URL (When product_name, product_description, product_image_asset_ids are manually filled, the manually entered values take precedence)
product_name	Conditional	string	Product name (for manually entered products)
product_description	Conditional	string	Product description (for manually entered products)
product_image_asset_ids	Conditional	string[]	Product image asset ID array (for manually entered products)
reference_video_asset_id	Yes	string	Reference video asset ID
currency	No	string	Currency: USD / GBP / AUD / CAD / SGD / CNY / TWD / HKD / MOP / EUR / MXN / BRL / IDR / THB / VND / JPY / KRW
target_language	Yes	string	Target language: en-US
prompt	Conditional	string	Generation prompt, ≤800 characters
model	Yes	string	Generation model: seedance2.0 / kling
video_ratio	Yes	string	Video aspect ratio: 9:16 / 16:9
video_resolution	Yes	string	Resolution: 720P
original_price	No	string	Original product price
promo_price	No	string	Promotional/discounted price
promo_description	No	string	Promotion description
callback_url	No	string	Callback URL

4. Response Structure

Returns the standard task submission response (see General Instructions → General Response Structure).

5. Code Example

cURL (Custom product + user-uploaded reference video):

bash

curl -X POST 'https://wizstar.com/wizstar/openapi/video/reference/create' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <YOUR_API_KEY>' \
  -d '{
    "product_name": "Wireless Earbuds",
    "product_description": "High-quality wireless earbuds with active noise cancellation",
    "product_image_asset_ids": ["<product_image_asset_id>"],
    "currency": "USD",
    "reference_video_asset_id": "<reference_video_asset_id>",
    "target_language": "en-US",
    "model": "seedance2.0",
    "video_ratio": "9:16",
    "video_resolution": "720P"
  }'

VIII. Image & Video Lip Sync

1. Overview

Specify a digital human figure and voice, provide multiple scripts, and batch-generate digital human talking videos. Suitable for producing multiple talking videos in a single run.

2. Basic Request & Authentication

URL: POST https://wizstar.com/wizstar/openapi/video/batch-broadcast
Authentication: Authorization: Bearer <YOUR_API_KEY>

3. Request Parameters

Field	Required	Type	Description
figure_id	Yes	string	Digital human ID
figure_source	Yes	int	Figure source (e.g., 2 represents a specific source type)
voice_id	Yes	string	Voice ID
script	Yes	string[]	Script array, max 10 items, each ≤1000 characters
speed	No	float	Speaking speed: 0.5–2.0
pitch	No	int	Pitch: 1–3
screen_type	Yes	int	Screen type: 1 (portrait) / 2 (landscape)
language	No	string	Language: zh-CN / en-US / ja-JP / id-ID
video_resolution	No	string	Resolution: 1080P
callback_url	No	string	Callback URL

4. Response Structure

Returns the standard task submission response (see General Instructions → General Response Structure).

5. Code Example

cURL:

bash

curl -X POST 'https://wizstar.com/wizstar/openapi/video/batch-broadcast' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <YOUR_API_KEY>' \
  -d '{
    "figure_id": "<figure_id>",
    "figure_source": 2,
    "voice_id": "<voice_id>",
    "script": ["Hello everyone, welcome to our product showcase.", "Today we are introducing a brand new smart device."],
    "screen_type": 1,
    "language": "zh-CN"
  }'

IX. Avatar List

1. Overview

Queries available avatars. Supports public avatar gallery (scope=public) and user's private avatar gallery (scope=private). Can be filtered by gender and aspect ratio (9:16 / 16:9).

2. Basic Request & Authentication

URL: POST https://wizstar.com/wizstar/openapi/video/figure/list
Authentication: Authorization: Bearer <YOUR_API_KEY>

3. Request Parameters

Field	Required	Type	Description
scope	Yes	string	public (public) / private (private)
page_no	No	int	Page number
page_size	No	int	Items per page, default 100
gender	No	int	Gender: 0 (unset), 1 (male), 2 (female)
screen	No	int	Screen: 1 (portrait), 2 (landscape)
race	No	int	Race: 1 (Caucasian), 2 (East Asian), 3 (South Asian), 4 (Latino), 5 (Middle Eastern), 6 (African)
target_audience	No	int	Age: 1 (young), 2 (middle-aged), 3 (elderly)

4. Response Structure

Returns a paginated avatar list:

JSON

{
  "errno": 0,
  "message": "success",
  "logid": "xxx",
  "timestamp": 1717401600,
  "data": {
    "count": 30,
    "list": [
      {
        "figure_id": 10086,
        "name": "Business Man",
        "gender": 1,
        "cover": "https://cdn.example.com/figure/cover_10086.jpg",
        "figure_source": 2,
        "screen": 1,
        "target_audience": 1,
        "race": 1,
        "status": 1
      },
      {
        "figure_id": 10087,
        "name": "Sweet Girl",
        "gender": 0,
        "cover": "https://cdn.example.com/figure/cover_10087.jpg",
        "figure_source": 2,
        "screen": 2,
        "target_audience": 0,
        "race": 0,
        "status": 1
      }
    ]
  }
}

5. Code Examples

cURL (Public avatar gallery):

bash

curl -X POST 'https://wizstar.com/wizstar/openapi/video/figure/list' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <YOUR_API_KEY>' \
  -d '{"scope":"public","page_no":1,"page_size":16}'

cURL (Private avatar gallery with filters):

bash

curl -X POST 'https://wizstar.com/wizstar/openapi/video/figure/list' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <YOUR_API_KEY>' \
  -d '{"scope":"public","page_no":1,"page_size":16,"gender":2,"screen":1}'

X. Voice Search

1. Overview

Searches the voice gallery. Supports public voices (scope=public) and user's private voices (scope=private). Used for selecting voice_id in lip-sync, digital human videos, and other APIs.

2. Basic Request & Authentication

URL: POST https://wizstar.com/wizstar/openapi/video/tts/search
Authentication: Authorization: Bearer <YOUR_API_KEY>

3. Request Parameters

Field	Required	Type	Description
scope	Yes	string	public (public) / private (private)
pn	No	int	Page number
rn	No	int	Items per page
name	No	string	Fuzzy search by name
gender	No	int	Gender: 0 (all), 1 (male), 2 (female)
language	No	int	Language: 1 (English), 2 (Chinese), 3 (French), 4 (German), 5 (Spanish), 6 (Thai), 7 (Indonesian), 8 (Portuguese), 9 (Japanese), 10 (Korean), 11 (Vietnamese), 12 (Arabic)
scene	No	int	Scene: 1 (Daily Life), 2 (E-commerce), 3 (Advertising/Marketing), 4 (Customer Service), 5 (News Anchoring), 6 (Popular Science)
age	No	int	Age: 1 (young), 2 (middle-aged), 3 (elderly)

4. Response Structure

Returns a paginated voice list:

JSON

{
  "errno": 0,
  "message": "success",
  "logid": "xxx",
  "timestamp": 1717401600,
  "data": {
    "count": 50,
    "list": [
      {
        "media_id": 1001,
        "name": "Sweet Female Voice",
        "gender": 0,
        "language": 1,
        "scene": 1,
        "age": 1,
        "denoise": 0,
        "status": 1,
        "recommend": 1,
        "status_msg": "",
        "preview": "https://cdn.example.com/tts/preview_1001.mp3",
        "duration": 5000,
        "upload_url": "",
        "is_public": 1
      }
    ]
  }
}

Field	Description
media_id	Voice ID, used as voice_id in other APIs
name	Voice name
preview	Preview audio link
is_public	1 (public) / 0 (private)

5. Code Examples

cURL (Public voices):

bash

curl -X POST 'https://wizstar.com/wizstar/openapi/video/tts/search' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <YOUR_API_KEY>' \
  -d '{
    "scope": "public",
    "pn": 1,
    "rn": 20,
    "name": "Sweet",
    "gender": 0
  }'

cURL (Private voices):

bash

curl -X POST 'https://wizstar.com/wizstar/openapi/video/tts/search' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <YOUR_API_KEY>' \
  -d '{
    "scope": "private",
    "pn": 1,
    "rn": 20
  }'

XI. Task Query

1. Overview

Queries the task status and generation results using the task_id returned by the submission API. All asynchronous generation APIs use this endpoint to retrieve the final video.

2. Basic Request & Authentication

URL: GET https://wizstar.com/wizstar/openapi/video/task
Authentication: Authorization: Bearer <YOUR_API_KEY>

3. Request Parameters (Query)

Field	Required	Type	Default	Description
task_id	Yes	string	—	Task ID, prefixed with oat_

4. Response Structure

JSON

{
  "errno": 0,
  "message": "success",
  "logid": "<log_id>",
  "timestamp": 1781183414,
  "lang": "zh-CN",
  "data": {
    "task_id": "oat_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "status": "completed",
    "results": [
      {
        "video_url": "<video_url_without_watermark>",
        "watermark_video_url": "<video_url_with_watermark>",
        "cover_url": "<cover_image_url>",
        "watermark_cover_url": "<cover_image_url_with_watermark>",
        "duration": 5.04,
        "width": 720,
        "height": 1280
      }
    ],
    "error_code": "",
    "error_message": ""
  }
}

Field	Description
status	Task status; see General Instructions → Task Status Enumeration
results	Array of generated results, one video for each item
results[].video_url	Video URL without watermark
results[].duration	Video duration (seconds)
error_code / error_message	Error information on failure

5. Code Example

cURL:

bash

curl -X GET 'https://wizstar.com/wizstar/openapi/video/task?task_id=oat_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx' \
  -H 'Authorization: Bearer <YOUR_API_KEY>'

XII. Callback Notification

If a callback_url is provided when submitting a task, the platform will POST a callback to that URL once the task reaches a final state (all succeeded or any failed).

1. Trigger & Retry

Trigger condition: Fires once when all sub-videos under the task reach a final state (not triggered per individual video).
All succeeded → status=completed; any failed → status=failed

2. Callback Payload Example

JSON

{
  "task_id": "oat_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "completed",
  "results": [
    {
      "video_url": "https://xxx.com/path/to/video.mp4",
      "watermark_video_url": "https://xxx.com/path/to/video_wm.mp4",
      "cover_url": "https://xxx.com/path/to/cover.jpg",
      "watermark_cover_url": "https://xxx.com/path/to/cover_wm.jpg",
      "duration": 15.5,
      "width": 1920,
      "height": 1080
    }
  ],
  "error_code": "",
  "error_message": ""
}

3. Recipient Notes

The callback receiver must return a 2xx status within 10 seconds; otherwise, it will be considered a failure and trigger a retry.
It is recommended to implement idempotency based on task_id to avoid duplicate processing from retries.
The callback is a fallback notification; it is still recommended to retain the ability to proactively query capability.