Upload media

REST

Include the following fields in the POST request header:

Here is a POST request header:

POST https://photoslibrary.googleapis.com/v1/uploads
Authorization: Bearer OAUTH2_TOKEN
Content-type: application/octet-stream
X-Goog-Upload-File-Name: FILENAME
X-Goog-Upload-Protocol: raw

In the request body, include the binary of the file:

MEDIA_BINARY_DATA

If this POST request is successful, an upload token which is in the form of a raw text string, is returned as the response body. To create media items, use these text strings in the batchCreate call.

UPLOAD_TOKEN

Java

try {
  // Create a new upload request
  // Specify the filename that will be shown to the user in Google Photos
  // and the path to the file that will be uploaded
  UploadMediaItemRequest uploadRequest =
      UploadMediaItemRequest.newBuilder()
          //filename of the media item along with the file extension
          .setFileName(mediaFileName)
          .setDataFile(new RandomAccessFile(pathToFile, "r"))
          .build();
  // Upload and capture the response
  UploadMediaItemResponse uploadResponse = photosLibraryClient.uploadMediaItem(uploadRequest);
  if (uploadResponse.getError().isPresent()) {
    // If the upload results in an error, handle it
    Error error = uploadResponse.getError().get();
  } else {
    // If the upload is successful, get the uploadToken
    String uploadToken = uploadResponse.getUploadToken().get();
    // Use this upload token to create a media item
  }
} catch (ApiException e) {
  // Handle error
} catch (FileNotFoundException e) {
  // Local file could not be found for upload
}

PHP

// Create a new upload request

// Specify the filename that will be shown to the user in Google Photos
// and the path to the file that will be uploaded

// When specifying a filename, include the file extension
try {
    $uploadToken = $photosLibraryClient->upload(file_get_contents($localFilePath), $filename);
} catch (\GuzzleHttp\Exception\GuzzleException $e) {
    // Handle error
}

REST

Here is the POST request header:

POST https://photoslibrary.googleapis.com/v1/mediaItems:batchCreate
Content-type: application/json
Authorization: Bearer OAUTH2_TOKEN

The request body should specify a list of newMediaItems.

{
  "newMediaItems": [
    {
      "description": "ITEM_DESCRIPTION",
      "simpleMediaItem": {
        "uploadToken": "UPLOAD_TOKEN"
      }
    }
   , ...
  ]
}

Java

try {
  // Create a NewMediaItem with the uploadToken obtained from the previous upload request, and a description
  NewMediaItem newMediaItem = NewMediaItemFactory
      .createNewMediaItem(uploadToken, itemDescription);
  List<NewMediaItem> newItems = Arrays.asList(newMediaItem);

  BatchCreateMediaItemsResponse response = photosLibraryClient.batchCreateMediaItems(newItems);
  for (NewMediaItemResult itemsResponse : response.getNewMediaItemResultsList()) {
    Status status = itemsResponse.getStatus();
    if (status.getCode() == Code.OK_VALUE) {
      // The item is successfully created in the user's library
      MediaItem createdItem = itemsResponse.getMediaItem();
    } else {
      // The item could not be created. Check the status and try again
    }
  }
} catch (ApiException e) {
  // Handle error
}

PHP

try {
    $newMediaItems = [];
    $newMediaItems[0] = array(
        PhotosLibraryResourceFactory::newMediaItemWithDescription($uploadToken, $itemDescription));

    $response = $photosLibraryClient->batchCreateMediaItems($newMediaItems);
    foreach ($response->getNewMediaItemResults() as $itemResult) {
        $status = $itemResult->getStatus();
        if ($status->getCode() != Code::OK) {
            // Error when item is being created
        }
    }
} catch (\Google\ApiCore\ApiException $e) {
    // Handle error
}

REST

{
  "albumId": "ALBUM_ID",
  "newMediaItems": [
    {
      "description": "ITEM_DESCRIPTION",
      "simpleMediaItem": {
        "uploadToken": "UPLOAD_TOKEN"
      }
    }
   , ...
  ]
}

Java

try {
  // Create new media items in a specific album
  BatchCreateMediaItemsResponse response = photosLibraryClient
      .batchCreateMediaItems(albumId, newItems);
  // Check the response
} catch (ApiException e) {
  // Handle error
}

PHP

try {
    $response = $photosLibraryClient->batchCreateMediaItems($newMediaItems, ['albumId' => $albumId]);
} catch (\Google\ApiCore\ApiException $e) {
    // Handle error
}

REST

{
  "albumId": "ALBUM_ID",
  "newMediaItems": [
    {
      "description": "ITEM_DESCRIPTION",
      "simpleMediaItem": {
        "uploadToken": "UPLOAD_TOKEN"
      }
    }
    , ...
  ],
  "albumPosition": {
    "position": "AFTER_MEDIA_ITEM",
    "relativeMediaItemId": "MEDIA_ITEM_ID"
  }
}

Java

try {
  // Create new media items in a specific album, positioned after a media item
  AlbumPosition positionInAlbum = AlbumPositionFactory.createFirstInAlbum();
  BatchCreateMediaItemsResponse response = photosLibraryClient
      .batchCreateMediaItems(albumId, newItems, positionInAlbum);
  // Check the response
} catch (ApiException e) {
  // Handle error
}

PHP

try {
    $albumPosition = PhotosLibraryResourceFactory::albumPositionAfterMediaItem($mediaItemId);
    $response = $photosLibraryClient->batchCreateMediaItems($newMediaItems,
        ['albumId' => $albumId, 'albumPosition' => $albumPosition]);
} catch (\Google\ApiCore\ApiException $e) {
    // Handle error
}

REST

If all media items have been successfully created, the request returns HTTP status 200 OK. If some some media items could not be created, the request returns HTTP status 207 MULTI-STATUS to indicate partial success.

{
  "newMediaItemResults": [
    {
      "uploadToken": "UPLOAD_TOKEN",
      "status": {
        "message": "OK"
      },
      "mediaItem": {
        "id": "MEDIA_ITEM_ID",
        "productUrl": "https://photos.google.com/photo/PHOTO_PATH",
        "description": "ITEM_DESCRIPTION",
        "baseUrl": "BASE_URL-DO_NOT_USE_DIRECTLY",
        "mediaMetadata": {
          "width": "MEDIA_WIDTH_IN_PX",
          "height": "MEDIA_HEIGHT_IN_PX",
          "creationTime": "CREATION_TIME",
          "photo": {}
        },
      }
    },
    {
      "uploadToken": "UPLOAD_TOKEN",
      "status": {
        "code": 13,
        "message": "Internal error"
      }
    }
  ]
}

Java

BatchCreateMediaItemsResponse response = photosLibraryClient.batchCreateMediaItems(newItems);

// The response contains a list of NewMediaItemResults
for (NewMediaItemResult result : response.getNewMediaItemResultsList()) {
  // Each result item is identified by its uploadToken
  String uploadToken = result.getUploadToken();
  Status status = result.getStatus();

  if (status.getCode() == Code.OK_VALUE) {
    // If the request is successful, a MediaItem is returned
    MediaItem mediaItem = result.getMediaItem();
    String id = mediaItem.getId();
    String productUrl = mediaItem.getProductUrl();
    // ...
  }
}

PHP

// The response from a call to batchCreateMediaItems returns a list of NewMediaItemResults
foreach ($response->getNewMediaItemResults() as $itemResult) {
    // Each result item is identified by its uploadToken
    $itemUploadToken = $itemResult->getUploadToken();
    // Verify the status of each entry to ensure that the item has been uploaded correctly
    $itemStatus = $itemResult->getStatus();
    if ($itemStatus->getCode() != Code::OK) {
        // Error when item is being created
    } else {
        // Media item is successfully created
        // Get the MediaItem object from the response
        $mediaItem = $itemResult->getMediaItem();
        // It contains details such as the Id of the item, productUrl
        $id = $mediaItem->getId();
        $productUrl = $mediaItem->getProductUrl();
        // ...
    }
}