提交图片唱演任务

最近更新时间:2025-04-25 02:07:54

我的收藏

1. 接口描述

接口请求域名: vclm.tencentcloudapi.com 。

用于提交图片唱演任务。
支持提交音频和图片生成唱演视频,满足社交娱乐、互动营销等场景的需求。

推荐使用 API Explorer
点击调试
API Explorer 提供了在线调用、签名验证、SDK 代码生成和快速检索接口等能力。您可查看每次调用的请求内容和返回结果以及自动生成 SDK 调用示例。

2. 输入参数

以下请求参数列表仅列出了接口请求参数和部分公共参数,完整公共参数列表见 公共请求参数

参数名称 必选 类型 描述
Action String 公共参数,本接口取值:SubmitPortraitSingJob。
Version String 公共参数,本接口取值:2024-05-23。
Region String 公共参数,详见产品支持的 地域列表
AudioUrl String 传入音频URL地址,音频要求:
- 音频时长:2秒 - 60秒
- 音频格式:mp3、wav、m4a
示例值:https://xxx.com/audio.mp3
ImageUrl String 传入图片URL地址,图片要求:
- 图片格式:jpg、jpeg、png、bmp、webp
- 图片分辨率:192~4096
- 图片大小:不超过10M
- 图片宽高比:图片【宽:高】在1:2到2:1范围内
- 图片内容:避免上传无人脸、无宠物脸或脸部过小、不完整、不清晰、偏转角度过大、嘴部被遮挡的图片。
示例值:https://xxx.com/image.jpg
ImageBase64 String 传入图片Base64编码,编码后请求体大小不超过10M。
图片Base64编码与URL地址必传其一,如果都传以ImageBase64为准。
示例值:/9j/4QlQaHR0c...N6a2M5ZCI
Mode String 唱演模式,默认使用人像模式。
Person:人像模式,仅支持上传人像图片,人像生成效果更好,如果图中未检测到有效人脸将被拦截,生成时会将视频短边分辨率放缩至512。
Pet:宠物模式,支持宠物等非人像图片,固定生成512:512分辨率视频。
示例值:Person
Resolution String 生成视频尺寸。可选取值:"512:512"。

人像模式下,如果不传该参数,默认生成视频的短边分辨率为512,长边分辨率不固定、由模型根据生成效果自动适配得到。如需固定生成分辨率可传入512:512。

宠物模式下,如果不传该参数,默认将脸部唱演视频回贴原图,生成视频分辨率与原图一致。如不需要脸部回贴,仅保留脸部唱演视频,可传入512:512。
示例值:512:512
LogoAdd Integer 为生成视频添加标识的开关,默认为1。
1:添加标识;
0:不添加标识;
其他数值:默认按1处理。
建议您使用显著标识来提示,该视频是 AI 生成的视频。
示例值:1
LogoParam LogoParam 标识内容设置。 默认在生成视频的右下角添加“视频由 AI 生成”字样,您可根据自身需要替换为其他的标识图片。

3. 输出参数

参数名称 类型 描述
JobId String 任务ID。任务有效期为48小时。
示例值:1199999431088685056
RequestId String 唯一请求 ID,由服务端生成,每次请求都会返回(若请求因其他原因未能抵达服务端,则该次请求不会获得 RequestId)。定位问题时需要提供该次请求的 RequestId。

4. 示例

示例1 调用成功-图片url地址

调用成功

输入示例

POST / HTTP/1.1
Host: vclm.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: SubmitPortraitSingJob
<公共请求参数>

{
    "AudioUrl": "https://***/test.mp3",
    "ImageUrl": "https://***/test.png"
}

输出示例

{
    "Response": {
        "JobId": "1199964964965990400",
        "RequestId": "79655032-c347-4f05-af23-ae80f7ff47eb"
    }
}

示例2 调用失败-音频时长超限

音频时长超限

输入示例

POST / HTTP/1.1
Host: vclm.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: SubmitPortraitSingJob
<公共请求参数>

{
    "AudioUrl": "https://***/durationInvalid.m4a",
    "ImageUrl": "https://***/aj.jpg"
}

输出示例

{
    "Response": {
        "Error": {
            "Code": "InvalidParameterValue.InvalidAudioDuration",
            "Message": "音频时长超出限定范围。上传音频的时长要求:在1秒到60秒范围内"
        },
        "RequestId": "9d314f18-3670-4793-bf4b-619b43494ac7"
    }
}

示例3 调用失败-图片分辨率超限

图片分辨率超限

输入示例

POST / HTTP/1.1
Host: vclm.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: SubmitPortraitSingJob
<公共请求参数>

{
    "AudioUrl": "https://***/test.mp3",
    "ImageUrl": "https://***/resolutionInvalid.jpg"
}

输出示例

{
    "Response": {
        "Error": {
            "Code": "InvalidParameterValue.InvalidImageResolution",
            "Message": "图片分辨率超出限定范围。上传图片的长边分辨率要求:在0到2560范围内"
        },
        "RequestId": "29498231-20eb-43d1-bb3b-cc9e07978699"
    }
}

示例4 调用失败-图片宽高比超限

图片宽高比超限

输入示例

POST / HTTP/1.1
Host: vclm.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: SubmitPortraitSingJob
<公共请求参数>

{
    "AudioUrl": "https://***/test.mp3",
    "ImageUrl": "https://***/ratioInvalid.jpg"
}

输出示例

{
    "Response": {
        "Error": {
            "Code": "InvalidParameterValue.InvalidImageAspectRatio",
            "Message": "图片宽高比超出限定范围。上传图片的宽高比要求:在0.5到2.0范围内"
        },
        "RequestId": "3c9cb9bd-5b2a-4b18-a890-73f7712ca2ce"
    }
}

示例5 调用失败-图片大小超限

图片大小超限

输入示例

POST / HTTP/1.1
Host: vclm.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: SubmitPortraitSingJob
<公共请求参数>

{
    "AudioUrl": "https://***/test.mp3",
    "ImageUrl": "https://***/storageInvalid.jpg"
}

输出示例

{
    "Response": {
        "Error": {
            "Code": "InvalidParameterValue.InvalidImageSize",
            "Message": "图片大小超出限定范围。上传图片的大小要求:在0MB到10MB范围内"
        },
        "RequestId": "cd17e6bb-afdb-4bed-8a15-55c461333104"
    }
}

5. 开发者资源

腾讯云 API 平台

腾讯云 API 平台 是综合 API 文档、错误码、API Explorer 及 SDK 等资源的统一查询平台,方便您从同一入口查询及使用腾讯云提供的所有 API 服务。

API Inspector

用户可通过 API Inspector 查看控制台每一步操作关联的 API 调用情况,并自动生成各语言版本的 API 代码,也可前往 API Explorer 进行在线调试。

SDK

云 API 3.0 提供了配套的开发工具集(SDK),支持多种编程语言,能更方便的调用 API。

命令行工具

6. 错误码

以下仅列出了接口业务逻辑相关的错误码,其他错误码详见 公共错误码

错误码 描述
FailedOperation.AudioDecodeFailed 音频解码失败。
FailedOperation.ImageFaceDetectFailed 人脸检测失败
FailedOperation.InnerError 服务内部错误,请重试。
FailedOperation.ModerationAudioFailed 音频审核失败
FailedOperation.ServerError 系统内部错误。
FailedOperation.SubmitAsspFailed 请求声伴分离失败,请重试。
InvalidParameterValue.InvalidAudioDuration 不支持的音频时长。
InvalidParameterValue.InvalidAudioFormat 不支持的音频格式。
InvalidParameterValue.InvalidImageAspectRatio 不支持的图片长宽比。
InvalidParameterValue.InvalidImageFormat 不支持的图片格式
InvalidParameterValue.InvalidImageResolution 图片分辨率超限。
InvalidParameterValue.InvalidImageSize 不支持的图片大小
InvalidParameterValue.InvalidModel 不支持的模型。
InvalidParameterValue.TooLargeFaceAngle 人脸角度过大。
InvalidParameterValue.TooLowFaceQuality 人脸质量过低。
InvalidParameterValue.TooManyFaces 人脸数量超过1。
InvalidParameterValue.TooMuchFaceOcclusion 人脸遮挡过多。
InvalidParameterValue.TooSmallFaceSize 人脸过小。