Google

Google Photos APIs

Let users pick photos with the Picker API, upload to Google Photos and manage the albums and media your app created.

Media & contentGuided#photos#oauth2#picker#uploads#albums#google

Fork copies the collection into your workspace, without the publisher's secrets, so you can add your own key and send requests. Star saves it to your starred APIs (Account › Marketplace) and helps others find it.

Overview

Google Photos offers two REST APIs, and since 31 March 2025 they do different jobs:

  • The Photos Picker API lets the user choose photos and videos from their whole Google Photos library in a Google-hosted picker; your app then reads only the chosen items. Use it for "import from Google Photos", profile pictures, printing and similar features.
  • The Photos Library API lets your app upload photos and videos, create albums, and then list, read and edit only the content it created. It can no longer browse the user's library, read albums the user made, or share albums.

What changed in 2025

Google removed three Library API scopes: photoslibrary.readonly, photoslibrary.sharing and photoslibrary. As a result mediaItems.list, mediaItems.search, mediaItems.get, albums.list and albums.get return only app-created content, and the sharing methods (albums.share, albums.unshare, sharedAlbums.*) are gone. A request for any other photo or album, or a call that relied on a removed scope, gets 403 PERMISSION_DENIED. If your app used to read the library, move that feature to the Picker API. See Updates to the Google Photos APIs.

Set up credentials

  1. In the Google Cloud console, create or choose a project.
  2. Enable the Photos Picker API and/or the Photos Library API under APIs & Services > Library.
  3. Configure the OAuth consent screen (Google Auth Platform): External, publishing status Testing, add yourself as a test user, add the scopes below.
  4. Create an OAuth client of type Web application with your redirect URI, and copy the client ID and secret into this collection.
  5. Run 1. Get an access token, or use the OAuth 2.0 Playground for a quick token.

Apps that use the Photos APIs must pass Google's OAuth verification before real users (beyond your test users) can sign in. Guide: Authorization.

Scopes

ScopeAPIAllows
photospicker.mediaitems.readonlyPickersessions and the items the user picked
photoslibrary.appendonlyLibraryupload, create media items and albums
photoslibrary.readonly.appcreateddataLibraryread app-created items and albums
photoslibrary.edit.appcreateddataLibraryedit app-created items and albums, enrichments

All are prefixed with https://www.googleapis.com/auth/.

Base URLs and authentication

  • Picker: https://photospicker.googleapis.com/v1
  • Library: https://photoslibrary.googleapis.com/v1

Every request, including downloads from a picked item's baseUrl, sends Authorization: Bearer <access token>. Base URLs expire after 60 minutes; store item IDs instead.

How to use this collection

Run the folders in order: get a token, try the picker flow (create session, open pickerUri, poll, list, download, delete), then upload, create an album, add items and read or edit them. Test scripts save sessionId, pickedBaseUrl, uploadToken, mediaItemId, albumId and libraryBaseUrl for the next request.

Limits

Each API has per-project request quotas and separate quotas for fetching media bytes; see Usage limits and the Quotas page in the Cloud console. Uploads: photos up to 200 MB, videos up to 20 GB; up to 50 items per batch call.

Common errors

StatusMeaningWhat to do
401 UNAUTHENTICATEDtoken missing or expiredrun Refresh the access token
403 PERMISSION_DENIEDscope not granted, removed scope, or content not created by your appuse the Picker API for the user's own photos; check scopes
403 SERVICE_DISABLEDAPI not enabled in the projectenable it in the Cloud console
400 INVALID_ARGUMENTbad body, missing updateMask, albumId with filtersread error.message
429 RESOURCE_EXHAUSTEDquota reachedback off and retry, check quotas

Links

Endpoints 26

1. Get an access token

  • GETBuild the sign-in URL (open in a browser)https://accounts.google.com/o/oauth2/v2/authNot an API call: this request only builds Google's consent screen URL so you can copy it. Open it in a browser (sending it from here just returns the HTML…
  • POSTExchange the code for tokenshttps://oauth2.googleapis.com/tokenTrades the one-time code from the redirect for an access token and a refresh token. When: once, right after the browser sign-in. A code works once and expires…
  • POSTRefresh the access tokenhttps://oauth2.googleapis.com/tokenGets a new access token from the saved refresh token, without asking the user again. When: whenever a request returns 401 (access tokens last about an hour).…

2. Photos Picker API (the user's whole library)

  • POSTCreate a picking session{{pickerUrl}}/sessionsStarts a session and returns the pickerUri the user opens to choose photos and videos. When: each time the user wants to pick something. Scope:…
  • GETPoll the session{{pickerUrl}}/sessions/{{sessionId}}Reads the session to find out whether the user has finished picking. When: after opening pickerUri, repeat this call at the rate the response suggests in…
  • GETList picked media items{{pickerUrl}}/mediaItemsLists what the user picked in this session, page by page. When: after polling shows mediaItemsSet: true. What comes back: mediaItems[], each with id (stable…
  • GETDownload a picked photo (resized){{pickedBaseUrl}}=w1024-h1024Fetches the image bytes of a picked item, scaled to fit inside 1024x1024. How: baseUrl is not usable on its own: append size or download parameters after =.…
  • GETDownload a picked photo (original with metadata){{pickedBaseUrl}}=dDownloads the full image with its Exif metadata (=d). Google strips location data from the download. When: when you need the original resolution or camera…
  • GETDownload a picked video{{pickedBaseUrl}}=dvDownloads a high-quality transcoded copy of a picked video (=dv). When: only for items with type: VIDEO. Check…
  • DELETEDelete the session{{pickerUrl}}/sessions/{{sessionId}}Deletes the picking session once you have copied what you need. When: right after downloading the picked items. Delete sessions you no longer need; after…

3. Library API: upload and create

  • POSTUpload bytes{{libraryUrl}}/uploadsUploads raw file bytes and returns an upload token. This is step 1 of 2: the bytes are not in the user's library until Create media items from upload tokens…
  • POSTCreate an album{{libraryUrl}}/albumsCreates an album in the user's Google Photos that your app owns. When: before adding uploads to it. Only albums created this way can be changed through the…
  • POSTCreate media items from upload tokens{{libraryUrl}}/mediaItems:batchCreateTurns upload tokens into media items in the user's library, and optionally adds them to an app-created album in the same call. Scope:…
  • POSTAdd media items to an album{{libraryUrl}}/albums/{{albumId}}:batchAddMediaItemsAdds existing app-created media items to an app-created album (appended at the end, in the order given). When: for items uploaded without albumId, or to put…
  • POSTAdd a text enrichment to an album{{libraryUrl}}/albums/{{albumId}}:addEnrichmentInserts a text caption (an *enrichment*) into an app-created album, for example a heading above a group of photos. Enrichments are still available, but only…

4. Library API: read app-created content

  • GETList app-created media items{{libraryUrl}}/mediaItemsLists media items your app created, newest first, page by page. Scope: photoslibrary.readonly.appcreateddata. Query: pageSize (default 25, max 100),…
  • POSTSearch app-created media items (by album){{libraryUrl}}/mediaItems:searchLists the media items in one app-created album. Body: albumId plus pageSize (max 100) and pageToken. You cannot combine albumId with filters: the request…
  • POSTSearch app-created media items (filters){{libraryUrl}}/mediaItems:searchFilters your app's media items by date, media type or content, still limited to items your app created. Results come newest first. orderBy…
  • GETGet a media item{{libraryUrl}}/mediaItems/{{mediaItemId}}Reads one app-created media item, including a fresh baseUrl. When: to show or download an item you uploaded earlier. Store media item IDs, not base URLs: base…
  • GETGet several media items{{libraryUrl}}/mediaItems:batchGetReads up to 50 app-created media items in one call. Query: repeat mediaItemIds once per ID (no duplicates, not empty). What comes back: mediaItemResults[],…
  • GETDownload an app-created photo{{libraryBaseUrl}}=w2048-h2048Fetches the image bytes of an app-created item from its baseUrl (set by Get a media item), scaled to fit 2048x2048. The suffixes are the same as for picked…
  • GETList app-created albums{{libraryUrl}}/albumsLists albums your app created (albums the user made in Google Photos are not returned any more). Query: pageSize (default 20, max 50), pageToken. What comes…
  • GETGet an album{{libraryUrl}}/albums/{{albumId}}Reads one app-created album: title, item count, cover photo and productUrl. When: to show an album you created, or to check mediaItemsCount after adding…

5. Library API: edit app-created content

  • PATCHRename an album{{libraryUrl}}/albums/{{albumId}}Changes the title (or the cover photo) of an app-created album. Query: updateMask is required: title or coverPhotoMediaItemId (the cover must be an item in…
  • PATCHUpdate a media item description{{libraryUrl}}/mediaItems/{{mediaItemId}}Changes the description shown in the item's info panel in Google Photos. Query: updateMask=description (the only allowed value). Body: {"description": "..."},…
  • POSTRemove media items from an album{{libraryUrl}}/albums/{{albumId}}:batchRemoveMediaItemsTakes app-created items out of an app-created album. The items stay in the user's library; there is no API to delete media items. Body: mediaItemIds (up to…

API details

Base URL
https://photospicker.googleapis.com/v1
https://photoslibrary.googleapis.com/v1
Authentication
A bearer token in the Authorization header
OAuth 2.0 (authorization code flow) with 4 scopes
Operations
26 operations on 26 pathsGET 12POST 11PATCH 2DELETE 1
Main resources
1. Get an access token 32. Photos Picker API (the user's whole library) 73. Library API: upload and create 54. Library API: read app-created content 85. Library API: edit app-created content 3
Description format
Swastik Codes guided collection, API version checked against the docs on 2026-11-17

How to test the Google Photos APIs in Swastik Codes

  1. Open the APISelect “Fork & run in Swastik Codes” on this page. Sign in or create a free account if asked.
  2. Fork it into your workspaceChoose a workspace. You get your own copy of the Google Photos APIs collection, without the publisher's secrets.
  3. Add your credentialsThis API uses A bearer token in the Authorization header. Add yours in the collection's variables or an environment; the requests already reference it.
  4. Send a requestPick an endpoint, for example “Build the sign-in URL (open in a browser)” (GET https://accounts.google.com/o/oauth2/v2/auth), and press Send. Check the response, add tests and run the whole collection with the runner.

Frequently asked questions

What is the Google Photos APIs?

Let users pick photos with the Picker API, upload to Google Photos and manage the albums and media your app created. It is listed under Media & content and has 26 endpoints.

Who publishes the Google Photos APIs?

It is listed from Google's public API description (an OpenAPI document), not published by Google on Swastik Codes. Anyone who controls googleapis.com can claim the profile by adding a DNS TXT record.

What is the base URL of the Google Photos APIs?

Its description lists 2 base URLs: https://photospicker.googleapis.com/v1, https://photoslibrary.googleapis.com/v1. The first is the usual one; the others are typically sandbox or regional servers.

How do I authenticate with the Google Photos APIs?

It accepts 2 methods: A bearer token in the Authorization header; OAuth 2.0 (authorization code flow) with 4 scopes.

How many endpoints does the Google Photos APIs have?

26 operations on 26 paths (12 GET, 11 POST, 2 PATCH, 1 DELETE). The largest groups are 1. Get an access token, 2. Photos Picker API (the user's whole library), 3. Library API: upload and create, 4. Library API: read app-created content.

Is forking the Google Photos APIs free?

Yes. Forking copies the collection into your workspace for free. It has been starred 0 times and forked 0 times.

Suggest an API

Tell us which public API is missing. We check it, then add it here with its endpoints when it has an OpenAPI (Swagger) description.