You need to enable JavaScript to run this app.
导航

创建图片模版

最近更新时间2023.11.16 10:11:32

首次发布时间2021.02.23 10:42:23

本接口支持指定服务 ID,在该服务下创建图片模板并自定义模板配置。

注意事项

  • 请求频率:单用户请求频率限制为 10 次/秒
  • 超时时间:超时时间约为 5 秒
  • 服务地址:veImageX 在全球多个区域部署,每个区域有自己对应的 OpenAPI 域名,不支持跨区域调用。具体详情请查看服务地址

请求说明

  • 请求方式:POST
  • 请求地址:https://imagex.volcengineapi.com/?Action=CreateImageTemplate&Version=2018-08-01

请求参数

下表仅列出该接口特有的请求参数和部分公共参数。更多信息请见公共请求参数

Query

参数类型是否必选示例值描述
ActionStringCreateImageTemplate接口名称。当前 API 的名称为 CreateImageTemplate
VersionString2018-08-01接口版本。当前 API 的版本为 2018-08-01

ServiceId

String

8h**9q

服务 ID。

  • 您可以在 veImageX 控制台 服务管理页面,在创建好的图片服务中获取服务 ID。
  • 您也可以通过 OpenAPI 的方式获取服务 ID,具体请参考获取所有服务信息

Body

参数类型是否必选示例值描述

TemplateName

String

tplv-e4**c0-test

模板名称,必须使用该服务的图片模板固定前缀。模板名称能包含的字符正则集合为[a-zA-Z0-9_-]。

说明

您可以通过调用获取单个服务信息接口的查看返回参数TemplatePrefix的值。

DoUpdate

Boolean

false

是否直接更新模板,取值如下所示:

  • true:已有的线上模板会同步更新,该操作直接生效;
  • false:新增一个模板,已有模板不受影响。

WithSig

Boolean

false

是否开启鉴权,取值如下所示:

  • true:开启鉴权。
  • false:(默认)关闭鉴权。

说明

一般当通过模板参数下发敏感信息时,比如文字水印内容、URL 失效期,需要对图片 URL 鉴权保护,防止内容被篡改。

ParametersArray of String ["snapshot_time"]图片模板使用的参数列表,URL 中下发参数的顺序需要跟列表中的保持一致。
ReqDeadlineString1636967882URL 的失效期,为 Unix 时间戳,一般配置为在 URL 中通过模板参数动态下发。
OuputQualityFloat75对图片编码使用的质量参数,取值范围为 [1,100],默认为 75。

OutputFormat

String

image

该模板计划使用的输出格式。

  • 取值为image,表示输出原格式。
  • 支持输出的静图格式:pngjpegheicavifwebpvvic
  • 支持输出的动图格式:awebpheifavis

DemotionFormat

String

jpeg

模板计划使用的降级格式,仅对 heic 静图有效。取值如下所示:

  • webp
  • jpeg

Sync

Boolean

是否同步处理,仅对 heic 静图有效。取值如下所示:

  • true:是
  • false:否
FiltersArray of Filters-对图片的编辑操作。

OutputExtra

JSON Map

-

用于图片服务输出时的图片编码自定义参数,键值均为 string。

  • 取值png.use_quant表示是否开启 png quant 压缩,取值为true表示开启,取值为false表示关闭;
  • 取值heic.sync表示使用 heic 同步编码,取值为true表示同步;
  • 取值heic.timeout表示 heic 同步编码的超时时间,比如 20。
EvalsArray of Evals-对结果图片执行的画质评估配置
AdaptiveFmtObject of AdaptiveFmt-指定图像自适应配置。

Snapshot

Object of Snapshot

-

仅当指定输出格式为静图时,配置有效。
视频截帧配置。

Animation

Object of Animation

-

仅当指定输出格式为动图时,配置有效。
视频转动图配置。

Exif

Object of Exif

-

仅当指定输出格式非动图时,配置有效。
保留 EXIF 信息配置。

AnimExtract

Object of AnimExtract

-

仅当指定输出格式为静图时,配置有效。
动图截帧配置。

QualityModeString""压缩质量模型,默认为空,表示使用绝对质量。取值 relative 时,表示使用相对质量,原图为 JPEG 有效。

Persistence

String

read_write

是否对图片结果缓存,默认为空。取值如下所示:

  • read_write:对结果读写
  • read_only:对结果只读

Temporary

Boolean

true

是否为临时使用,取值如下所示:

  • true:是
  • false:否

Filters

参数类型是否必选示例值描述
NameStringbright操作名称,具体详情请见图片编辑数据结构

Param

JSON Map

{
	"bright":26
}

操作参数配置内容,Key 为 参数名称,Value 为 参数配置。具体详情请见图片编辑数据结构

OutputExtra

参数类型是否必选示例值描述

png.use_quant

String

false

是否压缩颜色空间,取值如下所示:

  • true:是
  • false:否

jpeg.progressive

String

false

是否采用 jpeg 渐进编码格式,取值如下所示:

  • true:是
  • false:否

heic.roi

String

false

仅当OutputFormat取值为heic时配置有效
是否开启 ROI 编码,取值如下所示:

  • true:是
  • false:否

heic.encode.depth

String

8

仅当OutputFormat取值为heic时配置有效
色位深度,值越大则提供的图像色彩范围越多,使图像颜色变化的更细腻,但图像体积也会增大。取值如下所示:

  • 8:8bit
  • 10:10bit

heic.thumb.ratio

String

5

仅当OutputFormat取值为heic时配置有效
缩略图比例。在原图基础上,编码缩小一定倍数的小分辨率图片,跟大图一起封装在同一张图片中,缩小倍数不建议过大,一般为 5~10 之间相对合理。

heic.alpha.reserve

String

false

仅当OutputFormat取值为heic时配置有效
是否带透明通道编码,取值如下所示:

  • true:是
  • false:否

Evals

参数类型是否必选示例值描述
NameStringquality评估名,画质评估固定取值为 quality

Param

JSON Map

{
		"ratio":70,
		"types":[
				"vqscore",
        "aesthetic",
        "noise"
    ]
}

画质评估参数配置内容,Key 为 参数名称,Value 为 参数配置。具体详情请见图片编辑数据结构

AdaptiveFmt

参数类型是否必选示例值描述

Static

String

webp

静图自适应,具体实现说明参考图像自适应压缩。取值如下所示:

  • webp:若 HTTP 请求头中 accept 头部包含 image/webp 的字符串匹配,则返回 webp 格式。否则返回 OutputFormat 指定格式。
  • heic:若 HTTP 请求头中 accept 头部包含 image/heic 的字符串匹配,则返回 webp 格式。否则返回 OutputFormat 指定格式。
  • avif:若 HTTP 请求头中 accept 头部包含 image/avif 的字符串匹配,则返回 webp 格式。否则返回 OutputFormat 指定格式。
  • dynamic:智能模式,即根据请求头中 MIME 查找具体格式,查找成功,则返回该格式,否则返回 OutputFormat 指定格式。

Animated

String

webp

动图自适应,具体实现说明参考图像自适应压缩。取值如下所示:
取值如下所示:

  • webp:若 HTTP 请求头中 accept 头部包含 image/webp 的字符串匹配,则返回 webp 格式。否则返回 OutputFormat 指定格式。
  • heic:若 HTTP 请求头中 accept 头部包含 image/heic 的字符串匹配,则返回 webp 格式。否则返回 OutputFormat 指定格式。
  • avif:若 HTTP 请求头中 accept 头部包含 image/avif 的字符串匹配,则返回 webp 格式。否则返回 OutputFormat 指定格式。
  • dynamic:智能模式,即根据请求头中 MIME 查找具体格式,查找成功,则返回该格式,否则返回 OutputFormat 指定格式。

Snapshot

参数类型是否必选示例值描述

Type

String

default

视频截帧类型,取值如下所示:

  • default:智能模式,从视频首帧开始逐帧地检测当前帧是否为黑屏,并最终返回第一个非黑屏的帧。
  • offset:指定时间戳模式,返回指定截帧时间的那一帧。可在 TimeOffsetMsTimeOffsetMsStr 之间二选一。

TimeOffsetMs

Float

6

Typeoffset 时,在TimeOffsetMsTimeOffsetMsStr 之间二选一。
指定截图时间,取值范围为[0,视频时长],单位为 ms。默认为 0,表示返回首帧。若指定时间 > 视频长度,则返回视频最后一帧。

TimeOffsetMsStr

String

${snapshot_time}

Typeoffset 时,在TimeOffsetMsTimeOffsetMsStr 之间二选一。
指定截图时间为使用模板参数动态下发的方式,取值固定为${snapshot_time}

Animation

参数类型是否必选示例值描述
StartTimeInteger6动图起始时间戳,单位为 ms。
DurationInteger1000动图时长,单位为 ms。

SelectFrameMode

String

fps

抽帧策略,取值如下所示:

  • fps:抽帧频率,1 秒 X 帧。
  • spf:抽帧间隔,X 秒 1 帧。
  • key:抽取关键帧。
FramePerSecondInteger10帧率,1 秒 X 帧。仅当SelectFrameMode取值为fps时需要配置。
SecondPerFrameInteger1秒数,X 秒 1 帧。仅当SelectFrameMode取值为spf时需要配置。
WaitTimeInteger5同步等待时长,单位为 s,超时未完成则根据DemotionType降级。

DemotionType

String

vedio

降级类型,取值如下所示:

  • image:抽取一帧降级返回
  • video:直接返回原视频降级

Exif

参数类型是否必选示例值描述

ExifReserve

Boolean

true

是否开启保留全部 EXIF 信息,取值如下所示:

  • true:是
  • false:否

AutoOrientOff

Boolean

false

是否开启保留全部 EXIF 信息。取值如下所示:

  • true:是
  • false:否
ExifRetainNamesArray of String["Orientation", "DateTime"]保留部分 EXIF 信息的具体内容,多个之间用,分隔。更多信息请参考标准 EXIF 标签

AnimExtract

参数类型是否必选示例值描述

Strategy

Integer

0

动图截帧策略,取值如下所示:

  • 0:智能模式,从动图首帧开始逐帧检测当前帧亮度是否大于 80,并最终返回第一个亮度大于 80 的帧。
  • 1:全局最优,从动图首帧开始逐帧检测并返回亮度最大的一帧。
TimeoutInteger1500动图异步处理超时时间,单位为 ms。默认为 1500,取值负数时表示无超时时间。若在指定时间范围内处理未完成则返回失败。

返回参数

下表仅列出本接口特有的返回参数。更多信息请见公共返回参数

参数类型示例值描述
ServiceIdStringe4**c0服务 ID。
TemplateNameStringtplv-e4**c0-test-v1创建的模板名称。如果基于原模板做模板名称的更新,则会生成一个新模板。
CreateAtString2023-11-15 10:50:46模板的创建时间。
UnsupportedArray of Unsupported-不支持的 filter 处理参数。

Unsupported

参数类型示例值描述
NameStringbright操作名称

Param

JSON Map

{
	"bright":26.30910
}

参数对象

示例

请求示例

POST https://imagex.volcengineapi.com/?Action=CreateImageTemplate&Version=2018-08-01&ServiceId=8h**9q
{
   "TemplateName":"tplv-e4**c0-test",
   "OutputExtra":{
      "png.use_quant":"true",
      "anim.force.fmt":"awebp",
      "static.blurhash.enable":"true"
   },
   "Parameters":[
      
   ],
   "ParamValues":[
      
   ],
   "OuputQuality":75,
   "QualityMode":"",
   "Filters":[
      {
         "Name":"bright",
         "Param":{
            "bright":26
         }
      }
   ],
   "Evals":[
      {
         "Name":"quality",
         "Param":{
            "ratio":70,
            "types":[
               "vqscore",
               "aesthetic",
               "noise"
            ]
         }
      }
   ],
   "Evals":[
      
   ],
   "Snapshot":{
      "Type":"default"
   },
   "AnimExtract":{
      "Strategy":0,
      "Timeout":1500
   },
   "Scene":"snapshot",
   "Temporary":true,
   "Exif":{
      "ExifReserve":true
   }
}

返回示例

{
    "ResponseMetadata": {
        "RequestId": "202311151050454323B8E87D7E40500979",
        "Action": "CreateImageTemplate",
        "Version": "2018-08-01",
        "Service": "imagex",
        "Region": "cn-north-1"
    },
    "Result": {
        "ServiceId": "e4**c0",
        "TemplateName": "tplv-e4**c0-test-v1",
        "CreateAt": "2023-11-15 10:50:46",
        "Unsupported": []
    }
}

错误码

本接口无特有的错误码。更多信息请见公共错误码