Manage media items

  • After uploading media items to Google Photos, you can change their descriptions using the Google Photos API.

  • Modifying descriptions of app-created content requires the photoslibrary.edit.appcreateddata scope and ownership by the authenticated user.

  • To update a description, use the mediaItems/patch endpoint with the item's ID and a request body containing the new description.

  • The updateMask parameter in the request URL specifies that only the description is being modified.

  • The response to a successful update request will return the complete updated media item object.

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

Required authorization scope

Changing descriptions of app-created content requires the photoslibrary.edit.appcreateddata scope. For more information on scopes, see Authorization scopes.

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"
}