You need to enable JavaScript to run this app.
导航
获取单个图片模板
最近更新时间: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

参数类型是否必选描述
ActionString接口名称。
VersionString接口版本。veImageX 当前 API 的版本为 2018-08-01

ServiceId

String

服务 ID。

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

TemplateName

String

模板名称。

返回参数

参数
类型
描述
ServiceIDString服务 ID。
TemplateNameString模板名称。
CreateAtString模板创建时间。
AbstractArray of String模板的摘要信息。

WithSig

Bool

模板是否开启鉴权。

  • 取值为true,表示开启鉴权。
  • 取值为false,表示关闭鉴权。
ParametersArray of String图片模板的参数列表,URL 中下发参数的顺序需要跟列表中的保持一致。
ReqDeadlineStringURL 的失效期,为 Unix 时间戳。
OuputQualityInteger对图片编码使用的质量参数,取值范围为 [1,100],默认为 75。

OutputFormat

String

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

  • 取值为image,表示输出原格式。
  • 支持输出的静图格式:png、jpeg、heic、avif、webp。
  • 支持输出的动图格式:awebp、heif、avis。
DemotionFormatString模板计划使用的降级格式,仅对 heic 静图有效。
SyncBool是否同步处理,仅对 heic 图有效。
UsageString该模板的使用用例。
FiltersArray of Filters对图片的编辑操作。

OutputExtra

JSON Map

编码自定义参数,键值均为 String。

  • 取值png.use_quant表示是否开启 png quant 压缩,取值为true表示开启,取值为false表示关闭;
  • 取值heic.sync表示使用 heic 同步编码,取值为true表示同步;
  • 取值heic.timeout表示 heic 同步编码的超时时间,比如 20。
AdaptiveFmtJSON Map指定图像自适应配置。
SnapshotJSON Map视频截帧配置。
AnimationJSON 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.ratioString缩略图比例,仅当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时,表示指定时间戳截图。
TimeOffsetMsInteger截图的时间戳,单位为 ms。

Animation

参数类型描述
StartTimeInteger动图起始时间戳,单位为 ms。
DurationInteger动图时长,单位为 ms。

SelectFrameMode

String

抽帧策略。

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

DemotionType

String

降级类型。

  • 取值为image,表示抽取一帧降为静图返回。
  • 取值为video,表示直接返回原资源降级。

Filters

参数类型描述
NameString编辑操作的名称,具体详情请见图片编辑数据结构
ParamJSON 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."
        }
    }
}

错误码

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