Tencent VOD AIGC code helper

v1.0.0

腾讯云点播（VOD）AIGC 接口对接助手。当用户需要对接腾讯云点播 AIGC 生图、生视频、自定义主体、自定义音色等接口时使用，包括：调用各类 AIGC API、查询任务状态、处理回调事件、使用腾讯云 SDK 示例代码等场景。

0· 96· 1 versions· 0 current· 0 all-time· Updated 9h ago· MIT-0

Security Scans

VirusTotalBenign ClawScanBenign Static analysisBenign

Install

openclaw skills install tencent-vod-aigc-code-helper

腾讯云点播 AIGC 接口对接助手

核心文档链接

在回答时，必须主动提供以下文档链接供用户参考：

功能	接口名	文档地址
AIGC 生图接口	`CreateAigcImageTask`	https://cloud.tencent.com/document/product/266/126240
AIGC 生视频接口	`CreateAigcVideoTask`	https://cloud.tencent.com/document/product/266/126239
创建 AIGC 自定义主体	`CreateAigcCustomElement`	https://cloud.tencent.com/document/product/266/127544
创建 AIGC 自定义音色	`CreateAigcCustomVoice`	https://cloud.tencent.com/document/product/266/129120
创建 AIGC 高级自定义主体	`CreateAigcAdvancedCustomElement`	https://cloud.tencent.com/document/product/266/129121
创建 AIGC 自定义主体（Vidu）	`CreateAigcSubject`	https://cloud.tencent.com/document/product/266/129192
数据结构文档	-	https://cloud.tencent.com/document/product/266/31773
API 接口概览（找不到接口时查这里）	-	https://cloud.tencent.com/document/product/266/31753
查询任务接口	`DescribeTaskDetail`	https://cloud.tencent.com/document/product/266/33431
API 密钥文档	-	https://cloud.tencent.com/document/api/266/31757
回调事件文档	-	https://cloud.tencent.com/document/product/266/35579
子应用管理文档	-	https://cloud.tencent.com/document/api/266/43744

📌 补充参考文档（更及时）：官网文档可能存在轻微更新滞后（如新增参数未及时同步），遇到参数疑问时请同时参考以下腾讯文档：

生图/生视频接口参数表：https://doc.weixin.qq.com/sheet/e3_AOcASwZGACkCNPE0YsRJjS761Zng7?scode=AJEAIQdfAAo0s201lCAMkAoQZ9ACc&tab=0znb2u

接口详细说明文档：https://doc.weixin.qq.com/doc/w3_AUUAAQaDAMYCNbqzKJeSsTSKfdAbP?scode=AJEAIQdfAAowpfCxSPAMkAoQZ9ACc

🔍 找不到接口时：如果用户要求的接口在上表中找不到，请先查阅 API 接口概览，找到对应接口后再跳转到具体文档页面。

必须告知用户的关键信息

1. API 密钥

用户需要腾讯云 API 密钥（SecretId + SecretKey）才能调用接口
密钥获取文档：https://cloud.tencent.com/document/api/266/31757
安全提示：密钥不要硬编码在代码中，建议使用环境变量或配置文件

2. SubAppId（子应用 ID）

调用云点播 API 时，必须填写准确的 SubAppId（子应用 ID），否则请求会失败或操作到错误的子应用
在腾讯云点播控制台可以查看子应用列表及对应的 SubAppId
如果子应用不存在，需要先创建子应用，参考文档：https://cloud.tencent.com/document/api/266/43744
如何获取 SubAppId：登录腾讯云点播控制台 → 左上角切换子应用 → 查看当前子应用 ID

3. 异步任务机制

CreateAigcImageTask、CreateAigcVideoTask 等生图/生视频接口均为异步任务接口，调用后不会立即返回结果
接口调用成功后会返回 TaskId，需要通过该 TaskId 轮询 DescribeTaskDetail 查询任务状态
查询接口：https://cloud.tencent.com/document/product/266/33431
查询间隔建议 5 秒以上，避免频繁请求
任务状态字段：PROCESSING（处理中）、FINISH（已完成）、FAIL（失败）

4. 推荐使用腾讯云 SDK

强烈建议用户使用腾讯云官方 SDK，而非直接拼接 HTTP 请求：

语言	SDK 地址
Python	https://github.com/TencentCloud/tencentcloud-sdk-python
Go	https://github.com/TencentCloud/tencentcloud-sdk-go
Java	https://github.com/TencentCloud/tencentcloud-sdk-java
Node.js	https://github.com/TencentCloud/tencentcloud-sdk-nodejs
PHP	https://github.com/TencentCloud/tencentcloud-sdk-php
.NET	https://github.com/TencentCloud/tencentcloud-sdk-dotnet

⚠️ SDK 版本提示：如果 SDK 中缺少文档中的某个参数或 Request 类（如 CreateAigcImageTaskRequest、CreateAigcVideoTaskRequest、CreateAigcCustomElementRequest 等），可能是 SDK 版本较旧，需要升级到最新版本。

💡 参数参考提示：官网文档偶有更新滞后，若发现参数与实际不符，请参考补充文档获取最新参数说明：

https://doc.weixin.qq.com/sheet/e3_AOcASwZGACkCNPE0YsRJjS761Zng7?scode=AJEAIQdfAAo0s201lCAMkAoQZ9ACc&tab=0znb2u

https://doc.weixin.qq.com/doc/w3_AUUAAQaDAMYCNbqzKJeSsTSKfdAbP?scode=AJEAIQdfAAowpfCxSPAMkAoQZ9ACc

代码示例规范

Python 示例（使用 Python 3）

安装 SDK

pip3 install tencentcloud-sdk-python
# 如已安装，升级到最新版本
pip3 install --upgrade tencentcloud-sdk-python

完整示例

import os
import time
from tencentcloud.common import credential
from tencentcloud.common.exception.tencent_cloud_sdk_exception import TencentCloudSDKException
from tencentcloud.vod.v20180717 import vod_client, models


def create_aigc_image_task(secret_id: str, secret_key: str, sub_app_id: int):
    """调用腾讯云点播 AIGC 生图接口 CreateAigcImageTask
    文档：https://cloud.tencent.com/document/product/266/126240
    数据结构：https://cloud.tencent.com/document/product/266/31773
    sub_app_id: 子应用 ID，必填；如需创建：https://cloud.tencent.com/document/api/266/43744
    """
    try:
        cred = credential.Credential(secret_id, secret_key)
        client = vod_client.VodClient(cred, "")  # VOD 不需要指定 region

        req = models.CreateAigcImageTaskRequest()
        req.SubAppId = sub_app_id  # 必填：子应用 ID
        # 根据文档填写其他参数，详见：https://cloud.tencent.com/document/product/266/126240
        # 如官网文档参数有疑问，参考：https://doc.weixin.qq.com/sheet/e3_AOcASwZGACkCNPE0YsRJjS761Zng7?scode=AJEAIQdfAAo0s201lCAMkAoQZ9ACc&tab=0znb2u
        # req.Definition = 0  # 模板 ID
        # req.Text = "your prompt here"

        resp = client.CreateAigcImageTask(req)
        print(f"生图任务已提交，TaskId: {resp.TaskId}")
        return resp.TaskId
    except TencentCloudSDKException as e:
        print(f"SDK 异常: {e}")
        raise


def create_aigc_video_task(secret_id: str, secret_key: str, sub_app_id: int):
    """调用腾讯云点播 AIGC 生视频接口 CreateAigcVideoTask
    文档：https://cloud.tencent.com/document/product/266/126239
    数据结构：https://cloud.tencent.com/document/product/266/31773
    sub_app_id: 子应用 ID，必填；如需创建：https://cloud.tencent.com/document/api/266/43744
    """
    try:
        cred = credential.Credential(secret_id, secret_key)
        client = vod_client.VodClient(cred, "")

        req = models.CreateAigcVideoTaskRequest()
        req.SubAppId = sub_app_id  # 必填：子应用 ID
        # 根据文档填写其他参数，详见：https://cloud.tencent.com/document/product/266/126239
        # 如官网文档参数有疑问，参考：https://doc.weixin.qq.com/sheet/e3_AOcASwZGACkCNPE0YsRJjS761Zng7?scode=AJEAIQdfAAo0s201lCAMkAoQZ9ACc&tab=0znb2u
        # req.Definition = 0  # 模板 ID
        # req.Text = "your prompt here"

        resp = client.CreateAigcVideoTask(req)
        print(f"生视频任务已提交，TaskId: {resp.TaskId}")
        return resp.TaskId
    except TencentCloudSDKException as e:
        print(f"SDK 异常: {e}")
        raise


def create_aigc_custom_element(secret_id: str, secret_key: str, sub_app_id: int):
    """创建 AIGC 自定义主体 CreateAigcCustomElement
    文档：https://cloud.tencent.com/document/product/266/127544
    sub_app_id: 子应用 ID，必填；如需创建：https://cloud.tencent.com/document/api/266/43744
    """
    try:
        cred = credential.Credential(secret_id, secret_key)
        client = vod_client.VodClient(cred, "")

        req = models.CreateAigcCustomElementRequest()
        req.SubAppId = sub_app_id  # 必填：子应用 ID
        # 根据文档填写其他参数，详见：https://cloud.tencent.com/document/product/266/127544

        resp = client.CreateAigcCustomElement(req)
        print(f"自定义主体已创建，TaskId: {resp.TaskId}")
        return resp.TaskId
    except TencentCloudSDKException as e:
        print(f"SDK 异常: {e}")
        raise


def query_task_status(secret_id: str, secret_key: str, task_id: str, sub_app_id: int):
    """轮询查询任务状态（DescribeTaskDetail）
    文档：https://cloud.tencent.com/document/product/266/33431
    注意：AIGC 任务耗时较长，查询间隔建议 5 秒以上
    """
    cred = credential.Credential(secret_id, secret_key)
    client = vod_client.VodClient(cred, "")

    while True:
        req = models.DescribeTaskDetailRequest()
        req.TaskId = task_id
        req.SubAppId = sub_app_id  # 必填：子应用 ID

        resp = client.DescribeTaskDetail(req)
        status = resp.Status

        print(f"任务状态: {status}")
        if status == "FINISH":
            print("任务完成！")
            return resp
        elif status == "FAIL":
            print("任务失败！")
            return resp
        else:
            # PROCESSING - 继续等待，间隔 5 秒以上
            time.sleep(5)


if __name__ == "__main__":
    # 从环境变量读取密钥（推荐方式，避免硬编码）
    # 密钥申请文档：https://cloud.tencent.com/document/api/266/31757
    secret_id = os.environ.get("TENCENTCLOUD_SECRET_ID")
    secret_key = os.environ.get("TENCENTCLOUD_SECRET_KEY")
    # 子应用 ID，在腾讯云点播控制台获取
    # 如需创建子应用：https://cloud.tencent.com/document/api/266/43744
    sub_app_id = int(os.environ.get("VOD_SUB_APP_ID", "0"))

    # 示例：生图并查询结果
    # task_id = create_aigc_image_task(secret_id, secret_key, sub_app_id)
    # result = query_task_status(secret_id, secret_key, task_id, sub_app_id)

    # 示例：生视频并查询结果
    # task_id = create_aigc_video_task(secret_id, secret_key, sub_app_id)
    # result = query_task_status(secret_id, secret_key, task_id, sub_app_id)

    # 示例：创建自定义主体
    # task_id = create_aigc_custom_element(secret_id, secret_key, sub_app_id)
    # result = query_task_status(secret_id, secret_key, task_id, sub_app_id)

Go 示例

安装 SDK

go get github.com/tencentcloud/tencentcloud-sdk-go/tencentcloud/vod/v20180717

完整示例

package main

import (
    "fmt"
    "os"
    "strconv"
    "time"

    "github.com/tencentcloud/tencentcloud-sdk-go/tencentcloud/common"
    "github.com/tencentcloud/tencentcloud-sdk-go/tencentcloud/common/errors"
    vod "github.com/tencentcloud/tencentcloud-sdk-go/tencentcloud/vod/v20180717"
)

// createAigcImageTask 调用生图接口 CreateAigcImageTask
// 文档：https://cloud.tencent.com/document/product/266/126240
// 补充参数参考：https://doc.weixin.qq.com/sheet/e3_AOcASwZGACkCNPE0YsRJjS761Zng7?scode=AJEAIQdfAAo0s201lCAMkAoQZ9ACc&tab=0znb2u
func createAigcImageTask(client *vod.Client, subAppId uint64) (string, error) {
    request := vod.NewCreateAigcImageTaskRequest()
    request.SubAppId = common.Uint64Ptr(subAppId) // 必填：子应用 ID
    // 根据文档填写其他参数
    // request.Definition = common.Int64Ptr(0)
    // request.Text = common.StringPtr("your prompt here")

    response, err := client.CreateAigcImageTask(request)
    if _, ok := err.(*errors.TencentCloudSDKError); ok {
        return "", fmt.Errorf("SDK 错误: %s", err)
    }
    taskId := *response.Response.TaskId
    fmt.Printf("生图任务已提交，TaskId: %s\n", taskId)
    return taskId, nil
}

// createAigcVideoTask 调用生视频接口 CreateAigcVideoTask
// 文档：https://cloud.tencent.com/document/product/266/126239
// 补充参数参考：https://doc.weixin.qq.com/sheet/e3_AOcASwZGACkCNPE0YsRJjS761Zng7?scode=AJEAIQdfAAo0s201lCAMkAoQZ9ACc&tab=0znb2u
func createAigcVideoTask(client *vod.Client, subAppId uint64) (string, error) {
    request := vod.NewCreateAigcVideoTaskRequest()
    request.SubAppId = common.Uint64Ptr(subAppId) // 必填：子应用 ID
    // 根据文档填写其他参数
    // request.Definition = common.Int64Ptr(0)
    // request.Text = common.StringPtr("your prompt here")

    response, err := client.CreateAigcVideoTask(request)
    if _, ok := err.(*errors.TencentCloudSDKError); ok {
        return "", fmt.Errorf("SDK 错误: %s", err)
    }
    taskId := *response.Response.TaskId
    fmt.Printf("生视频任务已提交，TaskId: %s\n", taskId)
    return taskId, nil
}

// createAigcCustomElement 创建 AIGC 自定义主体 CreateAigcCustomElement
// 文档：https://cloud.tencent.com/document/product/266/127544
func createAigcCustomElement(client *vod.Client, subAppId uint64) (string, error) {
    request := vod.NewCreateAigcCustomElementRequest()
    request.SubAppId = common.Uint64Ptr(subAppId) // 必填：子应用 ID
    // 根据文档填写其他参数

    response, err := client.CreateAigcCustomElement(request)
    if _, ok := err.(*errors.TencentCloudSDKError); ok {
        return "", fmt.Errorf("SDK 错误: %s", err)
    }
    taskId := *response.Response.TaskId
    fmt.Printf("自定义主体已创建，TaskId: %s\n", taskId)
    return taskId, nil
}

// queryTaskStatus 轮询查询任务状态，间隔 5 秒以上
// 文档：https://cloud.tencent.com/document/product/266/33431
func queryTaskStatus(client *vod.Client, taskId string, subAppId uint64) {
    for {
        request := vod.NewDescribeTaskDetailRequest()
        request.TaskId = common.StringPtr(taskId)
        request.SubAppId = common.Uint64Ptr(subAppId) // 必填：子应用 ID

        response, err := client.DescribeTaskDetail(request)
        if _, ok := err.(*errors.TencentCloudSDKError); ok {
            fmt.Printf("SDK 错误: %s\n", err)
            return
        }

        status := *response.Response.Status
        fmt.Printf("任务状态: %s\n", status)

        if status == "FINISH" || status == "FAIL" {
            break
        }
        // 建议间隔 5 秒以上
        time.Sleep(5 * time.Second)
    }
}

func main() {
    // 密钥申请文档：https://cloud.tencent.com/document/api/266/31757
    cred := common.NewCredential(
        os.Getenv("TENCENTCLOUD_SECRET_ID"),
        os.Getenv("TENCENTCLOUD_SECRET_KEY"),
    )
    // 子应用 ID，在腾讯云点播控制台获取
    // 如需创建子应用：https://cloud.tencent.com/document/api/266/43744
    subAppIdStr := os.Getenv("VOD_SUB_APP_ID")
    subAppId, _ := strconv.ParseUint(subAppIdStr, 10, 64)

    client, _ := vod.NewClient(cred, "", nil)

    // 示例：生图并查询结果
    // taskId, _ := createAigcImageTask(client, subAppId)
    // queryTaskStatus(client, taskId, subAppId)

    // 示例：生视频并查询结果
    // taskId, _ := createAigcVideoTask(client, subAppId)
    // queryTaskStatus(client, taskId, subAppId)

    // 示例：创建自定义主体
    // taskId, _ := createAigcCustomElement(client, subAppId)
    // queryTaskStatus(client, taskId, subAppId)

    _ = client
    _ = subAppId
}

回调事件（可选方案）

如果用户不想轮询查询，可以使用回调事件来获取任务结果：

文档：https://cloud.tencent.com/document/product/266/35579
支持 HTTP 回调和 CMQ/TDMQ 消息队列两种方式
在腾讯云控制台配置回调 URL 后，任务完成时腾讯云会主动推送结果
回调方式适合生产环境，避免轮询带来的资源消耗

建议：

开发调试阶段：使用轮询查询（简单直接）
生产环境：使用回调事件（更高效，节省资源）

常见问题处理

SDK 缺少某个 Request 类（如 CreateAigcImageTaskRequest、CreateAigcCustomElementRequest 等）：SDK 版本较旧，执行 pip3 install --upgrade tencentcloud-sdk-python 升级
鉴权失败：检查 SecretId/SecretKey 是否正确，以及账号是否有 VOD 相关权限
SubAppId 如何获取：登录腾讯云点播控制台，左上角切换子应用即可看到子应用 ID；如子应用不存在，参考文档创建：https://cloud.tencent.com/document/api/266/43744
任务一直 PROCESSING：AIGC 任务耗时较长属正常现象，请耐心等待，不要频繁查询
参数与文档不一致：官网文档可能存在更新滞后，请参考补充文档获取最新参数说明：https://doc.weixin.qq.com/sheet/e3_AOcASwZGACkCNPE0YsRJjS761Zng7?scode=AJEAIQdfAAo0s201lCAMkAoQZ9ACc&tab=0znb2u
找不到需要的接口：请查阅 API 接口概览 https://cloud.tencent.com/document/product/266/31753，找到对应接口后跳转到具体文档页面

Version tags

latestvk974jn1e3814qgnby2jnjw46q984qg5p