Photos Picker

The Photos Picker API is separate from the app-created-only Photos Library API. It exposes only media the user explicitly selects for a short-lived picking session.

#Setup

Enable the Photos Picker API in the OAuth client project, then authorize the dedicated service:

gog auth add you@gmail.com --services photospicker

photospicker is intentionally excluded from the default user and all-user service sets. It uses only https://www.googleapis.com/auth/photospicker.mediaitems.readonly.

#Select Media

Create a session and open its Google-hosted picker:

gog photos picker create --max-items 20 --open --json

The response contains session.id, session.pickerUri, the expiration time, and Google's recommended polling configuration. The browser must be signed in to the same Google account that owns the session.

Wait until the user finishes:

gog photos picker wait <sessionId> --json

wait follows the API-provided pollInterval and timeoutIn. An optional --timeout only shortens that server-provided limit.

#List And Download

List one page or all selected items:

gog photos picker list <sessionId> --max 100 --json
gog photos picker list <sessionId> --all --json

Download an item by its selected-media ID:

gog photos picker download <sessionId> <mediaItemId> --out photo.jpg

Downloads use the authenticated Picker client. Image downloads request the original media with location metadata removed; video downloads request the transcoded video bytes and reject videos that are not ready.

Picker baseUrl values are short-lived, currently up to 60 minutes, and require an OAuth bearer token. Prefer the download command instead of persisting or sharing those URLs.

#Cleanup

Delete the session after retrieving the required bytes:

gog photos picker delete <sessionId>

Google recommends deleting completed or timed-out sessions to avoid session resource limits. create and delete support the global --dry-run flag.

Command pages: