Manage media items

  • You can update descriptions of media items uploaded by your app using the photoslibrary.edit.appcreateddata scope.

  • To update a description, send a PATCH request to the media item's endpoint with the updateMask parameter set to description and the new description in the request body.

  • The authenticated user must be the owner of the media item to modify its description, and descriptions are limited to 1,000 characters.

  • Successful updates return the entire updated media item resource, including the new description.

  • Code samples for Java and PHP demonstrate how to programmatically update media item descriptions.

In addition to accessing media items after you upload them, you can also change their descriptions.

Required authorization scope

To change the descriptions of media items after their creation, use the photoslibrary.edit.appcreateddata scope.

Changing media item descriptions

To change a media item's description, make a media items update call with the identifier of the media item, and include the new description in the request.

To change a media item's description, your app must have uploaded the media item, and the currently authenticated user must be the owner. Descriptions can be no more than 1,000 characters in length.

REST

Here's a PATCH request header to update a media item description:

PATCH https://photoslibrary.googleapis.com/v1/mediaItems/media-item-id?updateMask=description

This request determines what properties are being updated by including a field mask, indicated by the updateMask parameter in the URL.

Include the new description in the body of the request:

{
  "description": "new-media-item-description"
}

If successful, the response returns the updated media item:

{
  "id": "media-item-id",
  "description": "new-media-item-description",
  "productUrl": "media-item-product-url",
  "baseUrl": "media-items-in-album",
  "mimeType": "mime-type-of-media",
  "mediaMetadata": {
    ...
  },
  "contributorInfo": {
    ...
  },
  "fileName": "item-filename"
}

Java

try {
  // Update the description of the media item.
  // The new description must not be null.
  MediaItem updatedItem = photosLibraryClient.updateMediaItemDescription(mediaItem, "new-media-item-description");
} catch (ApiException e) {
  // Handle error
}

PHP

try {

    // ID of the media item to update.
    $mediaItemId = "MEDIA_ITEM_ID";

    // New description of the media item.
    $newDescription = "new-media-item-description";

    // Update the description of the media item identified.
    $mediaItem = $photosLibraryClient->updateMediaItemDescription($mediaItemId, $newDescription);

} catch (\Google\ApiCore\ApiException $e) {
    // Handle error
}