> ## Documentation Index
> Fetch the complete documentation index at: https://docs.corsair.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Google Photos plugin

> Read albums and media items, upload photos and videos, and manage album membership through the Google Photos Library API.

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**

```bash npm theme={null}
npm install corsair @corsair-dev/googlephotos better-sqlite3
npm install --save-dev @types/better-sqlite3
```

```bash yarn theme={null}
yarn add corsair @corsair-dev/googlephotos better-sqlite3
yarn add --dev @types/better-sqlite3
```

```bash pnpm theme={null}
pnpm install corsair @corsair-dev/googlephotos better-sqlite3
pnpm install --save-dev @types/better-sqlite3
```

```bash bun theme={null}
bun add corsair @corsair-dev/googlephotos better-sqlite3
bun add --dev @types/better-sqlite3
```

**2. Add the plugin**

```ts corsair.ts theme={null}
import Database from 'better-sqlite3';
import { createCorsair } from 'corsair';
import { googlephotos } from '@corsair-dev/googlephotos';

export const corsair = createCorsair({
	plugins: [
		googlephotos(),
	],
	database: new Database('corsair.db'),
	kek: process.env.CORSAIR_KEK!,
	multiTenancy: true,
	hub: {
		projectApiKey: process.env.CORSAIR_API_KEY!,
		signingSecret: process.env.CORSAIR_SIGNING_SECRET!,
	},
});
```

With `multiTenancy: true`, scope calls with `corsair.withTenant(id)`. See [Quick start](https://docs.corsair.dev/quick-start.md) for KEK + Hub keys, and [Multi-tenancy](https://docs.corsair.dev/concepts/multi-tenancy.md) for account isolation.

**3. Choose authentication**

> [tab] OAuth 2.0 (Recommended)
>
> Open [hub.corsair.dev](https://hub.corsair.dev/dashboard), navigate to your project, and enter the **client ID** and **client secret** from your Google Photos OAuth app.
>
> ```ts theme={null}
> googlephotos()
> ```
>
> More: [OAuth 2.0](https://docs.corsair.dev/concepts/oauth)

**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](https://docs.corsair.dev/management/connect).

```ts theme={null}
const { connectUrl } = await corsair.manage.connect.createLink({
	plugin: 'googlephotos',
	tenantId: 'acme',
});
// redirect the user's browser to connectUrl
```

## Example API calls

**Find the photos in an app-created album**

```ts theme={null}
const tenant = corsair.withTenant('acme');
await tenant.googlephotos.api.mediaItems.search({ albumId: 'ABcDeFgHiJkLmNoP' });
```

**Create an album**

```ts theme={null}
const tenant = corsair.withTenant('acme');
await tenant.googlephotos.api.albums.create({ title: 'Holiday 2026' });
```

See the full list on the [API](https://docs.corsair.dev/plugins/googlephotos/api.md) page.

## What's next

> [card] [API reference](https://docs.corsair.dev/plugins/googlephotos/api.md)
>
> Every `googlephotos.api.*` operation with input and output types.

> [card] [Connect / OAuth](https://docs.corsair.dev/management/connect)
>
> createLink, Hub delivery, and tenant connect flows.

> [card] [Use with agents](https://docs.corsair.dev/mcp-adapters/mcp-adapters)
>
> Expose this plugin's operations as MCP tools.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.