Skip to main content
Use Google Photos through Corsair: one client, typed API calls. The Google Photos Library API manages a user’s albums and media items: it lists and searches them, uploads new bytes, and adds or removes items from albums an app created. Read this before you build on it. On 31 March 2025 Google removed the photoslibrary, photoslibrary.readonly and photoslibrary.sharing scopes and restricted the Library API to content the app created. Three things follow, and this plugin is shaped around them:
  • The scopes that remain are photoslibrary.appendonly, photoslibrary.readonly.appcreateddata and photoslibrary.edit.appcreateddata. All three are requested here.
  • Reads only reach albums and media items this app created. No API searches the rest of a user’s library any more. To work with other photos, the Google Photos Picker API lets the user pick items in a Picker session and gives the app only those; it is a different API with its own flow and is not part of this plugin.
  • albums.share, albums.unshare and every sharedAlbums.* method were removed. The plugin exposes none of them.
Things to know before you call:
  • Uploading is two steps, done here in one call. mediaItems.create posts the bytes to /uploads, reads back an upload token, then sends up to 50 tokens to mediaItems:batchCreate. Each file is a public URL, { url } or { base64 }, with an optional filename and contentType, up to 200 MB. A partial failure answers 207 with a status per item, so check each newMediaItemResults[].status.
  • Uploads count toward the user’s storage past 25MB. Google asks an app to tell the user this.
  • Google asks for a different request shape per list. Albums default to 20 per page and cap at 50; media items default to 25 and cap at 100. Both are paginated with nextPageToken.
  • filters and albumId cannot be combined. The API answers 400, so the plugin refuses it before the request.
  • orderBy only works with a date filter. The two accepted values are MediaMetadata.creation_time desc (newest first, the default) and MediaMetadata.creation_time.
  • A base URL is not fetchable, and it expires. A parameter must be appended: =d for a photo’s original bytes, =dv for a video’s bytes, or =w<width>-h<height> for a scaled copy (a thumbnail for a video) with an optional -c to crop. A base URL works for 60 minutes after the read that returned it. mediaBytesUrl(item, options) builds the URL and picks =dv when the item is a video.
  • Updates change one field each. albums.update renames an album (the title mask) and mediaItems.update changes a media item’s description (the description mask, the only one the API accepts).
  • A 429 needs at least 30 seconds before a retry. That is the upload guide’s rule. The plugin waits 30 seconds, or longer when Google’s Retry-After asks for more. A 429 that reports the spent daily quota (10,000 requests per project per day) is not retried, since no wait within the call can clear it.
  • No service accounts. Google states the Library API does not support them, so every call is made as a signed-in user.
What you get:
  • 13 typed API operations

Setup

1

Install

2

Add the plugin

corsair.ts
With multiTenancy: true, scope calls with corsair.withTenant(id). See Quick start for KEK + Hub keys, and Multi-tenancy for account isolation.
3

Choose authentication

4

Connect a tenant

Mint a connect link and send the tenant to it. Hub hosts the page and delivers the result to your app — see Connect / OAuth.

Example API calls

Find the photos in an app-created album
Create an album
See the full list on the API page.

What’s next

API reference

Every googlephotos.api.* operation with input and output types.

Connect / OAuth

createLink, Hub delivery, and tenant connect flows.

Use with agents

Expose this plugin’s operations as MCP tools.