文档中心

获取文件上传地址和凭证

最近更新时间：2024.01.31 15:19:58

首次发布时间：2021.02.23 10:42:24

本接口用于指定上传文件信息，并获取文件上传地址和凭证。成功获取到上传地址和凭证后，使用公网域名上传您指定的文件二进制数据，对返回的上传地址发起 PUT 请求上传文件。（可选操作：通过调用 CommitImageUpload 接口，确认文件上传并获取上报上传结果。）

推荐您使用服务端 SDK 进行文件上传，具体上传流程请参考服务端上传。

说明

强烈不建议您依赖 CommitImageUpload 返回的图片 meta 信息，有获取 meta 需求推荐在上传完成后拼接~info模板获取图片 meta 信息。原因请见为什么不建议依赖 Commit 阶段返回的图片 meta 信息？

注意事项

请求频率：单用户请求频率限制为 100 次/秒。
超时时间：超时时间约 5 秒。

请求说明

请求方式：GET
接口地址示例：https://imagex.volcengineapi.com/?Action=ApplyImageUpload&Version=2018-08-01

说明

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

请求参数

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

Query

参数	类型	是否必选	示例值	描述
Action	String	是	`ApplyImageUpload`	接口名称。veImageX 当前 API 的名称为 `ApplyImageUpload`。
Version	String	是	`2018-08-01`	接口版本。veImageX 当前 API 的版本为 `2018-08-01`。
ServiceId	String	是	`WMK**UXe`	服务 ID。您可以在 veImageX 控制台服务管理页面，在创建好的图片服务中获取服务 ID。您也可以通过 OpenAPI 的方式获取服务 ID，具体请参考获取所有服务信息。
SessionKey	String	否	`eyJh**In0=`	一次上传会话 Key。说明本接口上一次请求的`SessionKey`，可在重试时带上，作为服务端的再次选路时的一个参考。
UploadNum	Integer	否	`1`	上传文件的数量，将决定下发的 StoreUri 的数量，取值范围为[1,10]，默认为 1。
StoreKeys	Array of String	否	`312**ea6.png`	上传文件的存储 Key。默认使用随机生成的字符串作为存储 Key。数组长度和`UploadNum`保持一致。不支持空格，如果中间有空格将会导致上传失败。不支持以/开头或结尾，不支持/连续出现，Key 值最大长度限制为 180 个字节。说明仅对于 veImageX 上传场景生效。
Prefix	String	否	`a/b`	指定的上传文件路径。指定`Prefix`时，下发的存储 Key 为：`Prefix/{随机Key}{FileExtension}`，其中`Prefix + FileExtension`最大长度限制为 145 个字节。不支持以/开头或结尾，不支持/连续出现。说明仅当未指定`StoreKeys`时生效。
FileExtension	String	否	`png`	文件扩展名(如：.java, .txt, .go 等)，最大长度限制为 8 个字节。说明仅当未指定`StoreKeys`时生效。
Overwrite	Boolean	否	`false`	是否开启重名文件覆盖上传，取值如下所示： `true`：开启 `false`：（默认）关闭注意在指定 `Overwrite` 为 `true` 前，请确保您指定的 `ServiceId` 对应服务已开启了覆盖上传能力。

返回参数

参数	类型	示例值	描述
UploadAddress	Array of UploadAddress		上传地址
RequestId	String	`20221110162951010212162157127244C2`	请求的唯一标识 ID。

UploadAddress

参数	类型	示例值	描述
StoreInfos	Array of StoreInfos		上传 Uri 说明数量由请求参数中的`UploadNum`决定。
UploadHosts	Array of String	`tos.test.com`	上传域名列表，可以用于客户端容灾，并行上传等。
SessionKey	String	`eyJh**In0=`	一次上传会话 Key。上传完成上报时使用该值，该 Key 可以在解码后提取信息及参数校验。

StoreInfos

参数	类型	示例值	描述
StoreUri	String	`tos-cn-i-mmw2/31a6.png`	资源 ID。
Auth	String	`6FJL:-fUzI=:Mz**5n`	上传凭证。

示例

请求示例

GET https://imagex.volcengineapi.com/?Action=ApplyImageUpload&Version=2018-08-01&ServiceId=WMK**UXe&StoreKeys=312**ea6.png

返回示例

{
    "ResponseMetadata": {
        "RequestId": "202307241740314A9411E1E466F1684AB7",
        "Action": "ApplyImageUpload",
        "Version": "2018-08-01",
        "Service": "imagex",
        "Region": "cn-north-1"
    },
    "Result": {
        "UploadAddress": {
            "StoreInfos": [
                {
                    "StoreUri": "tos-i-mm**w2/31**a6.png",
                    "Auth": "6F**JL:-fU**zI=:Mz**5n"
                }
            ],
            "UploadHosts": [
                "upload-test.net"
            ],
            "SessionKey": "eyJh**In0="
        },
        "RequestId": "202307241740314A9411E1E466F1684AB7",
        "SDKParam": null
    }
}

错误码

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

服务端 SDK

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