创建图片模版

最近更新时间：2023.05.19 15:49:35

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

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

请求说明

接口名称：CreateImageTemplate
请求方式：POST
接口地址示例：https://imagex.volcengineapi.com/?Action=CreateImageTemplate&Version=2018-08-01
请求频率：1000 次/秒
超时时间：5 秒

说明

veImageX 在全球多个区域部署，每个区域有自己对应的 OpenAPI 域名，不支持跨区域调用。具体详情请查看服务地址。

请求参数

以下请求参数列表仅列出了该接口的部分公共参数，完整公共参数列表见公共参数。

Query

参数类型是否必选描述

Action String 是接口名称。

Version String 是接口版本。veImageX 当前 API 的版本为 2018-08-01。

参数	类型	是否必选	描述
Action	String	是	接口名称。
Version	String	是	接口版本。veImageX 当前 API 的版本为 `2018-08-01`。
ServiceId	String	是	服务 ID。您可以在 veImageX 控制台服务管理页面，在创建好的图片服务中获取服务 ID。您也可以通过 OpenAPI 的方式获取服务 ID，具体请参考获取所有服务信息。

ServiceId

String

是

服务 ID。

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

Body

参数	类型	是否必选	描述
TemplateName	String	是	模板名称，必须使用该服务的图片模板固定前缀。模板名称能包含的字符正则集合为[a-zA-Z0-9_-]。说明您可以通过调用获取单个服务信息接口的查看返回参数`TemplatePrefix`的值。
DoUpdate	Bool	否	是否直接更新模板。取值为`true`，已有的线上模板会同步更新，该操作直接生效；取值为`false`，新增一个模板，已有模板不受影响。
WithSig	Bool	否	是否开启鉴权。默认关闭。取值为`true`，表示开启鉴权。取值为`false`，表示关闭鉴权。说明一般当通过模板参数下发敏感信息时，比如文字水印内容、URL 失效期，需要对图片 URL 鉴权保护，防止内容被篡改。
Parameters	Array of String	否	图片模板使用的参数列表，URL 中下发参数的顺序需要跟列表中的保持一致。
ReqDeadline	String	否	URL 的失效期，为 Unix 时间戳，一般配置为通过模板参数下发。
OuputQuality	Integer	否	对图片编码使用的质量参数，取值范围为 [1,100]，默认为 75。
OutputFormat	String	是	该模板计划使用的输出格式。取值为`image`，表示输出原格式。支持输出的静图格式：png、jpeg、heic、avif、webp。支持输出的动图格式：awebp、heif、avis。
DemotionFormat	String	否	模板计划使用的降级格式，仅对 heic 静图有效。
Sync	Bool	否	是否同步处理，仅对 heic 静图有效。
Filters	Array of Filters	否	对图片的编辑操作。
AdaptiveFmt	JSON Map	否	指定图像自适应配置。
OutputExtra	JSON Map	否	用于图片服务输出时的图片编码自定义参数，键值均为string。取值`png.use_quant`表示是否开启 png quant 压缩，取值为`true`表示开启，取值为`false`表示关闭；取值`heic.sync`表示使用 heic 同步编码，取值为`true`表示同步；取值`heic.timeout`表示 heic 同步编码的超时时间，比如 20。
Snapshot	JSON Map	否	视频截帧配置。
Animation	JSON Map	否	视频转动图配置。

OutputExtra

参数	类型	是否必填	描述
png.use_quant	String	否	是否压缩颜色空间。默认关闭。取值为`true`，表示开启；取值为`false`，表示关闭。
jpeg.progressive	String	否	是否采用 jpeg 渐进编码格式。默认关闭。取值为`true`，表示开启；取值为`false`，表示关闭。
heic.roi	String	否	是否开启 ROI 编码。仅当`OutputFormat`取值为`heic`时配置有效，默认关闭。取值为`true`，表示开启；取值为`false`，表示关闭。
heic.encode.depth	String	否	色位深度。仅当`OutputFormat`取值为`heic`时配置有效，默认关闭。支持取值为：8bit、10bit。说明值越大则提供的图像色彩范围越多，使图像颜色变化的更细腻，但图像体积也会增大。
heic.thumb.ratio	String	否	缩略图比例，仅当`OutputFormat`取值为`heic`时配置有效，开启后默认为 5。默认关闭。
heic.alpha.reserve	String	否	是否带 ALPHA 透明通道编码。仅当`OutputFormat`取值为`heic`时配置有效，默认开启。取值为`true`，表示开启；取值为`false`，表示关闭。

AdaptiveFmt

说明

自适应的具体原理说明请参考实现原理。

参数	类型	是否必填	描述
Static	String	否	静图自适应，支持取值：webp、heic、avif、dynamic。取值为`dynamic`表示智能策略。
Animated	String	否	动图自适应，支持取值：webp、heic、avif、dynamic。取值为`dynamic`表示智能策略。

Snapshot

参数类型是否必填描述

参数	类型	是否必填	描述
Type	String	否	截图类型。取值为`default`时，表示智能截图。取值为`offset`时，表示指定时间戳截图。
TimeOffsetMs	Integer	否	截图的时间戳，单位为 ms。

Type

String

否

截图类型。

取值为default时，表示智能截图。
取值为offset时，表示指定时间戳截图。

TimeOffsetMs Integer 否截图的时间戳，单位为 ms。

Animation

参数	类型	是否必填	描述
StartTime	Integer	否	动图起始时间戳，单位为 ms。
Duration	Integer	否	动图时长，单位为 ms。
SelectFrameMode	String	否	抽帧策略：取值为`fps`，表示抽帧频率，1 秒 X 帧。取值为`spf`，表示抽帧间隔，X 秒 1 帧。取值为`key`，表示抽取关键帧。
FramePerSecond	Integer	否	帧率，1 秒 X 帧。仅当`SelectFrameMode`取值为`fps`时需要配置。
SecondPerFrame	Integer	否	秒数，X 秒 1 帧。仅当`SelectFrameMode`取值为`spf`时需要配置。
WaitTime	Integer	否	同步等待时长，单位为 s，超时未完成则根据`DemotionType`降级。
DemotionType	String	否	降级类型。取值为`image`，表示抽取一帧降为静图返回。取值为`video`，表示直接返回原资源降级。

Filters

参数	类型	是否必填	描述
Name	String	是	操作名称，具体详情请见图片编辑数据结构。
Param	JSON Map	是	操作参数配置内容，Key 为参数名称，Value 为参数配置。具体详情请见图片编辑数据结构。

返回参数

参数	类型	描述
ServiceId	String	服务 ID。
TemplateName	String	创建的模板名称。如果基于原模板做模板名称的更新，则会生成一个新模板。
CreateAt	String	模板的创建时间。

示例

请求示例

POST https://imagex.volcengineapi.com/?Action=CreateImageTemplate&Version=2018-08-01&ServiceId=fc51f8f9*
{
    "TemplateName": "tplv-xyz-xxx",
    "Parameters": [
        "width"
    ],
    "OuputQuality": 85,
    "Filters": [
        {
            "Name": "resize",
            "Param": {
                "width": "${width}",
                "height": 0,
                "keepratio": true
            }
        }
    ]
}

正常返回示例

{
    "ResponseMetadata": {
        "RequestId": "201806041104200100100232280022D30",
        "Action": "CreateImageTemplate",
        "Version": "2018-08-01",
        "Service": "imagex",
        "Region": "cn-north-1"
    },
    "Result": {
        "ServiceId": "d7b84ac7-38b7-4f4f-8eea-fff3c5f95be0",
        "TemplateName": "tplv-xyz-xxx",
        "CreateAt": "2018-05-09 17:44:40"
    }
}

异常返回示例

{
    "ResponseMetadata": {
        "RequestId": "201806041104200100100232280022D30",
        "Action": "CreateImageTemplate",
        "Version": "2018-08-01",
        "Service": "imagex",
        "Region": "cn-north-1"
        "Error": {
            "Code": "CreateTemplateFailure",
            "Message": "Service not found."
        }
    }
}

错误码

访问公共错误码以及模板相关错误码获取详细信息。