You need to enable JavaScript to run this app.
导航
创建图片模板
最近更新时间:2024.02.29 15:03:58首次发布时间: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 中通过模板参数动态下发。
OuputQualityInteger75对图片编码使用的质量参数,取值范围为 [1,100],默认为 75。

OutputFormat

String

image

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

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

DemotionFormat

String

jpeg

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

  • webp
  • jpeg

Sync

Boolean

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

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

OutputExtra

Object of OutputExtra

-

用于图片服务输出时的图片编码自定义参数,键值均为 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

-

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

QualityModeStringrelative压缩质量模型,默认为空,表示使用绝对质量。取值 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:否
jpeg.alpha.demotion.pngStringpngjpeg 的 alpha 图片是否降级为 png,指定为 png 时表示降级为 png 格式。缺省情况下默认为空,表示不降级。

jpeg.size.fixed.padding

String

append

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

jpeg.size.fixed

String

10000

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

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

Long

0

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": "202306041104200100100232280022D31",
        "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": []
    }
}

错误码

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

服务端 SDK

为了方便您快速开发,veImageX 提供了配套的服务端 SDK,同时支持多种编程语言。建议您使用服务端 SDK 来调用 API,参考文档如下所示: