获取结果图 URI--veImageX-火山引擎

文档中心

立即注册

导航

veImageX

获取结果图 URI

最近更新时间：2024.09.03 16:47:46首次发布时间：2022.03.31 19:17:43

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

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

使用限制

请求频率限制：5 次/秒
超时时间：10 秒
服务地址：仅支持使用国内对应的 OpenAPI 域名，具体请见请求地址。

请求说明

接口名称：GetImageStyleResult
请求方式：POST
请求地址：https://imagex.volcengineapi.com/?Action=GetImageStyleResult&Version=2018-08-01

请求参数

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

Query

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

Body

参数	类型	是否必选	描述
StyleId	String	是	图片渲染所用样式的样式 ID。获取方法请参见如何获取样式 ID。
Params	JSON Map	否	样式中的动态要素和要素取值。格式为 `"Key":"Value"`，例如，`"el17fbb3a2134*":"Hello,World",` Key：表示要素 ID，String 类型。获取方式请参见如何获取要素 ID； Value：表示要素的取值，String 类型。需要您根据实际需求自定义，例如，自定义图片地址、文本及二维码等内容。
background	JSON Object	否	样式背景，结构请参考样式定义。此参数不为空则使用自定义参数内容替换样式定义中的 background 属性值。
elements	JSON Array	否	要素属性，结构请参考样式定义。此参数不为空则使用自定义参数内容替换样式定义中对应 elements 的相关属性值。说明要素类型不允许更改；若`elements`和`params`两个参数同时指定了某个要素的内容，则以`elements`中指定的为准。
OutputFormat	String	否	渲染结果图的编码格式，默认值为 webp。取值如下所示： jpeg webp png heic
OutputQuality	Integer	否	渲染结果图的编码质量。默认为 75，取值范围为 [1,100]，值越大，结果图的质量越高。

返回参数

参数	类型	描述
ResUri	String	渲染结果图的 URI。您可使用结果图 URI（即 `ResUri`）拼接完整访问 URL 后，在浏览器查看渲染效果。
RenderDetail	Array of RanderDetail	渲染详情

RanderDetail

参数	类型	描述
Element	String	渲染失败的要素 ID
ErrMsg	String	渲染失败的原因

示例

请求示例

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，参考文档如下所示：