Skill: tencent-mpaas-skills/tencent-vod-aigc-code-helper (version 1.0.0)

--- name: tencent-vod-aigc-code-helper description: 腾讯云点播（VOD）AIGC 接口对接助手。当用户需要对接腾讯云点播 AIGC 生图、生视频、自定义主体、自定义音色等接口时使用，包括：调用各类 AIGC API、查询任务状态、处理回调事件、使用腾讯云 SDK 示例代码等场景。 metadata: version: "1.0.0" --- # 腾讯云点播 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 接口概览](https://cloud.tencent.com/document/product/266/31753)，找到对应接口后再跳转到具体文档页面。 ## 必须告知用户的关键信息 ### 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 ```bash pip3 install tencentcloud-sdk-python # 如已安装，升级到最新版本 pip3 install --upgrade tencentcloud-sdk-python ``` #### 完整示例 ```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 ```bash go get github.com/tencentcloud/tencentcloud-sdk-go/tencentcloud/vod/v20180717 ``` #### 完整示例 ```go 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 后，任务完成时腾讯云会主动推送结果 - 回调方式适合生产环境，避免轮询带来的资源消耗 **建议**： - 开发调试阶段：使用轮询查询（简单直接） - 生产环境：使用回调事件（更高效，节省资源） ## 常见问题处理 1. **SDK 缺少某个 Request 类**（如 `CreateAigcImageTaskRequest`、`CreateAigcCustomElementRequest` 等）：SDK 版本较旧，执行 `pip3 install --upgrade tencentcloud-sdk-python` 升级 2. **鉴权失败**：检查 SecretId/SecretKey 是否正确，以及账号是否有 VOD 相关权限 3. **SubAppId 如何获取**：登录腾讯云点播控制台，左上角切换子应用即可看到子应用 ID；如子应用不存在，参考文档创建：https://cloud.tencent.com/document/api/266/43744 4. **任务一直 PROCESSING**：AIGC 任务耗时较长属正常现象，请耐心等待，不要频繁查询 5. **参数与文档不一致**：官网文档可能存在更新滞后，请参考补充文档获取最新参数说明：https://doc.weixin.qq.com/sheet/e3_AOcASwZGACkCNPE0YsRJjS761Zng7?scode=AJEAIQdfAAo0s201lCAMkAoQZ9ACc&tab=0znb2u 6. **找不到需要的接口**：请查阅 API 接口概览 https://cloud.tencent.com/document/product/266/31753，找到对应接口后跳转到具体文档页面


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)