创建多文件压缩异步任务--veImageX-火山引擎

文档中心

立即注册

导航

创建多文件压缩异步任务

最近更新时间：2025.07.28 16:13:16首次发布时间：2023.07.14 14:45:08

本接口支持将指定的若干文件进行压缩并打包为 ZIP 包，并将结果上传至指定服务。同时，在打包的过程中，支持对各文件重命名，以及自定义压缩规则与压缩包名称。

使用说明

本接口支持以下两种待压缩文件的提交方式：

方式 1：FlieList 方式：需配置待压缩文件的公网访问 URL 与 Alias，Folder 配置，文件不得超过 3000 个。
方式 2：IndexFile 方式：在 .txt 文件（索引文件）内填写待压缩文件相关配置，每行需填写 StoreUri/URL,Alias,Folder相关配置，并将该索引文件上传至指定的 veImageX 存储服务，并获取索引文件在该服务的 StoreUri。
索引文件内支持填写的文件地址有以下两种类型，但单个索引文件内的文件地址类型需要保持一致，不支持混用。
1. 填写待压缩文件的公网访问 URL，veImageX 将按序依次下载公网文件。您可下载 Compress_StoreUri.txt 参考示例，完成 URL 类型索引文件的填写。
  Compress_URL.txt
  110.00Bytes
2. 【推荐】填写待压缩文件的 StoreUri，您需要提前将该文件上传至指定的 veImageX 存储服务。您可下载 Compress_StoreUri.txt 参考示例，完成 StoreUri 类型索引文件的填写。
  Compress_StoreUri.txt
  100.00Bytes

注意

如果待压缩文件的地址为公网 URL 类型，那么 veImageX 将在解析到文件地址后，依次去公网下载文件。如果提交的这批文件的原始总大小超过了 45000MB，那么当下载量达到 45000MB 时，接口会提示该压缩任务失败，但此时已产生对应 45000MB 文件的公网流出费用。

由于 veImageX 对于公网下载文件的缓存时间为 30 个自然日，那么您可在任务失败后的 30 天内重新创建已缓存文件的压缩任务，期间不再重复收费。

注意事项

计费说明：多文件压缩功能属于附加组件下其他增值模块，属于后付费计费，使用后会产生增值服务费用。
前提条件：请在 veImageX 控制台提前开通多文件压缩组件。
使用限制：使用组件前，请先确认多文件压缩使用限制。详见火山引擎控制台的组件市场 > 附加组件 > 其他增值 > 多文件压缩处理 > 组件介绍页面右侧的使用限制。
请求频率：单用户请求频率限制为 10 次/秒。
服务地址：veImageX 在全球多个区域部署，每个区域有自己对应的 OpenAPI 域名，不支持跨区域调用。详情参见服务地址。

请求说明

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

请求参数

下表仅列出该接口特有的请求参数和部分公共参数。更多信息请见公共请求参数。

Query

参数类型是否必选示例值描述

Action String 是 CreateImageCompressTask 接口名称。当前 API 的名称为 CreateImageCompressTask。

Version String 是 2018-08-01 接口版本。当前 API 的版本为 2018-08-01。

参数	类型	是否必选	示例值	描述
Action	String	是	`CreateImageCompressTask`	接口名称。当前 API 的名称为 `CreateImageCompressTask`。
Version	String	是	`2018-08-01`	接口版本。当前 API 的版本为 `2018-08-01`。
ServiceId	String	是	`7g**2i`	压缩文件存储的目标服务 ID。您可以在 veImageX 控制台服务管理页面，在创建好的图片服务中获取服务 ID。您也可以通过 OpenAPI 的方式获取服务 ID，具体请参考获取所有服务信息。

ServiceId

String

是

7g**2i

压缩文件存储的目标服务 ID。

您可以在 veImageX 控制台服务管理页面，在创建好的图片服务中获取服务 ID。
您也可以通过 OpenAPI 的方式获取服务 ID，具体请参考获取所有服务信息。

Body

参数	类型	是否必选	示例值	描述
FileList	Array of FileList	否	`-`	与`IndexFile`为二选一，必填。压缩文件列表配置，最多可支持 3000 个文件，压缩前文件的总大小不得超过 45000 MB。若超出限制，则取消压缩打包操作，致使打包任务失败。
IndexFile	String	否	`tos-boe-i-hr***pr/testcompress.txt`	与 `FileList`为二选一，必填。索引文件的 StoreUri，为 .txt 文件，该索引文件需上传至指定服务对应存储中。该索引文件内需填写待压缩文件的地址，每行填写一个，最多可填写 3000 行。压缩前文件的总大小不超过 45000 MB。若超出限制，则取消压缩打包操作，致使打包任务失败。
Output	String	否	`testcompress`	压缩后文件压缩包的指定名称，默认为随机 Key。
ZipMode	Integer	是	`0`	文件的处理方式，取值如下所示： `0`：使用 ZIP DEFLATE 压缩方法，将文件进行压缩并打包为 ZIP 包。该方式适用于需要长期存储大量未经压缩的文件的场景，以节省存储空间。但需注意的是，若文件本身已经过压缩处理，将会因为文件的可压缩空间有限，导致该方式的压缩效果不明显。 `1`：仅将文件打包为 ZIP 包，但不执行压缩操作。该方式适用于快速整理文件而无需节省存储空间的场景。例如已经过压缩的文件的打包存储，以便于传输或归档。
Callback	String	否	`http://test.com`	POST 类型的回调 URL，用于接收相关回调 JSON 类型数据。回调参数请参考回调内容。

FileList

参数类型是否必选示例值描述

Url String 是 http://test.imagex.com/tos-cn-i-rw****qr/86****4c.png~tplv-rw***qr-6.image 公网可访问的待压缩文件 URL

参数	类型	是否必选	示例值	描述
Url	String	是	`http://test.imagex.com/tos-cn-i-rw**qr/864c.png~tplv-rw*qr-6.image`	公网可访问的待压缩文件 URL
Alias	String	否	`compress1`	指定时，为 URL 文件所在压缩包中的别名。输入规则如下所示：支持汉字、字母、数字及符号`-`、`_`和`.`；不能以`-`、`_`和`.`开头；长度不得超过 100 个字符。不指定时，若能提取原文件名称时，则以 URL 原文件名称；否则，使用随机名称。
Folder	String	否	`a/b`	指定源文件在压缩包中的文件夹，不传时则将该资源存储至一级目录下。输入规则如下所示：支持汉字、字母、数字及符号`-`、`_`和`.`；不能以`-`、`_`和`.`开头；不能以`/`结尾。注意建议命名长度不超过 256 个字节。 -建议您在命名中仅使用 `-`、`_` 和 `.` 这三种符号。如果您使用了其他符号，可能因操作系统不支持导致处理异常。

Alias

String

否

compress1

指定时，为 URL 文件所在压缩包中的别名。输入规则如下所示：
- 支持汉字、字母、数字及符号-、_和.；
- 不能以-、_和.开头；
- 长度不得超过 100 个字符。
不指定时，若能提取原文件名称时，则以 URL 原文件名称；否则，使用随机名称。

Folder

String

否

a/b

指定源文件在压缩包中的文件夹，不传时则将该资源存储至一级目录下。输入规则如下所示：

支持汉字、字母、数字及符号-、_和.；
不能以-、_和.开头；
不能以/结尾。

注意

建议命名长度不超过 256 个字节。
-建议您在命名中仅使用 -、_ 和 . 这三种符号。如果您使用了其他符号，可能因操作系统不支持导致处理异常。

返回参数

下表仅列出本接口特有的返回参数。更多信息请见公共返回参数。

参数	类型	示例值	描述
TaskId	String	`82370***12102`	压缩任务 ID

请求示例

POST https://imagex.volcengineapi.com/?Action=CreateImageCompressTask&Version=2018-08-01&ServiceId=7g**2i
{
    "FileList": [
        {
            "Url": "http://test.imagex.com/tos-cn-i-rw****qr/86****4c.png~tplv-rw***qr-6.image",
            "Alias": "compress1",
            "Folder": ""
        },
        {
            "Url": "http://test.imagex.com/tos-cn-i-rw****qr/90****5j.png~tplv-rw***qr-1.image",
            "Alias": "compress2",
            "Folder": "a/b"
        }
    ],
    "Output": "compress_test",
    "ZipMode": 0,
    "Callback": "http://test.com"
}

返回示例

{
    "ResponseMetadata": {
        "RequestId": "202306041104200100100232280022D31",
        "Action": "CreateImageCompressTask",
        "Version": "2018-08-01",
        "Service": "imagex",
        "Region": "cn-north-1"
    },
    "Result": {
        "TaskId": "82370***12102"
    }
}

错误码

访问公共错误码和 veImageX 错误码获取详细信息。

服务端 SDK

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

回调内容

参数名称	参数类型	参数描述
TaskId	String	异步压缩任务 ID
Status	String	任务状态，取值如下所示： `Failed`：压缩失败 `Success`：压缩成功
OutputUri	String	压缩包 StoreUri。
Err	String	错误信息。仅当`Status`为`Failed`时，该值不为空。
Code	Integer	错误码。仅当`Status`为`Failed`时，该值不为 0。
StartTime	int 64	创建开始时间，unix 时间，单位为纳秒。
EndTime	int 64	创建结束时间，unix 时间，单位为纳秒。
TimeCost	int 64	打包耗时时间，unix 时间，单位为毫秒。
ErrUrls	Array of String	打包失败的 URL/Uri 列表。

回调示例如下所示。

{
	"TaskId": "82370***12102",
	"Status": "Failed",
	"OutputUri": "tos-cn-i-hr***pr/testcompress.txt",
	"Err": "压缩失败",
	"Code": 604026,
	"StartTime": 1641027296000000000,
	"EndTime": 1641037921000000000,
	"TimeCost": 1200000,
	"ErrUrls": {
		"tos-cn-i-hr***pr/1.png",
		"tos-cn-i-hr***pr/test.jpg"
	}
}