ServiceId

String

是

8h**9q

服务 ID。

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

TemplateName

String

是

tplv-e4**c0-test

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

DoUpdate

Boolean

否

false

是否直接更新模板，取值如下所示：

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

WithSig

Boolean

否

false

是否开启鉴权，取值如下所示：

• true：开启鉴权。
• false：（默认）关闭鉴权。

OutputFormat

String

否

image

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

• 取值为image，表示输出原格式。
• 支持输出的静图格式：png、jpeg、heic、avif、webp、vvic。
• 支持输出的动图格式：awebp、heif、avis。

DemotionFormat

String

否

jpeg

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

• webp
• jpeg

Sync

Boolean

否

是

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

• true：是
• false：否

OutputExtra

Object of OutputExtra

否

-

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

• 取值png.use_quant表示是否开启 png quant 压缩，取值为true表示开启，取值为false表示关闭；
• 取值heic.sync表示使用 heic 同步编码，取值为true表示同步；
• 取值heic.timeout表示 heic 同步编码的超时时间，比如 20。

Snapshot

Object of Snapshot

否

-

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

Animation

Object of Animation

否

-

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

Exif

Object of Exif

否

-

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

AnimExtract

Object of AnimExtract

否

-

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

Persistence

String

否

read_write

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

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

Temporary

Boolean

否

true

是否为临时使用，取值如下所示：

• true：是
• false：否

Param

JSON Map

是

{
		"bright":26
}

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

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：否

jpeg.size.fixed.padding

String

否

append

指定 jpeg 体积的输出大小，需同时指定 jpeg.size.fixed，二者缺一不可。
体积填充方式，取值固定为 append。

jpeg.size.fixed

String

否

10000

指定 jpeg 体积的输出大小，需同时设置 jpeg.size.fixed.padding，二者缺一不可。
指定输出体积大小，单位为 Byte。

Param

JSON Map

是

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

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

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 指定格式。

Type

String

是

default

视频截帧类型，取值如下所示：

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

TimeOffsetMs

Long

否

0

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