Wizstar 視頻 Open API 幫助中心

本文檔面向接入 Wizstar 視頻能力的開發者，覆蓋文生視頻、圖生視頻、視頻翻譯、對口型、商品圖生視頻、視頻參考、批量生口播、數字人/音色檢索、任務查詢等接口。

文中所有 API Key、資產 ID、商品信息、返回鏈接等均為示例佔位數據，請替換為你自己的真實值。

通用部分說明

以下約定適用於本文檔全部接口，各接口章節不再重複展開，除非單接口明確說明。

通用請求約定

約定項	說明
鑑權方式	所有接口均需在請求頭攜帶 API Key，格式為 Authorization: Bearer <YOUR_API_KEY>
請求格式	任務提交類接口均為 application/json（POST）；任務查詢為 GET
文件傳參	所有文件類字段傳 asset_id 字符串（由資產上傳服務預先生成），不直接上傳二進制
回調通知	任務類接口可選填 callback_url，任務到終態後會回調一次

通用響應結構

視頻生成為異步任務。提交接口立即返回 task_id，再通過「任務查詢」接口或回調獲取最終結果。整體流程：提交接口 → 返回 task_id → 輪詢「任務查詢」或等待 callback → 拿到視頻結果。建議輪詢間隔 ≥3 秒，避免觸發限流；最長生成等待 24 小時，超時判失敗並退費。

任務提交成功響應（所有提交類接口結構一致）：

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

字段	說明
errno	0 表示成功，非 0 見錯誤碼章節
data[].task_id	任務 ID，oat_ 開頭，用於後續查詢
data[].points_consumed	本次調用消耗的星幣（用量），便於賬單核對
data[].queue_position	當前排隊位置
data[].estimated_wait_seconds	預計等待秒數

任務狀態枚舉：

狀態	說明
asset_checking	資產風控檢測中（未扣費）
pending	資產就緒，排隊等待併發/限流條件（未扣費）
queued	已扣費，等待生成
generating	生成中
completed	全部成功
failed	失敗（風控拒絕 / 餘額不足 / 生成失敗）

通用錯誤碼

Code	含義（英文原文）	排障建議
30400201	Invalid parameter	檢查參數枚舉值、長度、範圍、聯動必填
30400202	Asset is required	缺少必填的 asset_id
30400203	File size exceeds limit	資產文件超過大小上限
30400204	Unsupported file format	資產文件格式不支持
30400301	Insufficient points	星幣餘額不足，請充值後重試
30400302	Insufficient rights for this feature	當前會員等級無該功能權限
30400303	Rate limit exceeded	觸發限流，降低請求頻率後重試
30400304	Concurrent task limit exceeded	併發任務數超限，等待在途任務完成
30400401	Task not found	task_id 不存在或無權訪問
30400402	Task generation failed	任務生成失敗，可重新提交
30400601	Content rejected by risk control	內容被風控拒絕
30400602	Text content contains prohibited content	文本含違禁內容
30400603	File content contains prohibited content	文件含違禁內容
30400901	Internal server error	服務內部錯誤，稍後重試或聯繫支持
20610101	File request parameter error	文件請求參數錯誤
10100001	Authentication invalid or missing	認證無效或缺少
20610104	Storage quota exceeded	存儲配額不足
20610103	Unsupported file format	文件格式不支持
10110002	Internal server error	服務內部錯誤

通用計費與限制說明

項	說明
計費模式	按次/按時長扣星幣，具體單價以控制台計費頁為準；提交成功（queued）時扣費
失敗退費	生成失敗自動退還本次星幣
風控/餘額攔截	風控拒絕或餘額不足時不扣費
資產引用	文件需先經資產服務上傳換取 asset_id，本服務僅接收引用
回調重試	返回 2xx 視為成功

一、文件資產管理

視頻生成任務中涉及的圖片、視頻、音頻素材，需先上傳至文件資產服務獲取 file_id（即視頻接口中的 asset_id），再通過 asset_id 引用文件。

1、上傳文件

URL：POST https://wizstar.ai/wizstar/openapi/common/files/upload
鑑權：Authorization: Bearer <YOUR_API_KEY>（同視頻接口）
請求格式：multipart/form-data

字段	必填	類型	說明
file	是	file	待上傳文件。

支持的格式：

圖片：JPEG（.JPG/.JPEG）、PNG
視頻：MP4、MOV
音頻：WAV、MP3

僅代表資產庫可上傳範圍，實際要求以具體工具限制為準。

上傳成功響應：

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

配額限制：

項	限制
最大文件數	500 個
總容量	1 GB
單文件大小（圖片）	20 MB
單文件大小（視頻）	200 MB
單文件大小（音頻）	200 MB
文件有效期	15 天

上述配額隨時可能調整，但已上傳文件的有效期不受影響，仍以響應中的 expires_at 為準。

2、查詢文件元信息

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

返回結構與上傳成功響應的 data 字段相同。

3、列出用戶文件

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

參數	類型	必填	說明
limit	integer	否	返回條數限制。超過 200 時降級為默認值 20；有效範圍 1~200
cursor	string	否	分頁遊標，從上一頁響應的 cursor 字段取值
created_after	integer	否	創建時間下界（Unix 毫秒時間戳），0 表示不限制
created_before	integer	否	創建時間上界（Unix 毫秒時間戳），0 表示不限制

列表按創建時間倒序排列，僅返回當前用戶 status=1 狀態且未過期、未刪除的文件。

響應結構：

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

字段	說明
items	文件列表
limit	服務端實際應用的返回條數限制
cursor	下一頁遊標令牌，為空時表示已到最後一頁
has_more	是否還有更多數據，false 表示已到最後一頁

4、刪除文件

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

5、文件資產管理注意事項

file_id 為 32 字符無橫槓 hex 字符串，在後續視頻 API 中作為 asset_id 傳入
文件過期後不可訪問，需重新上傳；已過期文件的查詢/刪除返回 errno 10110002
以 errno 為判斷請求是否成功的唯一依據，HTTP 狀態碼固定為 200
URL 末尾不要帶斜槓：查詢（GET）、列表（GET）、刪除（DELETE）末尾無斜槓；上傳（POST /upload）末尾有斜槓

二、文生視頻

1、接口概述

根據文本提示詞（prompt）生成視頻。適用於無素材、純創意驅動的視頻生成場景。輸入文本與生成參數，輸出一段或多段視頻。

2、基礎請求與鑑權

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

3、請求參數

字段	必填	類型	說明
prompt	是	string	文本提示詞，≤800 字符
model	是	string	生成模型 seedance2.0 / seedance1.5 / kling
video_ratio	是	string	視頻比例 9:16 / 16:9
video_duration	是	int	視頻時長（秒） 5 / 10
video_resolution	是	string	分辨率，如 720P
video_num	是	int	生成數量，1~4
callback_url	否	string	任務完成回調地址

4、響應結構

返回任務提交標準響應（見「通用說明 · 通用響應結構」）

5、代碼調用示例

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": "兩隻小狗在草地上跳舞，電影質感",
    "model": "seedance2.0",
    "video_ratio": "9:16",
    "video_duration": 5,
    "video_resolution": "720P",
    "video_num": 1
  }'

三、圖生視頻

1、接口概述

以一張圖片為首幀/參考，結合提示詞生成動態視頻。適用於讓靜態圖"動起來"的場景。

2、基礎請求與鑑權

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

3、請求參數

字段	必填	類型	說明
image_asset_id	是	string	圖片資產 ID，JPG/PNG，≤10MB
prompt	是	string	文本提示詞，≤800 字
model	是	string	生成模型 seedance2.0 / seedance1.5 / kling
video_ratio	是	string	視頻比例 9:16 / 16:9
video_duration	是	int	視頻時長（秒） 5 / 10
video_resolution	是	string	分辨率 720P
video_num	是	int	生成數量，1~4
callback_url	否	string	回調地址

4、響應結構

返回任務提交標準響應（見「通用說明 · 通用響應結構」）。

5、代碼調用示例

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": "<圖片資產ID>",
    "prompt": "鏡頭緩緩拉遠，天空雲朵流動，電影質感",
    "model": "seedance2.0",
    "video_ratio": "9:16",
    "video_duration": 5,
    "video_resolution": "720P",
    "video_num": 1
  }'

四、視頻翻譯

1、接口概述

將一段視頻翻譯為目標語言，支持兩種模式：lip_sync_audio（口型同步 + 配音）與 audio_only（僅替換音軌）。適用於多語種出海內容本地化。

2、基礎請求與鑑權

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

3、請求參數

字段	必填	類型	說明
video_asset_id	是	string	視頻資產 ID，≤200MB，≤5min
source_lang	是	string	源語種，枚舉：auto / zh-CN / en-US
target_lang	是	string	目標語種，枚舉：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	是	string	翻譯模式：lip_sync_audio / audio_only
callback_url	否	string	回調地址

4、響應結構

返回任務提交標準響應（見「通用說明 · 通用響應結構」）。

5、代碼調用示例

cURL（口型同步模式）：

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": "<視頻資產ID>",
    "source_lang": "zh-CN",
    "target_lang": "en-US",
    "translation_mode": "lip_sync_audio"
  }'

cURL（僅配音模式）：

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": "<視頻資產ID>",
    "source_lang": "zh-CN",
    "target_lang": "en-US",
    "translation_mode": "audio_only"
  }'

五、數字人口播

1、接口概述

讓視頻或圖片中的人物"對口型"說話，音頻來源支持上傳音頻或文本合成（TTS）。共 4 種組合：視頻+上傳音頻、視頻+文本合成、圖片+上傳音頻、圖片+文本合成。

2、基礎請求與鑑權

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

3、請求參數

字段	必填	類型	說明
video_asset_id	二選一	string	視頻資產 ID，≤200MB，≤5min（與 image_asset_id 二選一）
image_asset_id	二選一	string	圖片資產 ID，JPG/PNG/WEBP，≤10MB
audio_asset_id	二選一	string	音頻資產 ID，MP3/WAV，≥16kHz，≤5min，≤50MB（與 script 二選一）
script	二選一	string	合成文本，≤1000 字
voice_id	條件必填	string	填 script 時必填，音色 ID
prompt	條件必填	string	圖片對口型時必填
video_ratio	條件必填	string	視頻比例 9:16 / 16:9 圖片對口型時必填
video_resolution	條件必填	string	分辨率 720P 圖片對口型時必填
callback_url	否	string	回調地址

4、響應結構

返回任務提交標準響應（見「通用說明 · 通用響應結構」）。

5、代碼調用示例

cURL（視頻 + 上傳音頻）：

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": "<視頻資產ID>",
    "audio_asset_id": "<音頻資產ID>"
  }'

cURL（視頻 + 文本合成音頻）：

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": "<視頻資產ID>",
    "script": "大家好，歡迎來到我們的直播間",
    "voice_id": "<音色ID>"
  }'

cURL（圖片 + 文本合成音頻）：

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": "<圖片資產ID>",
    "script": "大家好，歡迎來到我們的直播間",
    "voice_id": "<音色ID>",
    "prompt": "參考圖片生成一段產品介紹視頻",
    "video_ratio": "9:16",
    "video_resolution": "720P"
  }'

六、商品圖生視頻

1、接口概述

基於商品主圖、細節圖、場景圖與提示詞，生成商品營銷/帶貨短視頻。

2、基礎請求與鑑權

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

3、請求參數

字段	必填	類型	說明
product_image_asset_id	是	string	商品主圖資產 ID，JPG/PNG
detail_image_asset_ids	否	string[]	細節圖資產 ID 數組，最多 2 張
scene_image_asset_ids	否	string[]	場景圖資產 ID 數組，最多 2 張
prompt	是	string	文本提示詞，≤800 字
model	是	string	生成模型 kling
video_ratio	是	string	視頻比例 9:16 / 16:9
video_duration	是	int	視頻時長（秒），枚舉 5 / 10
video_resolution	是	string	分辨率 720P
video_num	是	int	生成數量，1~4
callback_url	否	string	回調地址

4、響應結構

返回任務提交標準響應（見「通用說明 · 通用響應結構」）。

5、代碼調用示例

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": "<商品主圖資產ID>",
    "detail_image_asset_ids": [],
    "scene_image_asset_ids": [],
    "prompt": "展示產品在戶外使用的場景，突出便攜性",
    "model": "kling",
    "video_ratio": "9:16",
    "video_duration": 5,
    "video_resolution": "720P",
    "video_num": 1
  }'

七、視頻爆款模仿

基於商品信息與參考視頻，生成最終成片。支持傳 product_url，或自定義商品 + 用戶自上傳參考視頻。

視頻參考-生成

1、接口概述

基於參考視頻生成最終成片。支持引用推薦結果、傳 product_url，或用戶自上傳參考視頻三種方式。

2、基礎請求與鑑權

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

3、請求參數

字段	必填	類型	說明
product_url	條件必填	string	商品鏈接（product_name product_description product_image_asset_ids 手動填寫時優先使用手動填寫內容）
product_name	條件必填	string	商品名（手填商品時）
product_description	條件必填	string	商品描述（手填商品時）
product_image_asset_ids	條件必填	string[]	商品圖資產 ID 數組（手填商品時）
reference_video_asset_id	是	string	參考視頻資產 ID
currency	否	string	貨幣美元：USD 英鎊：GBP 澳元：AUD 加元：CAD 新加坡元：SGD 人民幣：CNY 新台幣：TWD 港元：HKD 澳門元：MOP 歐元：EUR 墨西哥比索：MXN 巴西雷亞爾：BRL 印尼盾：IDR 泰銖：THB 越南盾：VND 日元：JPY 韓元：KRW
target_language	是	string	目標語言 en-US
prompt	條件必填	string	生成提示詞，≤800 字
model	是	string	生成模型 seedance2.0 / kling
video_ratio	是	string	視頻比例 9:16 / 16:9
video_resolution	是	string	分辨率 720P
original_price	否	string	商品原價
promo_price	否	string	商品促銷價/折扣價
promo_description	否	string	促銷活動描述
callback_url	否	string	回調地址

4、響應結構

返回任務提交標準響應（見「通用說明 · 通用響應結構」）。

5、代碼調用示例

cURL（自定義商品 + 用戶上傳參考視頻）：

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": "無線耳機",
    "product_description": "高音質無線耳機，支持主動降噪",
    "product_image_asset_ids": ["<商品圖資產ID>"],
    "currency": "USD",
    "reference_video_asset_id": "<參考視頻資產ID>",
    "target_language": "en-US",
    "model": "seedance2.0",
    "video_ratio": "9:16",
    "video_resolution": "720P"
  }'

八、圖片/視頻對口型

1、接口概述

指定數字人形象與音色，傳入多段文案，批量生成數字人口播視頻。適用於一次產出多條口播內容的場景。

2、基礎請求與鑑權

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

3、請求參數

字段	必填	類型	說明
figure_id	是	string	數字人形象 ID
figure_source	是	int	形象來源（如 2 表示某來源類型）
voice_id	是	string	音色 ID
script	是	string[]	文案數組，最多 10 段，每段 ≤1000 字
speed	否	float	語速，0.5~2.0
pitch	否	int	音調，1~3
screen_type	是	int	屏幕類型 1（豎屏）/ 2（橫屏）
language	否	string	語種，zh-CN / en-US / ja-JP / id-ID
video_resolution	否	string	分辨率 1080P
callback_url	否	string	回調地址

4、響應結構

返回任務提交標準響應（見「通用說明 · 通用響應結構」）。

5、代碼調用示例

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": "<數字人形象ID>",
    "figure_source": 2,
    "voice_id": "<音色ID>",
    "script": ["大家好，歡迎來到我們的產品展示。", "今天為大家介紹一款全新的智能設備。"],
    "screen_type": 1,
    "language": "zh-CN"
  }'

九、數字人形象列表

1、接口概述

查詢可用的數字人形象，支持公共形象庫（scope=public）與用戶私有形象庫（scope=private），可按性別、比例（9:16 / 16:9）篩選。

2、基礎請求與鑑權

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

3、請求參數

字段	必填	類型	說明
scope	是	string	public（公共）/ private（私有）
page_no	否	int	頁碼
page_size	否	int	每頁條數默認100
gender	否	int	性別：0未設置 1男性 2女性
screen	否	int	尺寸：1 豎版 2 橫版
race	否	int	人種：1白人 2亞裔 3南亞裔 4拉丁裔 5中東裔 6非裔
target_audience	否	int	年齡：1青年 2中年 3老年

4、響應結構

返回分頁形象列表（字段示意）：

JSON

{
  "errno": 0,
  "message": "success",
  "logid": "xxx",
  "timestamp": 1717401600,
  "data": {
    "count": 30,
    "list": [
      {
        "figure_id": 10086,
        "name": "商務男士",
        "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": "甜美女生",
        "gender": 0,
        "cover": "https://cdn.example.com/figure/cover_10087.jpg",
        "figure_source": 2,
        "screen": 2,
        "target_audience": 0,
        "race": 0,
        "status": 1
      }
    ]
  }
}

5、代碼調用示例

cURL（公共形象列表）：

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（私有形象列表 + 篩選）：

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

十、音色搜索

1、接口概述

搜索音色庫，支持公共音色（scope=public）與用戶私有音色（scope=private），用於對口型、批量生口播等接口的 voice_id 選取。

2、基礎請求與鑑權

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

3、請求參數

字段	必填	類型	說明
scope	是	string	public（公共）/ private（私有）
pn	否	int	頁碼
rn	否	int	每頁條數
name	否	string	名稱模糊搜索
gender	否	int	性別 0全部 1男 2女
language	否	int	語種 1 = 英語，2 = 漢語，3 = 法語，4 = 德語，5 = 西班牙語，6 = 泰語，7 = 印尼語，8 = 葡萄牙語，9 = 日語，10 = 韓語，11 = 越南語，12 = 阿拉伯語
scene	否	int	場景 1 = 日常生活，2 = 電商賣貨，3 = 廣告營銷，4 = 客服助理，5 = 新聞主持，6 = 科普知識
age	否	int	年齡 1青年 2中年 3老年

4、響應結構

返回分頁音色列表（字段示意）：

JSON

{
  "errno": 0,
  "message": "success",
  "logid": "xxx",
  "timestamp": 1717401600,
  "data": {
    "count": 50,
    "list": [
      {
        "media_id": 1001,
        "name": "甜美女聲",
        "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
      }
    ]
  }
}

字段	說明
media_id	音色 ID，用作其他接口的 voice_id
name	音色名稱
preview	試聽音頻鏈接
is_public	1 公共 / 0 私有

5、代碼調用示例

cURL（公共音色）：

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": "甜美",
    "gender": 0
  }'

cURL（私有音色）：

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

十一、任務查詢

1、接口概述

根據提交接口返回的 task_id 查詢任務狀態與生成結果。所有異步生成類接口均通過本接口拉取最終視頻。

2、基礎請求與鑑權

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

3、請求參數（query）

字段	必填	類型	默認值	說明
task_id	是	string	-	任務 ID，oat_ 開頭

4、響應結構

JSON

{
  "errno": 0,
  "message": "success",
  "logid": "<日誌ID>",
  "timestamp": 1781183414,
  "lang": "zh-CN",
  "data": {
    "task_id": "oat_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "status": "completed",
    "results": [
      {
        "video_url": "<無水印視頻鏈接>",
        "watermark_video_url": "<帶水印視頻鏈接>",
        "cover_url": "<封面圖鏈接>",
        "watermark_cover_url": "<帶水印封面圖鏈接>",
        "duration": 5.04,
        "width": 720,
        "height": 1280
      }
    ],
    "error_code": "",
    "error_message": ""
  }
}

字段	說明
status	任務狀態，見「通用說明 · 異步任務模型」狀態枚舉
results	生成結果數組，每項為一條視頻
results[].video_url	無水印視頻鏈接
results[].duration	視頻時長（秒）
error_code / error_message	失敗時的錯誤信息

5、代碼調用示例

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

十二、回調通知（callback）

提交任務時若填寫 callback_url，任務到達終態（全部成功或含失敗）後，平臺會向該地址 POST 一次回調。

1、觸發與重試

觸發時機：該任務下所有子視頻均到終態後觸發一次（不按單條視頻回調）
全部成功 → status=completed；含任意失敗 → status=failed

2、回調 Payload 示例

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、接收端注意事項

回調接收端需在 10 秒內返回 2xx，否則視為失敗並觸發重試
建議對 task_id 做冪等處理，避免重試導致重複處理
回調為兜底通知，仍建議保留主動查詢能力