获取单个图片模板--veImageX-火山引擎

文档中心

立即注册

导航

获取单个图片模板

最近更新时间：2024.01.31 15:01:57首次发布时间：2021.02.23 10:42:23

本接口支持通过指定服务 ID 以及模板名称，获取单个图片模板的配置详情。

请求说明

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

说明

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

请求参数

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

Query

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

返回参数

参数	类型	描述
ServiceID	String	服务 ID。
TemplateName	String	模板名称。
CreateAt	String	模板创建时间。
Abstract	Array of String	模板的摘要信息。
WithSig	Bool	模板是否开启鉴权。取值为`true`，表示开启鉴权。取值为`false`，表示关闭鉴权。
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 图有效。
Usage	String	该模板的使用用例。
Filters	Array of Filters	对图片的编辑操作。
OutputExtra	JSON Map	编码自定义参数，键值均为 String。取值`png.use_quant`表示是否开启 png quant 压缩，取值为`true`表示开启，取值为`false`表示关闭；取值`heic.sync`表示使用 heic 同步编码，取值为`true`表示同步；取值`heic.timeout`表示 heic 同步编码的超时时间，比如 20。
AdaptiveFmt	JSON Map	指定图像自适应配置。
Snapshot	JSON Map	视频截帧配置。
Animation	JSON Map	视频转动图配置。

OutputExtra

参数	类型	描述
png.use_quant	String	是否压缩颜色空间。默认关闭。取值为`true`，表示开启；取值为`false`，表示关闭。
jpeg.progressive	String	是否采用 jpeg 渐进编码格式。默认关闭。
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	编辑操作的参数，具体详情请见图片编辑数据结构。

示例

请求示例

GET https://imagex.volcengineapi.com/?Action=GetImageTemplate&Version=2018-08-01&ServiceId=fc51f8f9*&TemplateName=tplv-xyz-xxx

正常返回示例

{
    "ResponseMetadata": {
        "RequestId": "201806041104200100100232280022D30",
        "Action": "GetImageTemplate",
        "Version": "2018-08-01",
        "Service": "imagex",
        "Region": "cn-north-1"
    },
    "Result": {
        "ServiceID": "fc51f8f9*",
        "TemplateName": "tplv-xyz-xxx",
        "CreateAt": "2018-05-09 17:44:40",
        "Abstract": [
            "缩略：等比缩放",
            "效果：模糊半径20"
        ],
        "WithSig": false,
        "Parameters": [
            "width"
        ],
        "ReqDeadline": "",
        "OuputQuality": 85,
        "OutputFormat": "image",
        "Sync": false,
        "Usage": "~tplv-xyz-xxx:width.image",
        "Filters": [
            {
                "Name": "resize",
                "Param": {
                    "width": "${width}",
                    "height": 0,
                    "keepratio": true
                }
            }
        ]
    }
}

异常返回示例

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

错误码

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