Performing multipart uploads

This page describes how to make a multipart upload request using the Cloud Storage JSON API. A multipart upload request allows you to send metadata along with the data to upload. Use this option if the data you are sending is small enough to upload again in its entirety if the connection fails.

If your file does not have any metadata, use simple upload instead. For larger files or less reliable network connections, use resumable upload instead.

A multipart upload is considered one Class A operation.

Learn about request URIs

When you upload objects with the JSON API, you use a special URI that differs from the URI you use for most JSON API requests, including requests to upload object metadata:

  • For object uploads, use the /upload URI. The format of the /upload endpoint is the standard resource URI with an /upload prefix. Use this URI when transferring the object data itself.

    For example, for a bucket named myBucket:

    POST /upload/storage/v1/b/myBucket/o
  • For other requests, use the standard resource URI. This includes adding or updating metadata values for an existing object.

    For example, for a metadata patch to an object named myObject in a bucket named myBucket:

    PATCH /storage/v1/b/myBucket/o/myObject

Sending a multipart upload request

To use multipart upload:

  1. Create a POST request to the method's /upload URI.
  2. Add the query parameter uploadType=multipart.

    For example, for a bucket named myBucket:

  3. Create the body of the request. Format the body according to the multipart/related content type RFC 2387, which contains two parts:

    1. Metadata part. Must come first, and must have a Content-Type header set to application/json; charset=UTF-8. Add the file's metadata to this part in JSON format.
    2. Media part. Must come second, and must have a Content-Type header, which may have any MIME type. Add the file's data to this part.

    Identify each part with a boundary string, preceded by two hyphens. In addition, add two hyphens after the final boundary string.

  4. Add the following top-level HTTP headers:

    • Content-Type. Set to multipart/related, and include the boundary string you're using to identify the different parts of the request. For example: Content-Type: multipart/related; boundary=foo_bar_baz
    • Content-Length. Set to the total number of bytes in the request body.
  5. Send the request.

Example: Sending a multipart upload request

The following example shows a multipart upload request to a bucket named myBucket:

Authorization: Bearer YOUR_AUTH_TOKEN
Content-Type: multipart/related; boundary=foo_bar_baz

Content-Type: application/json; charset=UTF-8

  "name": "myObject"

Content-Type: image/jpeg


If the request succeeds, the server returns the HTTP 200 OK status code along with the file's metadata:

HTTP/1.1 200
Content-Type: application/json

  "name": "myObject"

Handling errors

When uploading media, be sure to follow these best practices related to error handling:

  • Resume or retry uploads that fail due to connection interruptions or any 5xx errors, including:

    • 500 Internal Server Error
    • 502 Bad Gateway
    • 503 Service Unavailable
    • 504 Gateway Timeout
  • Use an exponential backoff strategy if any 5xx server error is returned when resuming or retrying upload requests. These errors can occur if a server is getting overloaded. Exponential backoff can help alleviate these kinds of problems when there is a high volume of requests or heavy network traffic.

  • When you receive an error other than a 5xx error, you do not need to use an exponential backoff strategy. Instead, limit the number of times you retry the request. For example, your code could report an error to the user after retrying a request 10 times.

For additional tips on uploading to Cloud Storage, see Uploading data best practices.

What's next?