Initiate a multipart upload

Initiates a XML API multipart upload with a POST request. This initial request generates an upload ID for use in subsequent PUT requests to upload the data in parts and in the final POST request to complete the upload. There is no limit to the number of multipart uploads that can be underway for a given object.

This initial request allows you to specify metadata for the completed object. Once a multipart upload completes, the uploaded object replaces any existing object with the same name. For tips on uploading to Cloud Storage, see best practices.

For simple uploads with the XML API, you make a PUT Object request instead of using POST Object.

Query string parameters

Parameter	Description	Required
`uploads`	Indicates the request is to initiate a multipart upload.	Yes

See signed URL query string parameters for information on the parameters you include when creating and using signed URLs.

Request headers

The following request headers can be used.

Header	Description	Required
`Authorization`	The authentication string for the request.	Yes
`Cache-Control`	The conditions under which the resulting object should be cached if it is publicly accessible. `Cache-Control` is also used to determine whether the resulting object can be transformed.	No
`Content-Disposition`	A header that specifies presentational information about how the resulting object data is to be transmitted.	No
`Content-Encoding`	The compression algorithm that was used to compress the data you are uploading.	No
`Content-Language`	The language code of the content.	No
`Content-Length`	The length of the request body without headers (in bytes). For initiating a multipart upload, this value is 0.	Yes
`Content-Type`	The MIME type of the data you are uploading. If you do not specify a content type, Cloud Storage defaults to `application/octet-stream` when it serves the uploaded object.	No (recommended)
`Date`	The date and time of the request.	Yes
`Host`	The URI for Cloud Storage. For more information, see Request Endpoints.	Yes
`x-goog-acl`	The predefined ACL that you want to apply to the object.	No
`x-goog-custom-time`	A user-specified date and time.	No
`x-goog-encryption-kms-key-name`	The customer-managed encryption key to use to encrypt the object.	No
`x-goog-meta-`	An extension header that can be used to store custom metadata.	No
`x-goog-object-lock-mode`	Mode of the object's retention configuration. `GOVERNANCE` corresponds to unlocked mode, and `COMPLIANCE` corresponds to locked mode. If this header is specified, `x-goog-object-lock-retain-until-date` must also be specified.	No
`x-goog-object-lock-retain-until-date`	A date and time represented in RFC 3339 UTC format that determines the time until which the object is retained as immutable. If this header is specified, `x-goog-object-lock-mode` must also be specified.	No
`x-goog-storage-class`	Gives each part of the upload and the resulting object a storage class besides the default storage class of the associated bucket.	No
`x-goog-user-project`	The project to be billed for charges associated with this request.	No

To provide a customer-supplied encryption key along with the object upload, use the headers listed on the Customer-Supplied Encryption Key page in your request.

Request body elements

This request does not include an XML document in the request body.

Response headers

The request can return a variety of response headers depending on the request headers you use.

Response body elements

The following response body elements apply to POST Object requests that use the uploads query string parameter.

Element	Description
`InitiateMultipartUploadResult`	Container for the response to the upload initiation request.
`Bucket`	The name of the bucket the multipart upload was initiated in.
`Key`	The name of the object the multipart upload was initiated for.
`UploadId`	The upload ID of the initiated multipart upload.

Example

The following sample initiates a multipart upload for an object named paris.jpg in a bucket named travel-maps.

Request

POST /paris.jpg?uploads HTTP/2
Host: travel-maps.storage.googleapis.com
Date: Wed, 24 Mar 2021 18:11:50 GMT
Content-Type: image/jpg
Content-Length: 0
Authorization: Bearer ya29.AHES6ZRVmB7fkLtd1XTmq6mo0S1wqZZi3-Lh_s-6Uw7p8vtgSwg

Response

HTTP/2 200
Date: Wed, 24 Mar 2021 18:11:53 GMT
Content-Length: 280
Content-Type: application/xml
Server: UploadServer

<?xml version="1.0" encoding="UTF-8"?>
<InitiateMultipartUploadResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
  <Bucket>travel-maps</Bucket>
  <Key>paris.jpg</Key>
  <UploadId>VXBsb2FkIElEIGZvciBlbHZpbmcncyBteS1tb3ZpZS5tMnRzIHVwbG9hZA</UploadId>
</InitiateMultipartUploadResult>