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 做幂等处理，避免重试导致重复处理
回调为兜底通知，仍建议保留主动查询能力