Method: mediaItems.batchCreate

Creates one or more media items in a user's Google Photos library.

This is the second step for creating a media item. For details regarding Step 1, uploading the raw bytes to a Google Server, see Uploading media.

This call adds the media item to the library. If an album id is specified, the call adds the media item to the album too. Each album can contain up to 20,000 media items. By default, the media item will be added to the end of the library or album.

If an album id and position are both defined, the media item is added to the album at the specified position.

If the call contains multiple media items, they're added at the specified position. If you are creating a media item in a shared album where you are not the owner, you are not allowed to position the media item. Doing so will result in a BAD REQUEST error.

HTTP request

POST https://photoslibrary.googleapis.com/v1/mediaItems:batchCreate

The URL uses gRPC Transcoding syntax.

Request body

The request body contains data with the following structure:

JSON representation
{
  "albumId": string,
  "newMediaItems": [
    {
      object (NewMediaItem)
    }
  ],
  "albumPosition": {
    object (AlbumPosition)
  }
}
Fields
albumId

string

Identifier of the album where the media items are added. The media items are also added to the user's library. This is an optional field.

newMediaItems[]

object (NewMediaItem)

List of media items to be created.

albumPosition

object (AlbumPosition)

Position in the album where the media items are added. If not specified, the media items are added to the end of the album (as per the default value, that is, LAST_IN_ALBUM). The request fails if this field is set and the albumId is not specified. The request will also fail if you set the field and are not the owner of the shared album.

Response body

If successful, the response body contains data with the following structure:

List of media items created.

JSON representation
{
  "newMediaItemResults": [
    {
      object (NewMediaItemResult)
    }
  ]
}
Fields
newMediaItemResults[]

object (NewMediaItemResult)

Output only. List of media items created.

Authorization Scopes

Requires one of the following OAuth scopes:

  • https://www.googleapis.com/auth/photoslibrary
  • https://www.googleapis.com/auth/photoslibrary.appendonly
  • https://www.googleapis.com/auth/photoslibrary.sharing

NewMediaItem

New media item that's created in a user's Google Photos account.

JSON representation
{
  "description": string,
  "simpleMediaItem": {
    object (SimpleMediaItem)
  }
}
Fields
description

string

Description of the media item. This will be shown to the user in the item's info section in the Google Photos app. This string shouldn't be more than 1000 characters.

simpleMediaItem

object (SimpleMediaItem)

A new media item that has been uploaded via the included uploadToken.

SimpleMediaItem

A simple media item to be created in Google Photos via an upload token.

JSON representation
{
  "uploadToken": string
}
Fields
uploadToken

string

Token identifying the media bytes that have been uploaded to Google.

NewMediaItemResult

Result of creating a new media item.

JSON representation
{
  "uploadToken": string,
  "status": {
    object (Status)
  },
  "mediaItem": {
    object (MediaItem)
  }
}
Fields
uploadToken

string

The upload token used to create this new media item.

status

object (Status)

If an error occurred during the creation of this media item, this field is populated with information related to the error. For details regarding this field, see Status.

mediaItem

object (MediaItem)

Media item created with the upload token. It's populated if no errors occurred and the media item was created successfully.

Try it!