Skip to content
Scalekit Docs
Talk to an Engineer Dashboard

Connect AI agents to Google Photos

Scalekit connector
Open markdown

The Google Photos connector lets your AI agent act in each user's Google Photos account. Each user signs in to Google Photos once, and Scalekit stores and refreshes their tokens, so your agent never handles credentials. It comes with 17 tools.

Tools
17
What they doRead · write · destructive
8 · 7 · 28 read7 write2 destructive
Users sign in with
OAuth app
Your own Google app

Setup

  1. Install the SDK

    Terminal window
    npm install @scalekit-sdk/node dotenv

  2. Set your credentials

    Add your Scalekit credentials to your .env file. Find values in app.scalekit.com > Developers > API Credentials.

    .env
    SCALEKIT_ENVIRONMENT_URL=<your-environment-url>
    SCALEKIT_CLIENT_ID=<your-client-id>
    SCALEKIT_CLIENT_SECRET=<your-client-secret>

  3. Create the Google Photos connection

    In AgentKit > Connections, create a Google Photos connection and copy its redirect URI. The name you give it is the connection_name your code passes. See Configure connections.

  4. Register a Google OAuth app

    Google Photos connections use your own OAuth app. Register one with Google and add the redirect URI you copied.

    Then enter the app's Client ID and Client Secret on the Google Photos connection.

  5. Authorize a user and make your first call

    quickstart.mts
    import { ScalekitClient } from '@scalekit-sdk/node'
    import 'dotenv/config'
    import { createInterface } from 'node:readline/promises'
    

    const scalekit = new ScalekitClient(
      process.env.SCALEKIT_ENVIRONMENT_URL,
      process.env.SCALEKIT_CLIENT_ID,
      process.env.SCALEKIT_CLIENT_SECRET,
    )
    const actions = scalekit.actions
    

    const connector = 'googlephotos'
    const identifier = 'user_123'
    

    // Generate an authorization link for the user
    const { link } = await actions.getAuthorizationLink({ connectionName: connector, identifier })
    console.log('Authorize Google Photos:', link)
    const rl = createInterface({ input: process.stdin, output: process.stdout })
    await rl.question('Press Enter after authorizing...')
    rl.close()
    

    // Make your first call
    const result = await actions.executeTool({
      connector,
      identifier,
      toolName: 'googlephotos_list_albums',
      toolInput: {},
    })
    console.log(result)
    Terminal window
    npx tsx quickstart.mts

    Each user signs in once. See Authorize a user for the full flow and statuses.

Tools

Pass the exact name to execute_tool
Try in PlaygroundRequest a tool
  • googlephotos_batch_get_media_itemsRetrieve up to 50 media items in a single call by their IDs, restricted to media this app itself created or uploaded — Google removed access to a user's full pre-existing Photos library in March 2025.Read-only

    Batch Get Media Items

    Retrieve up to 50 media items in a single call by their IDs, restricted to media this app itself created or uploaded — Google removed access to a user's full pre-existing Photos library in March 2025. Returns one result per requested ID: each is either the media item's details (filename, MIME type, a temporary base URL, creation time, dimensions, and photo/video metadata) or an error status if that ID doesn't exist or wasn't created by this app, so check each result's status before assuming success. Use batch_get_media_items to fetch several known items at once. Use get_media_item for a single item, or list_media_items/search_media_items to discover IDs. Requires media item IDs from a prior list_media_items, search_media_items, or batch_create_media_items call.

    Inputs

    media_item_idsarrayrequired
    Media item IDs to fetch in one call, up to 50 per request. Each ID must belong to a media item this app created or uploaded. Example: ["AKXeXaGH2op6RtcErdX_S0hu0iF8p1XKln5RfQCcXebK6HH1RwOKAAAA", "AKXeXaHy91C3vXY6rZp2Enb3vXY6rZp2Enrichment"].

    Also accepts schema_version and tool_version to pin a version.

  • googlephotos_get_albumRetrieve an album by its ID, restricted to albums this app itself created — Google removed access to a user's full pre-existing Photos library in March 2025.Read-only

    Get Album

    Retrieve an album by its ID, restricted to albums this app itself created — Google removed access to a user's full pre-existing Photos library in March 2025. Returns the album's title, product URL, whether it's editable, its media item count, and cover photo details. Use get_album to look up one known album. Use list_albums to browse the albums this app has created. Requires an album ID from a prior list_albums or create_album call; albums created outside this app are not retrievable.

    Inputs

    album_idstringrequired
    Identifier of the album to retrieve. Must be an album created by this app — albums from the user's broader Google Photos library are not accessible via this API. Obtain the ID from a prior create_album or list_albums call.

    Also accepts schema_version and tool_version to pin a version.

  • googlephotos_get_media_itemRetrieve a single media item by its ID, restricted to media this app itself created or uploaded — Google removed access to a user's full pre-existing Photos library in March 2025.Read-only

    Get Media Item

    Retrieve a single media item by its ID, restricted to media this app itself created or uploaded — Google removed access to a user's full pre-existing Photos library in March 2025. Returns the item's filename, MIME type, a temporary base URL for viewing or downloading it, creation time, dimensions, and photo/video technical metadata. Use get_media_item to look up one known item by ID. Use list_media_items to browse this app's media, batch_get_media_items to fetch several at once, or search_media_items to filter it. Requires a media item ID from a prior list_media_items, search_media_items, or batch_create_media_items call.

    Inputs

    media_item_idstringrequired
    Identifier of the media item to retrieve. Must be a media item this app created or uploaded — items from the user's broader Google Photos library are not accessible via this API. Obtain the ID from a prior list_media_items, search_media_items, or batch_create_media_items call.

    Also accepts schema_version and tool_version to pin a version.

  • googlephotos_get_picker_sessionCheck the status of a Google Photos Picker session created by create_picker_session.Read-only

    Get Picker Session

    Check the status of a Google Photos Picker session created by create_picker_session. Returns mediaItemsSet: true once the user has finished picking media in their browser — poll this tool (using the interval in the session's pollingConfig) until it flips true, then call list_picker_media_items with the same session id. Also returns the session's pickerUri and expireTime.

    Inputs

    session_idstringrequired
    Identifier of the picker session to check, as returned in the id field of create_picker_session's response.

    Also accepts schema_version and tool_version to pin a version.

  • googlephotos_list_albumsList the albums this app has created in Google Photos, one page at a time.Read-only

    List Albums

    List the albums this app has created in Google Photos, one page at a time. Google removed access to a user's full pre-existing Photos library in March 2025, so only albums this app created are ever returned — albums made in the Google Photos app itself, or by other apps, cannot appear here. Returns each album's id, title, product URL, editability, media item count, and cover photo, plus a token for the next page when more results exist. Use list_albums to browse or locate an album's id; use get_album when the id is already known.

    Inputs

    exclude_non_app_created_databoolean
    If true, asks the API to exclude albums not created by this app. Included for completeness, but this connection only ever holds the photoslibrary.readonly.appcreateddata scope, which already restricts every result to app-created albums — so this flag has no practical effect here.
    page_sizeinteger
    Maximum number of albums to return per page. Defaults to 20 if omitted; the API caps this at 50.
    page_tokenstring
    A page token from a previous list_albums call's nextPageToken, used to fetch the next page of results.

    Also accepts schema_version and tool_version to pin a version.

  • googlephotos_list_media_itemsList media items this app has created or uploaded, paginated in reverse-chronological creation order.Read-only

    List Media Items

    List media items this app has created or uploaded, paginated in reverse-chronological creation order. Returns each item's filename, MIME type, a temporary base URL for viewing or downloading it, creation time, dimensions, and photo/video technical metadata, plus a token for the next page. Use list_media_items to browse this app's media without filters. Use search_media_items to filter by date, content category, media type, or favorites, or get_media_item/batch_get_media_items to fetch specific known items. Note: Google removed access to a user's full pre-existing Photos library in March 2025 — only media this app itself created or uploaded is returned.

    Inputs

    page_sizeinteger
    Maximum number of media items to return per page. Defaults to 25 if omitted; the maximum allowed value is 100.
    page_tokenstring
    Pagination token from a previous list_media_items response's nextPageToken, used to fetch the next page of results. Omit to fetch the first page.

    Also accepts schema_version and tool_version to pin a version.

  • googlephotos_list_picker_media_itemsRetrieve the photos and videos the user picked during a Google Photos Picker session (from create_picker_session).Read-only

    List Picker Media Items

    Retrieve the photos and videos the user picked during a Google Photos Picker session (from create_picker_session). Only call this once get_picker_session reports mediaItemsSet: true — otherwise the list will be empty even though the session is still valid. Returns each item's type (photo or video), a temporary base URL to fetch its bytes, its filename and MIME type, and technical metadata. Unlike every other tool in this connector, these can be any items from the user's full Google Photos library, not just app-created ones.

    Inputs

    session_idstringrequired
    Identifier of the picker session whose picked items to list, as returned in the id field of create_picker_session's response.
    page_sizeinteger
    Maximum number of items to return per page. Google defaults to 50 if omitted; values above 100 are capped to 100.
    page_tokenstring
    Pagination token from a previous list_picker_media_items call's nextPageToken, to fetch the next page.

    Also accepts schema_version and tool_version to pin a version.

  • googlephotos_search_media_itemsSearch this app's media items by album, date range, content category, media type, or favorite status — Google removed access to a user's full pre-existing Photos library in March 2025, so results are limited to media this app itself created or uploaded.Read-only

    Search Media Items

    Search this app's media items by album, date range, content category, media type, or favorite status — Google removed access to a user's full pre-existing Photos library in March 2025, so results are limited to media this app itself created or uploaded. Returns a page of matching media items (filename, MIME type, a temporary base URL, creation time, dimensions, and photo/video metadata) plus a token for the next page. Use search_media_items to filter by date, content category, media type, or favorites, or to list everything in one specific album. Use list_media_items for an unfiltered chronological browse, or get_media_item/batch_get_media_items for specific known items. Note: album_id and the other filter fields (dates, categories, media type, favorites, archived) are mutually exclusive in a single call — searching within one album cannot be combined with the other filters.

    Inputs

    album_idstring
    ID of a single album (created by this app) to list all media items from. Mutually exclusive with the filter fields below (start_date, end_date, included_content_categories, excluded_content_categories, media_types, include_favorites_only, include_archived_media, exclude_non_app_created_data) — set either album_id or filters, not both.
    end_datestring
    End of the date range to search, in YYYY-MM-DD form (calendar date, not a timestamp). If provided together with start_date, matches items created on or between the two dates. If provided alone, matches items created on that single day. This tool supports one contiguous date range per call, not a list of discrete dates.
    exclude_non_app_created_databoolean
    When true, excludes media items not created by this app from the results (relevant mainly for shared albums). Defaults to the API's own behavior when omitted.
    excluded_content_categoriesarray
    Content categories to exclude from results. Valid values: NONE, LANDSCAPES, RECEIPTS, CITYSCAPES, LANDMARKS, SELFIES, PEOPLE, PETS, WEDDINGS, BIRTHDAYS, DOCUMENTS, TRAVEL, ANIMALS, FOOD, SPORT, NIGHT, PERFORMANCES, WHITEBOARDS, SCREENSHOTS, UTILITY, ARTS, CRAFTS, FASHION, HOUSES, GARDENS, FLOWERS, HOLIDAYS.
    include_archived_mediaboolean
    When true, includes media items the user has archived in their Google Photos library. Defaults to false (archived items excluded) when omitted.
    include_favorites_onlyboolean
    When true, restricts results to media items the user has marked as a favorite. Leave unset or false to include all media regardless of favorite status.
    included_content_categoriesarray
    Content categories to restrict results to. Valid values: NONE, LANDSCAPES, RECEIPTS, CITYSCAPES, LANDMARKS, SELFIES, PEOPLE, PETS, WEDDINGS, BIRTHDAYS, DOCUMENTS, TRAVEL, ANIMALS, FOOD, SPORT, NIGHT, PERFORMANCES, WHITEBOARDS, SCREENSHOTS, UTILITY, ARTS, CRAFTS, FASHION, HOUSES, GARDENS, FLOWERS, HOLIDAYS.
    media_typesarray
    Restrict results to photos, videos, or both. Valid values: ALL_MEDIA, PHOTO, VIDEO.
    page_sizeinteger
    Maximum number of media items to return per page. Defaults to 25 if omitted; the maximum allowed value is 100.
    page_tokenstring
    Pagination token from a previous search_media_items response's nextPageToken, used to fetch the next page of the same search. Omit to fetch the first page.
    start_datestring
    Start of the date range to search, in YYYY-MM-DD form (calendar date, not a timestamp). If provided together with end_date, matches items created on or between the two dates. If provided alone, matches items created on that single day. This tool supports one contiguous date range per call, not a list of discrete dates.

    Also accepts schema_version and tool_version to pin a version.

All 23 in Media