You need to enable JavaScript to run this app.
导航
模板管理
最近更新时间:2024.06.04 11:54:33首次发布时间:2024.06.04 11:54:33

阅读本文,您可以获取 Node SDK 模板管理的接口调用示例,实现快速开发。

说明

本文的调用示例包含接口的部分参数。由于参数间可能存在互斥关系,在调用时,请您参考注释,进行调整。

调用说明

  • 本文提供的接口调用示例均通过 AK 和 SK 初始化实例。
  • 接口的参数说明和错误码等信息可通过接口文档查看。

前提条件

调用接口前,请先完成 Node SDK 的安装及初始化操作。

调用示例

本节为您介绍模板管理相关接口的功能和调用示例。

创建图片模板

您可以调用 CreateImageTemplate 接口创建图片模板。详细的参数说明可参见 CreateImageTemplate 接口文档。

接口调用示例如下所示。

import { imagex } from "@volcengine/openapi";
  
  export async function CreateImageTemplateDemo () {
    try {
      const imagexService = new imagex.ImagexService({
        // 强烈建议不要把 AccessKey ID 和 AccessKey Secret 保存到工程代码里,否则可能导致 AccessKey 泄露,威胁您账号下所有资源的安全。
        accessKeyId: process.env.VOLC_ACCESSKEY,
        // 本示例通过从环境变量中读取 AccessKey ID 和 AccessKey Secret,来实现 API 访问的身份验证。运行代码示例前,请配置环境变量 VOLC_ACCESSKEY 和 VOLC_SECRETKEY
        secretKey: process.env.VOLC_SECRETKEY,
      });
      const requestParam = {
      // 服务 ID。
      // <li> 您可以在 veImageX 控制台 [服务管理](https://console.volcengine.com/imagex/service_manage/)页面,在创建好的图片服务中获取服务 ID。 </li>
      // <li> 您也可以通过 OpenAPI 的方式获取服务 ID,具体请参考[获取所有服务信息](https://www.volcengine.com/docs/508/9360)。 </li>
      "ServiceId": "8h**9q",
      // 模板名称,必须使用该服务的图片模板固定前缀。模板名称能包含的字符正则集合为[a-zA-Z0-9_-]。
      // note:
      // 您可以通过调用[获取单个服务信息](https://www.volcengine.com/docs/508/9358)接口的查看返回参数`TemplatePrefix`的值。
      "TemplateName": "tplv-e4**c0-test",
      // 是否为临时使用,取值如下所示:
      // <li> `true`:是 </li>
      // <li> `false`:否 </li>
      "Temporary": true,
      // 仅当指定输出格式非动图时,配置有效。
      // 保留 EXIF 信息配置。
      "Exif" : {
        // 是否开启保留全部 EXIF 信息。取值如下所示:
        // <li> `true`:是 </li>
        // <li> `false`:否 </li>
        "AutoOrientOff": false,
        // 保留部分 EXIF 信息的具体内容,多个之间用`,`分隔。更多信息请参考[标准 EXIF 标签](https://exiv2.org/tags.html)。
        "ExifRetainNames" : ["Orientation","DateTime"], 
        // 是否开启保留全部 EXIF 信息,取值如下所示:
        // <li> `true`:是 </li>
        // <li> `false`:否 </li>
        "ExifReserve": true,
      }, 
      // 对结果图片执行的画质评估配置
      "Evals" : [ 
          {
            // 评估名,画质评估固定取值为 `quality`。
            "Name": "quality",
          } 
      ], 
      // 是否直接更新模板,取值如下所示:
      // * `true`:已有的线上模板会同步更新,该操作直接生效;
      // * `false`:新增一个模板,已有模板不受影响。
      "DoUpdate": false,
      // 是否开启鉴权,取值如下所示:
      // * `true`:开启鉴权。
      // * `false`:(默认)关闭鉴权。
      // note:
      // 一般当通过模板参数下发敏感信息时,比如文字水印内容、URL 失效期,需要对图片 URL 鉴权保护,防止内容被篡改。
      "WithSig": false,
      // 图片模板使用的参数列表,URL 中下发参数的顺序需要跟列表中的保持一致。
      "Parameters" : ["snapshot_time"], 
      // URL 的失效期,为 Unix 时间戳,一般配置为在 URL 中通过模板参数动态下发。
      "ReqDeadline": "1636967882",
      // 对图片编码使用的质量参数,取值范围为 [1,100],默认为 75。
      "OuputQuality": 75,
      // 压缩质量模型,默认为空,表示使用绝对质量。取值 `relative` 时,表示使用相对质量,原图为 JPEG 有效。
      "QualityMode": "relative",
      // 是否对图片结果缓存,默认为空。取值如下所示:
      // <li> `read_write`:对结果读写 </li>
      // <li> `read_only`:对结果只读 </li>
      "Persistence": "read_write",
      // 该模板计划使用的输出格式。
      // * 取值为`image`,表示输出原格式。
      // * 支持输出的静图格式:`png`、`jpeg`、`heic`、`avif`、`webp`、`vvic`。
      // * 支持输出的动图格式:`awebp`、`heif`、`avis`。
      "OutputFormat": "image",
      // 模板计划使用的降级格式,仅对 heic 静图有效。取值如下所示:
      // <li> `webp` </li>
      // <li> `jpeg` </li>
      "DemotionFormat": "jpeg",
      // 是否同步处理,仅对 heic 静图有效。取值如下所示:
      // <li> `true`:是 </li>
      // <li> `false`:否 </li>
      "Sync": true,
      // 对图片的编辑操作。
      "Filters" : [ 
          {
            // 操作名称,具体详情请见[图片编辑数据结构](https://www.volcengine.com/docs/508/127820)。
            "Name": "bright",
          } 
      ], 
      // 用于图片服务输出时的图片编码自定义参数,键值均为 string。
      // * 取值`png.use_quant`表示是否开启 png quant 压缩,取值为`true`表示开启,取值为`false`表示关闭;
      // * 取值`heic.sync`表示使用 heic 同步编码,取值为`true`表示同步;
      // * 取值`heic.timeout`表示 heic 同步编码的超时时间,比如 20。
      "OutputExtra" : {
        // 是否压缩颜色空间,取值如下所示:
        // <li> `true`:是 </li>
        // <li> `false`:否 </li>
        "png.use_quant": "false",
        // 是否采用 jpeg 渐进编码格式,取值如下所示:
        // <li> `true`:是 </li>
        // <li> `false`:否 </li>
        "jpeg.progressive": "false",
        // 仅当OutputFormat取值为heic时配置有效
        // 是否开启 ROI 编码,取值如下所示:
        // <li> `true`:是 </li>
        // <li> `false`:否 </li>
        "heic.roi": "false",
        // 仅当OutputFormat取值为heic时配置有效
        // 色位深度,值越大则提供的图像色彩范围越多,使图像颜色变化的更细腻,但图像体积也会增大。取值如下所示:
        // <li> `8`:8bit </li>
        // <li> `10`:10bit </li>
        "heic.encode.depth": "8",
        // 仅当OutputFormat取值为heic时配置有效
        // 缩略图比例。在原图基础上,编码缩小一定倍数的小分辨率图片,跟大图一起封装在同一张图片中,缩小倍数不建议过大,一般为 5~10 之间相对合理。
        "heic.thumb.ratio": "5",
        // 仅当OutputFormat取值为heic时配置有效
        // 是否带透明通道编码,取值如下所示:
        // <li> `true`:是 </li>
        // <li> `false`:否 </li>
        "heic.alpha.reserve": "false",
        "jpeg.alpha.demotion.png": "png", 
        "jpeg.size.fixed": "10000", 
        "jpeg.size.fixed.padding": "append", 
      }, 
      // 指定图像自适应配置。
      "AdaptiveFmt" : {
        // 静图自适应,具体实现说明参考[图像自适应压缩](https://www.volcengine.com/docs/508/75733)。取值如下所示:
        // <li> `webp`:若 HTTP 请求头中 accept 头部包含 image/webp 的字符串匹配,则返回 webp 格式。否则返回 `OutputFormat` 指定格式。 </li>
        // <li> `heic`:若 HTTP 请求头中 accept 头部包含 image/heic 的字符串匹配,则返回 webp 格式。否则返回 `OutputFormat` 指定格式。 </li>
        // <li> `avif`:若 HTTP 请求头中 accept 头部包含 image/avif 的字符串匹配,则返回 webp 格式。否则返回 `OutputFormat` 指定格式。 </li>
        // <li> `dynamic`:智能模式,即根据请求头中 MIME 查找具体格式,查找成功,则返回该格式,否则返回 `OutputFormat` 指定格式。 </li>
        "Static": "webp",
        // 动图自适应,具体实现说明参考[图像自适应压缩](https://www.volcengine.com/docs/508/75733)。取值如下所示:
        // 取值如下所示:
        // <li> `webp`:若 HTTP 请求头中 accept 头部包含 image/webp 的字符串匹配,则返回 webp 格式。否则返回 `OutputFormat` 指定格式。 </li>
        // <li> `heic`:若 HTTP 请求头中 accept 头部包含 image/heic 的字符串匹配,则返回 webp 格式。否则返回 `OutputFormat` 指定格式。 </li>
        // <li> `avif`:若 HTTP 请求头中 accept 头部包含 image/avif 的字符串匹配,则返回 webp 格式。否则返回 `OutputFormat` 指定格式。 </li>
        // <li> `dynamic`:智能模式,即根据请求头中 MIME 查找具体格式,查找成功,则返回该格式,否则返回 `OutputFormat` 指定格式。 </li>
        "Animated": "webp",
      }, 
      // 仅当指定输出格式为静图时,配置有效。
      // 视频截帧配置。
      "Snapshot" : {
        // 视频截帧类型,取值如下所示:
        // <li> `default`:智能模式,从视频首帧开始逐帧地检测当前帧是否为黑屏,并最终返回第一个非黑屏的帧。 </li>
        // <li> `offset`:指定时间戳模式,返回指定截帧时间的那一帧。可在 `TimeOffsetMs` 和 `TimeOffsetMsStr` 之间二选一。 </li>
        "Type": "default",
        // 当 `Type` 为 `offset` 时,在`TimeOffsetMs` 和 `TimeOffsetMsStr` 之间二选一。
        // 指定截图时间,取值范围为[0,视频时长],单位为 ms。默认为 0,表示返回首帧。若指定时间 > 视频长度,则返回视频最后一帧。
        "TimeOffsetMs": 0,
        // 当 `Type` 为 `offset` 时,在`TimeOffsetMs` 和 `TimeOffsetMsStr` 之间二选一。
        // 指定截图时间为使用模板参数动态下发的方式,取值固定为`${snapshot_time}`。
        "TimeOffsetMsStr": "${snapshot_time}",
      }, 
      // 仅当指定输出格式为动图时,配置有效。
      // 视频转动图配置。
      "Animation" : {
        // 动图起始时间戳,单位为 ms。
        "StartTime": 6,
        // 动图时长,单位为 ms。
        "Duration": 1000,
        // 抽帧策略,取值如下所示:
        // <li> `fps`:抽帧频率,1 秒 X 帧。 </li>
        // <li> `spf`:抽帧间隔,X 秒 1 帧。 </li>
        // <li> `key`:抽取关键帧。 </li>
        "SelectFrameMode": "fps",
        // 帧率,1 秒 X 帧。仅当`SelectFrameMode`取值为`fps`时需要配置。
        "FramePerSecond": 10,
        // 秒数,X 秒 1 帧。仅当`SelectFrameMode`取值为`spf`时需要配置。
        "SecondPerFrame": 1,
        // 同步等待时长,单位为 s,超时未完成则根据`DemotionType`降级。
        "WaitTime": 5,
        // 降级类型,取值如下所示:
        // <li> `image`:抽取一帧降级返回  </li>
        // <li> `video`:直接返回原视频降级 </li>
        "DemotionType": "vedio",
      }, 
      // 仅当指定输出格式为静图时,配置有效。
      // 动图截帧配置。
      "AnimExtract" : {
        // 动图截帧策略,取值如下所示:
        // <li> `0`:智能模式,从动图首帧开始逐帧检测当前帧亮度是否大于 80,并最终返回第一个亮度大于 80 的帧。 </li>
        // <li> `1`:全局最优,从动图首帧开始逐帧检测并返回亮度最大的一帧。 </li>
        "Strategy": 0,
        // 动图异步处理超时时间,单位为 ms。默认为 1500,取值负数时表示无超时时间。若在指定时间范围内处理未完成则返回失败。
        "Timeout": 1500,
      }, 
    }

      const res = await imagexService.CreateImageTemplate(requestParam);
      console.log('res',res)
    } catch (err) {
      console.error(err);
    }
  }
    

删除图片模板

您可以调用 DeleteImageTemplate 接口删除图片模板。详细的参数说明可参见 DeleteImageTemplate 接口文档。

接口调用示例如下所示。

import { imagex } from "@volcengine/openapi";
  
  export async function DeleteImageTemplateDemo () {
    try {
      const imagexService = new imagex.ImagexService({
        // 强烈建议不要把 AccessKey ID 和 AccessKey Secret 保存到工程代码里,否则可能导致 AccessKey 泄露,威胁您账号下所有资源的安全。
        accessKeyId: process.env.VOLC_ACCESSKEY,
        // 本示例通过从环境变量中读取 AccessKey ID 和 AccessKey Secret,来实现 API 访问的身份验证。运行代码示例前,请配置环境变量 VOLC_ACCESSKEY 和 VOLC_SECRETKEY
        secretKey: process.env.VOLC_SECRETKEY,
      });
      const requestParam = {
      // imagex服务ID
      "ServiceId": "8h**9q",
      // 待删除模板名称,最大限制为 100。
      // note:
      // 您可以通过调用[获取服务下所有图片模板](https://www.volcengine.com/docs/508/9386)获取所需的模板名称。
      "TemplateNames" : ["TemplateName1","TemplateName2"], 
    }

      const res = await imagexService.DeleteImageTemplate(requestParam);
      console.log('res',res)
    } catch (err) {
      console.error(err);
    }
  }
    

获取单个图片模板

您可以调用 GetImageTemplate 接口获取单个图片模板。详细的参数说明可参见 GetImageTemplate 接口文档。

接口调用示例如下所示。

import { imagex } from "@volcengine/openapi";
  
  export async function GetImageTemplateDemo () {
    try {
      const imagexService = new imagex.ImagexService({
        // 强烈建议不要把 AccessKey ID 和 AccessKey Secret 保存到工程代码里,否则可能导致 AccessKey 泄露,威胁您账号下所有资源的安全。
        accessKeyId: process.env.VOLC_ACCESSKEY,
        // 本示例通过从环境变量中读取 AccessKey ID 和 AccessKey Secret,来实现 API 访问的身份验证。运行代码示例前,请配置环境变量 VOLC_ACCESSKEY 和 VOLC_SECRETKEY
        secretKey: process.env.VOLC_SECRETKEY,
      });
      const requestParam = {
      // 服务 ID。
      // <li> 您可以在 veImageX 控制台 [服务管理](https://console.volcengine.com/imagex/service_manage/)页面,在创建好的图片服务中获取服务 ID。 </li>
      // <li> 您也可以通过 OpenAPI 的方式获取服务 ID,具体请参考[获取所有服务信息](https://www.volcengine.com/docs/508/9360)。 </li>
      "ServiceId": "8h**9q",
      // 模板名称。
      // * 您可以通过调用[获取服务下所有模板](https://www.volcengine.com/docs/508/9386)获取所需的模板名称。
      "TemplateName": "TemplateName1",
    }

      const res = await imagexService.GetImageTemplate(requestParam);
      console.log('res',res)
    } catch (err) {
      console.error(err);
    }
  }
    

获取服务下所有图片模版

您可以调用 GetAllImageTemplates 接口获取服务下所有图片模版。详细的参数说明可参见 GetAllImageTemplates 接口文档。

接口调用示例如下所示。

import { imagex } from "@volcengine/openapi";
  
  export async function GetAllImageTemplatesDemo () {
    try {
      const imagexService = new imagex.ImagexService({
        // 强烈建议不要把 AccessKey ID 和 AccessKey Secret 保存到工程代码里,否则可能导致 AccessKey 泄露,威胁您账号下所有资源的安全。
        accessKeyId: process.env.VOLC_ACCESSKEY,
        // 本示例通过从环境变量中读取 AccessKey ID 和 AccessKey Secret,来实现 API 访问的身份验证。运行代码示例前,请配置环境变量 VOLC_ACCESSKEY 和 VOLC_SECRETKEY
        secretKey: process.env.VOLC_SECRETKEY,
      });
      const requestParam = {
      // 服务ID
      // <li> 您可以在 veImageX 控制台 [服务管理](https://console.volcengine.com/imagex/service_manage/)页面,在创建好的图片服务中获取服务 ID。 </li>
      // <li> 您也可以通过 OpenAPI 的方式获取服务 ID,具体请参考[获取所有服务信息](https://www.volcengine.com/docs/508/9360)。 </li>
      "ServiceId": "8h**9q",
      // 支持的字符正则集合为[a-zA-Z0-9_-]。指定时返回模板名称包含该字符串的图片模板,不填或者为空则返回所有模板。
      "TemplateNamePattern": "pic",
      // 分页偏移量,默认 0。取值为 1 时,表示跳过第一条数据,从第二条数据取值。
      "Offset": 0,
      // 分页获取条数,默认 10。
      "Limit": 10,
      // 是否按照模板创建时间升序查询,默认为`false`。
      // * 取值为`true`时,表示按升序查询。
      // * 取值为`false`时,表示降序查询。
      "Asc": "true",
    }

      const res = await imagexService.GetAllImageTemplates(requestParam);
      console.log('res',res)
    } catch (err) {
      console.error(err);
    }
  }
    

删除回收站模板

您可以调用 DeleteTemplatesFromBin 接口删除回收站模板。详细的参数说明可参见 DeleteTemplatesFromBin 接口文档。

接口调用示例如下所示。

import { imagex } from "@volcengine/openapi";
  
  export async function DeleteTemplatesFromBinDemo () {
    try {
      const imagexService = new imagex.ImagexService({
        // 强烈建议不要把 AccessKey ID 和 AccessKey Secret 保存到工程代码里,否则可能导致 AccessKey 泄露,威胁您账号下所有资源的安全。
        accessKeyId: process.env.VOLC_ACCESSKEY,
        // 本示例通过从环境变量中读取 AccessKey ID 和 AccessKey Secret,来实现 API 访问的身份验证。运行代码示例前,请配置环境变量 VOLC_ACCESSKEY 和 VOLC_SECRETKEY
        secretKey: process.env.VOLC_SECRETKEY,
      });
      const requestParam = {
      // 服务 ID。
      // <li> 您可以在 veImageX 控制台 [服务管理](https://console.volcengine.com/imagex/service_manage/)页面,在创建好的图片服务中获取服务 ID。 </li>
      // <li> 您也可以通过 OpenAPI 的方式获取服务 ID,具体请参考[获取所有服务信息](https://www.volcengine.com/docs/508/9360)。 </li>
      "ServiceId": "8h**9q",
      // 待删除模板名称。
      // note:
      // 您可以通过调用[获取回收站中所有模板](https://www.volcengine.com/docs/508/132241)获取所需的模板名称。
      "TemplateNames" : ["TemplateName1","TemplateName2"], 
    }

      const res = await imagexService.DeleteTemplatesFromBin(requestParam);
      console.log('res',res)
    } catch (err) {
      console.error(err);
    }
  }
    

恢复回收站模板

您可以调用 CreateTemplatesFromBin 接口恢复回收站模板。详细的参数说明可参见 CreateTemplatesFromBin 接口文档。

接口调用示例如下所示。

import { imagex } from "@volcengine/openapi";
  
  export async function CreateTemplatesFromBinDemo () {
    try {
      const imagexService = new imagex.ImagexService({
        // 强烈建议不要把 AccessKey ID 和 AccessKey Secret 保存到工程代码里,否则可能导致 AccessKey 泄露,威胁您账号下所有资源的安全。
        accessKeyId: process.env.VOLC_ACCESSKEY,
        // 本示例通过从环境变量中读取 AccessKey ID 和 AccessKey Secret,来实现 API 访问的身份验证。运行代码示例前,请配置环境变量 VOLC_ACCESSKEY 和 VOLC_SECRETKEY
        secretKey: process.env.VOLC_SECRETKEY,
      });
      const requestParam = {
      // 服务 ID。
      // <li> 您可以在 veImageX 控制台 [服务管理](https://console.volcengine.com/imagex/service_manage/)页面,在创建好的图片服务中获取服务 ID。 </li>
      // <li> 您也可以通过 OpenAPI 的方式获取服务 ID,具体请参考[获取所有服务信息](https://www.volcengine.com/docs/508/9360)。 </li>
      "ServiceId": "8h**9q",
      // 待恢复模板名称。
      // note:
      // 您可以通过调用[获取回收站中所有模板](https://www.volcengine.com/docs/508/132241)获取所需的模板名称。
      "TemplateNames" : ["TemplateName1","TemplateName2"], 
    }

      const res = await imagexService.CreateTemplatesFromBin(requestParam);
      console.log('res',res)
    } catch (err) {
      console.error(err);
    }
  }
    

获取回收站中所有模板

您可以调用 GetTemplatesFromBin 接口获取回收站中所有模板。详细的参数说明可参见 GetTemplatesFromBin 接口文档。

接口调用示例如下所示。

import { imagex } from "@volcengine/openapi";
  
  export async function GetTemplatesFromBinDemo () {
    try {
      const imagexService = new imagex.ImagexService({
        // 强烈建议不要把 AccessKey ID 和 AccessKey Secret 保存到工程代码里,否则可能导致 AccessKey 泄露,威胁您账号下所有资源的安全。
        accessKeyId: process.env.VOLC_ACCESSKEY,
        // 本示例通过从环境变量中读取 AccessKey ID 和 AccessKey Secret,来实现 API 访问的身份验证。运行代码示例前,请配置环境变量 VOLC_ACCESSKEY 和 VOLC_SECRETKEY
        secretKey: process.env.VOLC_SECRETKEY,
      });
      const requestParam = {
      // 服务 ID
      // <li> 您可以在 veImageX 控制台 [服务管理](https://console.volcengine.com/imagex/service_manage/)页面,在创建好的图片服务中获取服务 ID。 </li>
      // <li> 您也可以通过 OpenAPI 的方式获取服务 ID,具体请参考[获取所有服务信息](https://www.volcengine.com/docs/508/9360)。 </li>
      "ServiceId": "8h**9q",
      // 仅返回模板名称包含该字符串的图片模板,不填或者为空则返回所有模板。
      "TemplateNamePattern": "pic",
      // 分页偏移。默认 0。取值为1,表示跳过第一条数据,从第二条数据开始取值。
      "Offset": 0,
      // 分页获取条数,默认 10。
      "Limit": 10,
      // 是否按照模板创建时间升序查询,支持取值:`true、false`,默认为`false`。
      "Asc": "true",
    }

      const res = await imagexService.GetTemplatesFromBin(requestParam);
      console.log('res',res)
    } catch (err) {
      console.error(err);
    }
  }