调用方式--图像技术-火山引擎

文档中心

导航

调用方式

最近更新时间：2024.09.23 18:03:08首次发布时间：2022.07.21 16:20:22

接口简介

图片裁剪服务，接受一张图片以及裁剪的目标宽度和高度，自动选择图片的裁剪区域，保留重要内容，返回裁剪后的图片和裁剪的检测框。

限制条件

名称	内容
图片要求	图片格式：JPG、JPEG、PNG、BMP等常见格式，建议使用JPG格式。图片文件大小：最大 5 MB。

请求说明

名称	内容
接口地址	https://visual.volcengineapi.com
请求方式	POST
Content-Type	`application/x-www-form-urlencoded`

请求参数
（1）header请求参数
公共请求参数
以下请求参数列表仅列出了接口请求参数和必要公共参数，完整公共参数列表见公共参数

名称	类型	是否必填	描述
X-Date	String	是	使用UTC时间，精确到秒。请使用格式：`YYYYMMDD'T'HHMMSS'Z'` ，例如：`20201103T104027Z`
Authorization	String	是	HMAC-SHA256：签名方法 -Credential为签名凭证，其中: -AccessKeyId为访问密钥ID，可在访问密钥（Access Key）获取； -ShortDate为请求的短时间，使用UTC时间，精确到日。请使用格式：`YYYYMMDD`，例如：`20180201`； -Region为请求地区，国内一般为为`cn-north-1`； -Service为请求的服务，一般为`cv`； -SignedHeaders为参与签名计算的头部信息，`content-type` 和 `host` 为必选头部； -Signature为签名，可在签名方法获取。注：我们提供了SDK及签名示例供您实现服务快速接入，具体可参考快速接入例如：`HMAC-SHA256 Credential={AccessKeyId}/{ShortDate}/{Region}/{Service}/request, SignedHeaders={SignedHeaders}, Signature={Signature}`
X-Security-Token	String	否	指安全令牌服务（Security Token Service，STS）颁发的临时安全凭证中的SessionToken，使用长期密钥时无需填写该参数。

（2）Query参数
业务请求参数

参数	可选/必选	类型	说明
Action	必选	String	接口名，取值：ImageCut
Version	必选	String	版本号，取值：2020-08-26

（3）Body参数
业务请求参数

参数	可选/必选	类型	说明
`image_base64`	必选（二选一，优先生效）	String	图片Base64编码
`image_url`	必选（二选一）	String	图片文件URL
`width`	必选	`Int`	要求输出图片的宽度
`height`	必选	`Int`	要求输出图片的高度
`cut_method`	必选	`String`	图片裁剪方法

cut_method 裁剪算法，现支持：

gauss_padding_reserve_score：高斯模糊兜底，会根据图片中主体大小进行扩展
fix_size：固定长宽比裁剪，不进行补边
fix_size_pad_cut_text：其他效果同上fix_size，但裁断比较大的文字时，会采用补边策略
~~gauss_padding：高斯模糊兜底~~（已废弃）
gauss_padding_resize：高斯模糊兜底，缩放到需求的长宽值
only_gauss_pad：只进行高斯模糊补边，不进行裁剪
fix_size_color_quantization_when_cut_text：智能裁剪，如果裁断文字，则选择用背景色补边
remove_edge：去除黑边高斯模糊边（width和height填成1，不会实际生效）

输出说明

（1）通用输出参数
通用输出参数具体见通用返回字段及错误码
（2）业务输出参数
data字段说明

字段	类型	说明
`image`	`Image`	裁剪后的图片
`boundingbox`	`BoundingBox`	裁剪框

Image结构说明

字段	类型	说明
`url`	`String`	图片链接
`data`	`String`	图片的base64编码

BoundingBox结构说明

字段	类型	说明
`x_min`	`float`	检测框`x`轴坐标(`0~1`)
`x_max`	`float`	检测框`x`轴坐标(`0~1`)
`y_min`	`float`	检测框`y`轴坐标(`0~1`)
`y_max`	`float`	检测框`y`轴坐标(`0~1`)

（3）输出示例

{
    "status": 10000,
    "code": 10000,
    "time_elapsed": "1.11217161s",
    "request_id": "68970913035200778321605854208",
    "message": "Success",
    "data": {
        "boundingbox": {
            "x_min": 0.43375,
            "y_max": 1,
            "y_min": 0,
            "x_max": 0.9325
        },
        "image": {
            "url": "{图片url}",
            "data": {图片base64编码}
        }
    }
}

错误码

（1）通用错误码
请参考通用返回字段及错误码
（2）业务错误码

HttpCode	错误码	错误消息	描述
200	10000	无	请求成功