You need to enable JavaScript to run this app.
导航
veImageX
  • 文档首页
    • /
  • veImageX

获取结果图 URI

最近更新时间：2024.01.31 15:20:00

首次发布时间：2022.03.31 19:17:43

我的收藏

使用创意魔方中预先创建好的样式 StyleId，定义需要设置的要素与要素的取值 Params，生成结果图，并获取结果图 URI。

  • 调用前，请先在控制台中完成创意魔方样式的创建，并获取图片样式 ID StyleId 、样式中要素 ID Key 与样式所在服务的 ID ServiceId。
  • 调用时，动态传入图片、文字、二维码等要素以及 Header 中的信息，实时渲染合成一张图片，并返回结果图片的 URI。
  • 调用后，请务必在图片服务的基础配置中开启源地址访问后，再使用 veImageX 地址拼接规则查看结果图。

请求说明

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

说明

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

请求参数

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

Query

参数类型是否必选描述
ActionString是接口名称。
VersionString是接口版本。veImageX 当前 API 的版本为 2018-08-01。
ServiceIdString是图片渲染所用样式关联的服务的 ID，用于计量计费和渲染结果的存储。获取方式请参见如何获取调用参数。

Body

参数类型是否必选描述
StyleIdString是图片渲染所用样式的样式 ID。获取方法请参见如何获取样式 ID。

Params

JSON Map

否

样式中的动态要素和要素取值。格式为 "Key":"Value"，例如，"el17fbb3a2134*":"Hello,World",

  • Key：表示要素 ID，String 类型。获取方式请参见如何获取要素 ID；
  • Value：表示要素的取值，String 类型。需要您根据实际需求自定义，例如，自定义图片地址、文本及二维码等内容。
backgroundJSON Object否样式背景，结构请参考样式定义。
此参数不为空则使用自定义参数内容替换样式定义中的 background 属性值。

elements

JSON Array

否

要素属性，结构请参考样式定义。
此参数不为空则使用自定义参数内容替换样式定义中对应 elements 的相关属性值。

说明

  • 要素类型不允许更改；
  • 若elements和params两个参数同时指定了某个要素的内容，则以elements中指定的为准。

OutputFormat

String

否

渲染结果图的编码格式，默认值为 webp。取值如下所示：

  • jpeg
  • webp
  • png
  • heic
OutputQualityInteger否渲染结果图的编码质量。默认为 75，取值范围为 [1,100]，值越大，结果图的质量越高。

返回参数

参数类型描述
ResUriString渲染结果图的 URI
RenderDetailArray of RanderDetail渲染详情

RanderDetail

参数类型描述
ElementString渲染失败的要素 ID
ErrMsgString渲染失败的原因

示例

请求示例

POST https://imagex.volcengineapi.com?Action=GetImageStyleResult&ServiceId=example&Version=2018-08-01
{
    "StyleId": "619b6dec3a997f01e7e263e*",
    "Params": {
        "img1":"tos-cn-i-example/dd*****.png",
        "el17fbb385189*":"HELLO\\nWORLD",
        "el17fbb3a2134*":"Hello,World",
        "el17fbb467e7c*":"https://www.volcengine.com/"
  	}
}

正常返回示例

{
    "ResponseMetadata": {
        "RequestId": "20220322174114010204055149180006F0",
        "Action": "GetImageStyleResult",
        "Version": "2018-08-01",
        "Service": "imagex",
        "Region": "cn-north-1"
    },
    "Result": {
        "ResUri": "tos-cn-i-example/86d0e****",
        "RenderDetail": []
    }
}

异常返回示例

{
    "ResponseMetadata": {
        "RequestId": "202203221744540102080370840B005D1B",
        "Action": "GetImageStyleResult",
        "Version": "2018-08-01",
        "Service": "imagex",
        "Region": "cn-north-1",
        "Error": {
            "CodeN": 100010,
            "Code": "SignatureDoesNotMatch",
            "Message": "The request signature we calculated does not match the signature you provided. Check your Secret Access Key and signing method. Consult the service documentation for details."
        }
    }
}

错误码

访问公共错误码和创意魔方错误码获取详细信息。

服务端 SDK

为了方便您快速开发，veImageX 提供了配套的服务端 SDK，同时支持多种编程语言。建议您使用服务端 SDK 来调用 API，参考文档如下所示：