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)

Required. List of media items to be created. Maximum 50 media items per call.
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

List of media items created.

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

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,

  // Union field new_media_item_type can be only one of the following:
  "simpleMediaItem": {
    object (SimpleMediaItem)
  }
  // End of list of possible types for union field new_media_item_type.
}
Fields
description

string

Description of the media item. This is shown to the user in the item's info section in the Google Photos app. Must be shorter than 1000 characters. Only include text written by users. Descriptions should add context and help users understand media. Do not include any auto-generated strings such as filenames, tags, and other metadata.
Union field new_media_item_type. The new media item can be of various different types - this is dependent on the upload path. The currently supported uploads only use the simple media item path. new_media_item_type can be only one of the following:
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,
  "fileName": string
}
Fields
uploadToken

string

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

string

File name with extension of the media item. This is shown to the user in Google Photos. The file name specified during the byte upload process is ignored if this field is set. The file name, including the file extension, shouldn't be more than 255 characters. This is an optional field.

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 (simple) media item. Only populated if the media item is simple and required a single upload token.
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.