获取文件 VPC 内网上传地址--veImageX-火山引擎

文档中心

立即注册

导航

veImageX

获取文件 VPC 内网上传地址

最近更新时间：2025.03.19 11:41:21首次发布时间：2025.03.19 11:41:21

本接口用于指定内网上传文件信息，并获取文件上传链接和 Header 信息。成功获取到上述信息后，按照链接及 Header 进行请求即可完成上传。

注意事项

请求频率：单用户请求频率限制为 100 次/秒。
超时时间：超时时间约 5 秒。
服务地址：veImageX 在全球多个区域部署，每个区域有自己对应的 OpenAPI 域名，不支持跨区域调用。具体详情请查看服务地址。

请求说明

请求方式：GET
请求地址：https://imagex.volcengineapi.com/?Action=ApplyVpcUploadInfo&Version=2023-05-01

请求参数

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

Query

参数	类型	是否必选	示例值	描述
Action	String	是	`ApplyVpcUploadInfo`	接口名称。当前 API 的名称为 `ApplyVpcUploadInfo`。
Version	String	是	`2023-05-01`	接口版本。当前 API 的版本为 `2023-05-01`。
ServiceId	String	是	`u3*k`	服务 ID。您可以在 veImageX 控制台服务管理页面，在创建好的图片服务中获取服务 ID。您也可以通过 OpenAPI 的方式获取服务 ID，具体请参考获取所有服务信息。
StoreKey	String	否	`test.jpg`	上传文件的存储 Key。默认使用随机生成的字符串作为存储 Key。存储 Key 详细命名规范请参看 veImageX 存储 Key 通用字符规则。
Prefix	String	否	`test`	指定的上传文件路径。指定 `Prefix` 时，下发的存储 Key 为：`Prefix/{随机Key}.{FileExtension}`，拼接形成的存储 Key 需满足 veImageX 存储 Key 通用字符规则。说明仅当未指定 `StoreKeys` 时生效。
FileExtension	String	否	`.jpg`	文件扩展名，最大长度限制为 8 个字节。说明仅当未指定 `StoreKeys` 时生效。
ContentType	String	否	`image/jpeg`	上传文件的 Content-Type 值。需确保指定值在服务维度的白名单内，否则无法成功上传，参看上传 Content-Type 限制。
StorageClass	String	否	`ARCHIVE`	存储类型。 `STANDARD`：标准存储 `IA`：低频存储 `ARCHIVE_FR`：归档闪回存储 `ARCHIVE`：归档存储 `COLD_ARCHIVE`：冷归档存储
FileSize	Long	否	`123`	文件大小。
PartSize	Long	否	`5242880`	分片大小，单位为字节，默认值为 200 MB。当 `FileSize` 大于 `PartSize` 时，下发分片上传的 URL。
Overwrite	Boolean	否	`true`	是否开启重名文件覆盖上传，取值如下所示： `true`：开启 `false`：（默认）关闭说明在指定 `Overwrite` 为 `true` 前，请确保您指定的 `ServiceId` 对应服务已开启了覆盖上传能力。

返回参数

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

参数	类型	示例值	描述
SessionKey	String	`eyJh**In0=`	一次上传会话 Key。上传完成上报时使用该值，该 Key 可以在解码后提取信息及参数校验。
UploadMode	String	`part`	上传模式。 `direct`：直接上传 `part`：分片上传
Oid	String	`demo`	参数的唯一标识符。
PutURL	String	`https://ll.xxx`	直接上传的 URL。
PutURLHeaders	Array of PutURLHeaders	`-`	直接上传的请求头。
PartUploadInfo	Object of PartUploadInfo	`-`	分片上传信息。

PutURLHeaders

参数	类型	示例值	描述
Key	String	`Content-Type`	请求头的键（Header key）。
Value	String	`image/jpeg`	请求头的值（Header value）。

PartUploadInfo

参数	类型	示例值	描述
PartPutURLs	Array of String	`["https://tos.xxx","https://tos.yyy"]`	分块上传 URL 列表。
CompletePartURL	String	`https://ouy.*.com`	合并分片的 URL。
PartSize	Long	`4194304`	上传分片大小，默认为 200MB。
CompletePartURLHeaders	Array of CompletePartURLHeaders	`-`	上传分片请求头信息，用于合并分片请求。

CompletePartURLHeaders

参数	类型	示例值	描述
Key	String	`X-Tos-Forbid-Overwrite`	请求头的键（Header key）。
Value	String	`true`	请求头的值（Header value）。

请求示例

GET https://imagex.volcengineapi.com/?Action=ApplyVpcUploadInfo&Version=2023-05-01&ServiceId=u3*k

返回示例

{
    "ResponseMetadata": {
        "RequestId": "20230604110420****100232280022D31",
        "Action": "ApplyVpcUploadInfo",
        "Version": "2023-05-01",
        "Service": "ImageX",
        "Region": "cn-north-1"
    },
    "Result": {
        "UploadMode": "part",
        "PartUploadInfo": {
            "PartSize": 4194304,
            "PartPutURLs": [
                "https://tos.xxx",
                "https://tos.yyy"
            ],
            "CompletePartURL": "https://ouy.*.com",
            "CompletePartURLHeaders": [
                {
                    "Key": "X-Tos-Forbid-Overwrite",
                    "Value": "true"
                }
            ]
        },
        "SessionKey": "eyJh**In0=",
        "Oid": "demo",
        "PutURL": "https://ll.xxx",
        "PutURLHeaders": [
            {
                "Key": "Content-Type",
                "Value": "image/jpeg"
            }
        ]
    }
}

错误码

本接口无特有的错误码。更多信息请见公共错误码和 veImageX 错误码。