Initiate a multipart upload
Initiates aXML API multipart upload with aPOST request. This initialrequest generates an upload ID for use in subsequentPUT requests toupload the data in parts and in the finalPOST request tocomplete the upload. There is no limit to the number of multipartuploads 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 existingobject with the same name. For tips on uploading to Cloud Storage, seebest practices.
For simple uploads with the XML API, you make aPUT Object requestinstead of usingPOST Object.
Query string parameters
| Parameter | Description | Required |
|---|---|---|
uploads | Indicates the request is to initiate a multipart upload. | Yes |
Seesigned URL query string parameters for information on the parametersyou include when creating and usingsigned 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 toapplication/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, seeRequest 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 | Thecustomer-managed encryption key to use to encrypt the object. | No |
x-goog-meta- | An extension header that can be used to storecustom metadata. | No |
x-goog-object-lock-mode | Mode of the object'sretention configuration. If this header is specified, | No |
| A date and time represented inRFC 3339 UTC format that determines the time until which the object is retained as immutable. If this header is 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, usetheheaders listed on the Customer-Supplied Encryption Key page in yourrequest.
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 requestheaders you use.
Response body elements
The following response body elements apply to POST Object requests that use theuploads 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 namedparis.jpg in a bucket namedtravel-maps.
Request
POST /paris.jpg?uploads HTTP/2Host: travel-maps.storage.googleapis.comDate: Wed, 24 Mar 2021 18:11:50 GMTContent-Type: image/jpgContent-Length: 0Authorization: Bearer ya29.AHES6ZRVmB7fkLtd1XTmq6mo0S1wqZZi3-Lh_s-6Uw7p8vtgSwg
Response
HTTP/2 200Date: Wed, 24 Mar 2021 18:11:53 GMTContent-Length: 280Content-Type: application/xmlServer: 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>
Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.
Last updated 2025-12-17 UTC.