视频生成 | MaiToken

通过 MaiToken 调用已开通的腾讯云视频模型。创建和查询均请求 https://api.maitoken.com/，通过请求头 X-TC-Action 区分操作，响应保留腾讯云的 Response 结构。

Authorizations

Header Authorization（string，必填）：使用 MaiToken API Key，格式为 Bearer YOUR_API_KEY。可在 API Key 管理页面获取。
Header Content-Type：application/json。
Header X-TC-Version：固定为 2018-07-17，这是接口版本，不是模型版本。
Header X-TC-Action：创建任务填 CreateAigcVideoTask，查询任务填 DescribeTaskDetail。

平台负责腾讯云签名及应用配置。调用方无需提供腾讯云 SecretId、SecretKey，也不要提交 SubAppId，否则请求会被拒绝。

提交生成任务

POST /X-TC-Action: CreateAigcVideoTask

使用根路径，不添加 /v1、/v1/videos 或 URL 查询参数。

模型名称与版本

先查询当前 API Key 可用的模型：

curl --request GET \  --url https://api.maitoken.com/v1/models \  --header 'Authorization: Bearer YOUR_API_KEY'

在返回的 data 中选择支持 tencent_vod 协议的模型，使用其 id 作为 ModelName，从 model_versions 中选择版本作为 ModelVersion。

例如，平台配置的对外名称为 tencent-Kling，且已授权 3.0-Omni，则填写：

{  "ModelName": "tencent-Kling",  "ModelVersion": "3.0-Omni"}

tencent-Kling 是本文的示例对外名称，请替换为你的模型列表返回值。平台会将对外名称映射到供应商的模型名。不要把版本拼进名称，也不要自行推测版本，例如填写未开通的 3.0-Pro。

请求参数

参数	类型	说明
`ModelName`	string	必填，当前 Key 可用的对外模型名称，区分大小写。
`ModelVersion`	string	必填，当前模型已授权的版本。
`Prompt`	string	视频内容描述；本文文生视频示例必填。
`NegativePrompt`	string	可选，不希望出现的内容，是否支持取决于模型。
`FileInfos`	array	可选，图片、视频等参考素材，平台当前支持 HTTP(S) URL。
`OutputConfig`	object	输出设置，常用字段见下表。
`ExtInfo`	string	可选，模型扩展参数，内容为 JSON 字符串；WAND-Vega 有专用要求，见文末。

OutputConfig 字段	类型	示例与说明
`StorageMode`	string	本文使用 `Temporary`，请及时保存生成结果。
`Resolution`	string	如 `720P`，注意大小写。
`Duration`	integer	生成时长，单位为秒，例如 `5`。
`AspectRatio`	string	如 `16:9`。
`AudioGeneration`	string	`Enabled` 开启音频，`Disabled` 关闭音频。

不同模型、版本支持的时长、分辨率、比例和音频能力不同。以下参数是调用示例，并不代表所有版本都支持相同组合。

文生视频请求示例

curl --request POST \  --url https://api.maitoken.com/ \  --header 'Authorization: Bearer YOUR_API_KEY' \  --header 'Content-Type: application/json' \  --header 'X-TC-Action: CreateAigcVideoTask' \  --header 'X-TC-Version: 2018-07-17' \  --data '{    "ModelName": "tencent-Kling",    "ModelVersion": "3.0-Omni",    "Prompt": "清晨的海边，一只白色海鸥掠过水面，镜头缓慢向前推进，写实电影风格",    "OutputConfig": {      "StorageMode": "Temporary",      "Resolution": "720P",      "Duration": 5,      "AspectRatio": "16:9",      "AudioGeneration": "Disabled"    }  }'

图生视频请求示例

使用首帧图片时，在 FileInfos 中设置 Usage: "FirstFrame"。素材 URL 必须可被供应商访问，请将示例 URL 替换为真实图片地址。

curl --request POST \  --url https://api.maitoken.com/ \  --header 'Authorization: Bearer YOUR_API_KEY' \  --header 'Content-Type: application/json' \  --header 'X-TC-Action: CreateAigcVideoTask' \  --header 'X-TC-Version: 2018-07-17' \  --data '{    "ModelName": "tencent-Kling",    "ModelVersion": "3.0-Omni",    "Prompt": "保持图片中的主体和场景，海浪轻轻涌动，镜头缓慢推进",    "FileInfos": [      {        "Type": "Url",        "Url": "https://example.com/first-frame.jpg",        "Category": "Image",        "Usage": "FirstFrame"      }    ],    "OutputConfig": {      "StorageMode": "Temporary",      "Resolution": "720P",      "Duration": 5,      "AudioGeneration": "Disabled"    }  }'

参考素材模式可使用 Usage: "Reference"，具体支持哪些素材类型以所选模型为准。平台当前不支持使用 FileId、ObjectId、LastFrameFileId 或 draft_task_id 引用托管资源。

提交成功响应

以下响应中的 ID 均为示意值：

{  "Response": {    "TaskId": "example-aigc-video-task-id",    "RequestId": "example-create-request-id"  }}

保存 Response.TaskId 用于后续查询。返回任务 ID 表示任务已受理，不表示视频已经生成完成。

查询任务状态

POST /X-TC-Action: DescribeTaskDetail

建议使用提交时的 API Key。查询只需提供 TaskId，不必重复提交模型、版本或生成参数。

curl --request POST \  --url https://api.maitoken.com/ \  --header 'Authorization: Bearer YOUR_API_KEY' \  --header 'Content-Type: application/json' \  --header 'X-TC-Action: DescribeTaskDetail' \  --header 'X-TC-Version: 2018-07-17' \  --data '{"TaskId":"example-aigc-video-task-id"}'

可每隔 5～10 秒查询一次；这是客户端轮询建议，不是接口限额承诺。超时或临时网络失败时适当延长间隔，不要重新提交生成请求代替查询。

处理中响应

下列响应省略了与状态判断无关的字段：

{  "Response": {    "TaskType": "AigcVideoTask",    "Status": "PROCESSING",    "AigcVideoTask": {      "TaskId": "example-aigc-video-task-id",      "Status": "PROCESSING"    },    "RequestId": "example-query-request-id"  }}

以 Response.AigcVideoTask 中的状态和错误信息判断生成结果：

条件	含义	下一步
`Status = WAITING`	等待处理	继续轮询。
`Status = PROCESSING`	正在生成	继续轮询。
`Status = FINISH`、`ErrCode = 0` 且 `ErrCodeExt` 为空	生成成功	获取输出文件。
`Status = FINISH`，且错误码非零或 `ErrCodeExt` 非空	生成失败	查看 `Message`，停止轮询。

仅看到 FINISH 不能直接判断成功；错误码尚未返回时，也不要将缺失值当作成功。

成功响应

{  "Response": {    "TaskType": "AigcVideoTask",    "Status": "FINISH",    "AigcVideoTask": {      "TaskId": "example-aigc-video-task-id",      "Status": "FINISH",      "ErrCode": 0,      "ErrCodeExt": "",      "Message": "",      "Output": {        "FileInfos": [          {            "FileUrl": "https://example.com/generated-video.mp4",            "MetaData": { "Duration": 5.0 }          }        ]      }    },    "RequestId": "example-query-request-id"  }}

失败响应

接口调用失败时，检查 Response.Error。即使 HTTP 状态为 200，出现该对象也表示业务失败：

{  "Response": {    "Error": {      "Code": "InvalidParameterValue",      "Message": "ModelVersion 3.0-Pro is invalid for ModelName Kling"    },    "RequestId": "example-error-request-id"  }}

任务已受理但生成失败时，错误信息位于 Response.AigcVideoTask.ErrCode、ErrCodeExt 和 Message。排查时请同时保留 TaskId、RequestId 和完整错误信息。

下载视频

生成成功后，从 Response.AigcVideoTask.Output.FileInfos[] 读取 FileUrl，访问对应地址下载结果。

curl --location \  --url 'https://example.com/generated-video.mp4' \  --output generated-video.mp4

将示例地址替换为实际返回的 FileUrl。不要向视频下载域名发送 MaiToken API Key。临时输出地址的有效期以上游实际返回和规则为准，建议生成后立即转存。

注意事项

模型名称、版本和价格以平台当前配置与当前 Key 授权为准。不同版本不会自动互相替代。
创建和查询都使用 POST /，并设置对应的腾讯 Action Header。
腾讯云文档中的 SubAppId 由平台注入，直接复制官方示例时请移除此字段。
请求体使用原生字段及大小写，例如 ModelName、ModelVersion、TaskId，不是 model、model_version、task_id。
任务查询存在归属校验；任务映射过期、任务 ID 错误或访问身份不匹配时可能无法查询，请及时保存生成结果。
如果创建请求超时且无法确定是否受理，不要无限自动重试，以免重复生成。
当前平台开放 CreateAigcVideoTask 和 DescribeTaskDetail，其他腾讯云 Action 不在此接入范围内。

WAND-Vega 扩展

调用 wand-vega-video 时，还需在 ExtInfo 中启用用量返回。ExtInfo 及其内部 WandVegaParameters 均为 JSON 字符串：

{  "ModelName": "wand-vega-video",  "ModelVersion": "1.0-pro",  "ExtInfo": "{\"WandVegaParameters\":\"{\\\"ReturnVegaUsage\\\":true}\"}"}

以上仅展示需补充的字段，请同时填写提示词和适用的输出设置；版本仍以模型列表为准。使用代码构造请求时，建议通过 JSON 序列化生成这两层字符串。Kling 等标准腾讯云视频模型不要求此扩展。

腾讯云视频生成 API 使用文档