模板管理--veImageX-火山引擎

文档中心

立即注册

导航

模板管理

最近更新时间：2024.08.12 16:27:03首次发布时间：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({
      // 强烈建议不要把 VOLC_ACCESSKEY 和 VOLC_SECRETKEY 保存到工程代码里，否则可能导致 AccessKey 泄露，威胁您账号下所有资源的安全。
      // 本示例通过从环境变量中读取 VOLC_ACCESSKEY 和 VOLC_SECRETKEY，来实现 API 访问的身份验证。运行代码示例前，请配置环境变量 VOLC_ACCESSKEY 和 VOLC_SECRETKEY
      accessKeyId: process.env.VOLC_ACCESSKEY,
      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.size.fixed": "10000",
        "jpeg.size.fixed.padding": "append",
        "heic.aq.mode": "1",
        "heic.quality.adapt.pixlimit": "1000000",
        "heic.quality.adapt.version": "3",
        "jpeg.alpha.demotion": "png",
        "jpeg.quality.adapt.pixlimit": "1000000",
        "jpeg.quality.adapt.version": "3",
        "webp.quality.adapt.pixlimit": "1000000",
        "webp.quality.adapt.version": "3",
      },
      // 指定图像自适应配置。
      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({
      // 强烈建议不要把 VOLC_ACCESSKEY 和 VOLC_SECRETKEY 保存到工程代码里，否则可能导致 AccessKey 泄露，威胁您账号下所有资源的安全。
      // 本示例通过从环境变量中读取 VOLC_ACCESSKEY 和 VOLC_SECRETKEY，来实现 API 访问的身份验证。运行代码示例前，请配置环境变量 VOLC_ACCESSKEY 和 VOLC_SECRETKEY
      accessKeyId: process.env.VOLC_ACCESSKEY,
      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({
      // 强烈建议不要把 VOLC_ACCESSKEY 和 VOLC_SECRETKEY 保存到工程代码里，否则可能导致 AccessKey 泄露，威胁您账号下所有资源的安全。
      // 本示例通过从环境变量中读取 VOLC_ACCESSKEY 和 VOLC_SECRETKEY，来实现 API 访问的身份验证。运行代码示例前，请配置环境变量 VOLC_ACCESSKEY 和 VOLC_SECRETKEY
      accessKeyId: process.env.VOLC_ACCESSKEY,
      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({
      // 强烈建议不要把 VOLC_ACCESSKEY 和 VOLC_SECRETKEY 保存到工程代码里，否则可能导致 AccessKey 泄露，威胁您账号下所有资源的安全。
      // 本示例通过从环境变量中读取 VOLC_ACCESSKEY 和 VOLC_SECRETKEY，来实现 API 访问的身份验证。运行代码示例前，请配置环境变量 VOLC_ACCESSKEY 和 VOLC_SECRETKEY
      accessKeyId: process.env.VOLC_ACCESSKEY,
      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({
      // 强烈建议不要把 VOLC_ACCESSKEY 和 VOLC_SECRETKEY 保存到工程代码里，否则可能导致 AccessKey 泄露，威胁您账号下所有资源的安全。
      // 本示例通过从环境变量中读取 VOLC_ACCESSKEY 和 VOLC_SECRETKEY，来实现 API 访问的身份验证。运行代码示例前，请配置环境变量 VOLC_ACCESSKEY 和 VOLC_SECRETKEY
      accessKeyId: process.env.VOLC_ACCESSKEY,
      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({
      // 强烈建议不要把 VOLC_ACCESSKEY 和 VOLC_SECRETKEY 保存到工程代码里，否则可能导致 AccessKey 泄露，威胁您账号下所有资源的安全。
      // 本示例通过从环境变量中读取 VOLC_ACCESSKEY 和 VOLC_SECRETKEY，来实现 API 访问的身份验证。运行代码示例前，请配置环境变量 VOLC_ACCESSKEY 和 VOLC_SECRETKEY
      accessKeyId: process.env.VOLC_ACCESSKEY,
      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({
      // 强烈建议不要把 VOLC_ACCESSKEY 和 VOLC_SECRETKEY 保存到工程代码里，否则可能导致 AccessKey 泄露，威胁您账号下所有资源的安全。
      // 本示例通过从环境变量中读取 VOLC_ACCESSKEY 和 VOLC_SECRETKEY，来实现 API 访问的身份验证。运行代码示例前，请配置环境变量 VOLC_ACCESSKEY 和 VOLC_SECRETKEY
      accessKeyId: process.env.VOLC_ACCESSKEY,
      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);
  }
}