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>