青云TOP API使用教程&开发文档小白用户&专业开发者快速使用指南
控制台
返回模型调用 API 参考
POST/tencent-vod/v1/aigc-image

创建任务

官方文档:https://cloud.tencent.com/document/product/266/126240

API Key application/json
腾讯 AIGC 异步协议

调用与返回说明

腾讯 AIGC 生图接口采用创建任务、保存 task_id、查询完成状态和读取结果的异步流程。请按页面定义区分任务创建响应和最终结果。

请求时注意

  • 请求头使用 Authorization: Bearer YOUR_API_KEY 和页面声明的 Content-Type。路径中的厂商名称不改变青云TOP API 的鉴权方式，也不要求客户端携带厂商密钥。
  • 模型 ID、模型版本和后缀必须使用当前账号 GET /v1/models 返回且与本页协议匹配的值；旧示例中的固定型号不能视为永久可用。
  • 异步创建返回的是公开任务或 request ID。请原样保存 ID，并只使用页面对应的查询接口继续读取，不要猜测其他前缀或把上游 ID 当作本站 ID。

返回时注意

  • HTTP 2xx 只表示创建或查询请求被接受；业务成功要检查响应体中的状态字段和结果字段。失败、取消、超时或未完成状态不能当作可下载图片。
  • 创建成功后转到本协议对应的查询接口，按建议间隔轮询并设置客户端总超时。
Request

请求

/tencent-vod/v1/aigc-image

Body

必填
Bodyapplication/json
Bodyobject
model_namestring必填

模型名称。取值： GEM：Gemini； Qwen：千问。 Hunyuan：混元。 示例值：GEM

model_versionstring必填

模型版本。取值： 当 ModelName 是 GEM，可选值为 2.5、3.0； 当 ModelName 是 Qwen，可选值为 0925； 当 ModelName 是 Hunyuan，可选值为 3.0； 示例值：2.5

promptstring必填

提示词

file_infosarray<object>
元素object
typestring

输入的视频文件类型。取值有： File：点播媒体文件； Url：可访问的 URL； 示例值：File

file_idstring

图片文件的媒体文件 ID，即该文件在云点播上的全局唯一标识符，在上传成功后由云点播后台分配。可以在 视频上传完成事件通知 或 云点播控制台 获取该字段。当 Type 取值为 File 时，本参数有效。 说明： 1. 推荐使用小于7M的图片； 2. 图片格式的取值为：jpeg，jpg, png, webp。 示例值：3704211***509819

urlstring

可访问的文件 URL。当 Type 取值为 Url 时，本参数有效。 说明： 1. 推荐使用小于7M的图片； 2. 图片格式的取值为：jpeg，jpg, png, webp。 示例值：https://test.com/1.png

textstring

输入图片的描述信息，用于帮助模型理解图片。仅GEM 2.5、GEM 3.0 有效。 示例值：任务背景：这是需要翻新的主建筑（图1），不得改变其几何结构。

negative_promptstring

要阻止模型生成图片的提示词。

enhance_promptstring

是否自动优化提示词。开启时将自动优化传入的 Prompt，以提升生成质量。取值有： Enabled：开启； Disabled：关闭；

output_configobject

生图任务的输出媒体文件配置。

storage_modestring

存储模式。取值有： Permanent：永久存储，生成的图片文件将存储到云点播，可在事件通知中获取到 FileId； Temporary：临时存储，生成的图片文件不会存储到云点播，可在事件通知中获取到临时访问的 URL； 默认值：Temporary

resolutionstring

生成图片的分辨率。可选值为 720P、1080P、2K、4K、1024x1024、2048x2048、2304x1728、2496x1664、2560x1440、3024x1296、4096x4096、4694x3520、4992x3328、5404x3040、6198x2656，其中使用模型 Jimeng 时，推荐通过 Prompt 指定图片分辨率和宽高比。 示例值：1024x1024

aspect_ratiostring

指定所生成图片的宽高比。 当 ModelName 是 GEM，可选值是 1:1、3:2、2:3、3:4、4:3、4:5、5:4、9:16、16:9 和 21:9； 当 ModelName 是 Qwen、Jimeng，则暂不支持，其中 Jimeng 会结合 Prompt意图、参考图片尺寸，由模型智能判断输出图片的宽高比。 示例值：16:9

person_generationstring

是否允许人物或人脸生成。取值有： AllowAdult：允许生成成人； Disallowed：禁止在图片中包含人物或人脸； 示例值：AllowAdult

input_compliance_checkstring

是否开启输入内容的合规性检查。取值有： Enabled：开启； Disabled：关闭； 示例值：Enabled

output_compliance_checkstring

是否开启输出内容的合规性检查。取值有： Enabled：开启； Disabled：关闭； 示例值：Enabled

session_idstring

用于去重的识别码，如果三天内曾有过相同的识别码的请求，则本次的请求会返回错误。最长 50 个字符，不带或者带空字符串表示不做去重。 示例值：mysession

session_contextstring

来源上下文，用于透传用户请求信息，音画质重生完成回调将返回该字段值，最长 1000 个字符。 示例值：mySessionContext

tasks_prioritystring

任务的优先级，数值越大优先级越高，取值范围是 -10 到 10，不填代表 0。 示例值：10

ext_infostring

保留字段，特殊用途时使用。 示例值：myextinfo

路径、查询与 Header 参数

参数位置类型必填说明示例
AuthorizationHeaderstring是必填。使用青云TOP API 的 API Key，保留 Bearer 后的空格。Bearer YOUR_API_KEY
Content-TypeHeaderstring否-application/json
Response

返回响应 200

HTTP 响应
响应 200json
响应 200object
statusstring必填
request_idstring必填
response_urlstring必填
status_urlstring必填
cancel_urlstring必填
logsnull必填
metricsobject必填
queue_positioninteger必填
腾讯 AIGC 异步协议

调用与返回说明

腾讯 AIGC 生图接口采用创建任务、保存 task_id、查询完成状态和读取结果的异步流程。请按页面定义区分任务创建响应和最终结果。

请求时注意

  • 请求头使用 Authorization: Bearer YOUR_API_KEY 和页面声明的 Content-Type。路径中的厂商名称不改变青云TOP API 的鉴权方式，也不要求客户端携带厂商密钥。
  • 模型 ID、模型版本和后缀必须使用当前账号 GET /v1/models 返回且与本页协议匹配的值；旧示例中的固定型号不能视为永久可用。
  • 异步创建返回的是公开任务或 request ID。请原样保存 ID，并只使用页面对应的查询接口继续读取，不要猜测其他前缀或把上游 ID 当作本站 ID。

返回时注意

  • HTTP 2xx 只表示创建或查询请求被接受；业务成功要检查响应体中的状态字段和结果字段。失败、取消、超时或未完成状态不能当作可下载图片。
  • 创建成功后转到本协议对应的查询接口，按建议间隔轮询并设置客户端总超时。