进阶功能--veImageX-火山引擎

文档中心

veImageX

Flutter 上传 SDK

进阶功能

本文档将为您介绍 veImageX 上传 SDK 的进阶能力。

设置云端储存 key

在文件上传完成后，文件在云端的存储路径形式如下所示：

StoreUri = {{BucketName}}/{{FilePrefix}}{{FileTitle}}{{FileExtension}}

各参数说明如下表所示：

参数	含义	描述
BucketName	存储桶名称	接入方无需手动设置。
FilePrefix	文件前缀	可选，路径字符串，支持多级路径（如 path/to/foo/bar/）
FileTitle	文件标题	可选，如果不手动设置，SDK 会自动生成 32 位字符串作为文件名。
FileExtension	文件后缀	可选。

具体操作代码示例如下所示：

ImageXUploaderOptions options = ImageXUploaderOptions(
    ...
    // 云端的存储路径：tos-cn-xxxx/testPrefix/test0.jpg
    // 为文件设置 storeKey
    storeKeys: storeKeys: ["testPrefix/test0.jpg"],
    ...
)

例如： tos-cn-xxxx/testPrefix/test0.jpg ，对应关系如下表所示：

字段	含义	说明
tos-cn-xxxx/	存储桶名称	接入方无需手动设置。
testPrefix/	文件前缀	可选。
test0	文件名	可选。若不手动设置，SDK 将自动生成一个 32 位字符串作为文件名。
.jpg	文件后缀	可选。

设置重名文件覆盖上传

注意

重名文件：文件存储 key 相同
开启重名覆盖上传功能会存在较高的数据安全风险，建议非必要不开启。如需开启建议您在客户端上传 STS 中限制上传文件 Storekey 的格式，以免您的存储资源受到污染。
开启前，请确保您的上传 STS 签名已添加重名覆盖上传的标识。

您可以通过开启重名覆盖上传，使新上传文件在上传路径及文件名重复时覆盖同名旧文件。若不开启，则新文件上传失败。具体使用步骤如下所示：

参考配置重名覆盖上传在 veImageX 控制台打开重名覆盖上传的功能开关。
在组件内开启覆盖上传，代码示例如下所示：

ImageXUploaderOptions options = ImageXUploaderOptions(
    ...
);
BDImageXUploader uploader = await initImageXUploader(options);

// 开启覆盖
await uploader.setEnableOverwrite(true);

设置加密上传

您可通过在 SDK 开启加密上传并使用 AES Key （自定义或 SDK 随机生成）加密原始上传文件。使用非对称公钥 RSA Public Key 加密 AES Key ， AES Key 加密上传文件。加密完成后 SDK 上传加密数据至 veImageX 服务。上传 SDK 将 veImageX 返回的上传成功的文件 URI 及 meta 信息回调给业务 APP。具体代码示例如下所示：

注意

您需要对 AES Key 的完整性和正确性负责，因您维护不当导致 AES Key 用错或丢失，从而导致加密数据无法解密所引起的一切损失和后果均由您自行承担。

ImageXUploaderOptions options = ImageXUploaderOptions(
    ...
    // 设置 AES key，即对称密钥，用于加密上传文件。支持 SDK 随机生成和自定义
    // 您可以选择不设置，上传 sdk 将自动生成，在上传成功后经回调返回具体内容
    // 如果您需自定义密钥内容，需为 32 位字符串，并经 base64 编码之后传入
    aesKey: "xxxxxx",
);

BDImageXUploader uploader = await initImageXUploader(options);

// 设置是否使用 全链路加密功能  true 使用，默认false
await uploader.setEnableEnd2EndEncryption(true);

// 设置 RSA 公钥, 用于加密对称密钥。请从控制台配置和获取。
// 可选(当上传后不需要 ImageX 服务端进行处理时，可以不填。上传需要 commit上报阶段或者需要返回 meta信息时必填)
// 上传默认获取 meta，可通过 await uploader.setEnableSkipMeta(skipMeta); 关闭获取 meta
await uploader.setPublicKey(publicKey);


// 回调参数新增加密信息 参考上文 BDImageXUploadInfo

设置是否跳过上传成功后的上报阶段

如果您无需在 veImageX 控制台资源管理查看资源列表，建议您跳过资源上传成功后的上报阶段，以提升上传速度，减少上传耗时。

// 设置是否跳过上传成功后的上报阶段，默认值为 true
await uploader.setEnableCommitUpload(false);

如果您无需在上报阶段使 SDK 返回图片 Meta 信息，建议您跳过图片 Meta 信息上报，以提升上传速度。

// 设置是否返回图片 Meta 信息，默认值为 false
await uploader.setEnableSkipMeta(true);

注意

若您需要使用智能审核，请勿跳过资源上传成功后的上报阶段和图片 Meta 信息上报，否则系统将无法触发图片审核。

设置文件的 Content-Type

您可自定义上传文件的 Content-Type，如 gif 图片，指定其 Content-Type 为 image/gif 。您可参考不同格式对应的常见 Content-Type 值。

ImageXUploaderOptions options = ImageXUploaderOptions(
    ...
    specifiedContentType: ["image/png"],
);

设置自定义请求参数

调用 setServerParameter 设置自定义参数，如 appid（应用 ID）、did（设备唯一标识）、uid（用户唯一标识）和 region （地域）等，以便您排查上传日志。参数示例如下所示：

ImageXUploaderOptions options = ImageXUploaderOptions(
    ...
    // 设置自定义请求参数的字符串，例如："appid=123&did=123456&uid=12345&Region=xxx"
    serverParameter: "appid=123&did=123456&uid=12345&Region=xxx",
);

设置 HttpDns 重试

为了避免因遭遇 LOCAL DNS 劫持导致的文件上传失败，您可开启 HttpDns 重试功能，来确保文件能够正常上传。代码示例如下所示：

注意

如果开启了云控，那么云控中默认是开启HttpDns重试功能的，如果不想使用，可以通过云控去关闭。

ImageXUploaderOptions options = ImageXUploaderOptions(
    ...
    // 1. 设置文件的上传重试次数，取值请务必设置为大于或等于 2，默认值为 3。
    fileRetryCount: 2,
);

BDImageXUploader uploader = await initImageXUploader(options);

// 2. 对 uploader 实例开启 httpdns 重试功能
await uploader.setEnableHttpDNS(true);

设置云控

云控指通过控制台参数的配置，对客户端 SDK 进行配置下发，适用于业务需要灵活修改配置参数的场景。控制台配置操作指南参看 SDK 配置下发。
具体使用参考初始化 SDK 中 useImageXCloudControl 字段的使用。

其他配置

上传 SDK 还支持分片上传等功能，您可以设置分片大小、开启并行上传的线程数等能力。具体操作代码示例如下所示：

ImageXUploaderOptions options = ImageXUploaderOptions(
    ...
    // 设置进行分片上传的阈值
    // 单张图片大小 > 阈值则走分片上传，否则走直传，单位 byte，默认值 1G
    sliceThreshold: 2 * 1024 * 1024,
    // 设置单张图片并行上传的线程数，只有走分片上传的情况才生效，默认值 1
    socketNum: 3,
    // 分片上传设置分片大小，单位 byte，默认值 512 * 1024；
    sliceSize: 512 * 1024,
    // 设置并行上传的文件数（上传多张图片的情况），
    // 建议设置的最大并行数，应该是小于等于传入的图片数目。默认值 1
    maxConcurrentFileNum: 2,
    // 单个分片传输超时，单位 s，默认 40
    rwTimeout: 30,
    // 系统 socket 单次读写超时，单位 s，默认 10
    tranTimeout: 15,
    // 分片重试次数，默认值 2
    sliceRetryCount: 3,
    // 文件级别的重试次数，默认值 3
    fileRetryCount: 4,
    
);

最近更新时间：2026.01.06 16:07:36

这个页面对您有帮助吗？

有用

无用

veImageX

设置云端储存 key #

设置重名文件覆盖上传 #

设置加密上传 #

设置是否跳过上传成功后的上报阶段 #

设置文件的 Content-Type #

设置自定义请求参数 #

设置 HttpDns 重试 #

设置云控 #

其他配置 #