직접 링크 및 메타데이터와 같은 필수 세부정보가 포함된 mediaItem 객체를 검색합니다.
라이브러리와 앨범 콘텐츠를 나열하면 미디어 항목 목록이 반환됩니다.
앨범에 포함된 보강은 포함되지 않습니다. 미디어 항목은 사진, 동영상 또는 기타 미디어를 나타냅니다. mediaItem에는 항목으로 연결되는 직접 링크, Google 포토의 항목으로 연결되는 링크, 기타 관련 메타데이터가 포함됩니다. 자세한 내용은 미디어 항목 액세스 및 mediaItems를 참고하세요.
반환된 각 앨범에는 앨범 콘텐츠 목록에 표시된 대로 앨범의 콘텐츠를 검색하는 데 사용할 수 있는 ID가 있습니다. 또한 제목과 포함된 미디어 항목 수가 포함됩니다.
productUrl는 사용자가 열 수 있는 Google 포토의 앨범을 가리킵니다.
coverPhotoMediaItemId에는 이 앨범의 표지 사진을 나타내는 미디어 항목 ID가 포함됩니다. 이 표지 이미지에 액세스하려면 coverPhotoBaseUrl을(를) 사용하세요.
추가 매개변수를 지정하지 않고 coverPhotoBaseUrl를 직접 사용하면 안 됩니다.
응답에는 nextPageToken도 포함됩니다. 자세한 내용은 페이지로 나누기를 참고하세요.
빈 앨범의 응답은 mediaItemsCount 및 coverPhotoMediaItemId가 기본적으로 0으로 설정되고 REST 응답에서 생략된다는 점에서 다릅니다. 또한 coverPhotoBaseUrl는 기본 자리표시자 이미지를 가리킵니다.
앱에서 만든 라이브러리 콘텐츠 표시
앱에서 만든 사용자의 Google 포토 라이브러리에 있는 모든 미디어 항목을 나열할 수 있습니다. 보관처리된 항목과 삭제된 항목은 제외됩니다. 필터를 적용하여 콘텐츠, 날짜, 기타 속성을 기준으로 미디어 항목을 표시할 수 있습니다.
응답에는 최근 항목부터 오래된 항목 순으로 정렬된 미디어 항목 목록이 포함됩니다.
자세한 내용은 mediaItems를 참고하세요. 또한 nextPageToken도 포함됩니다. 이 내용은 페이지로 나누기에 자세히 설명되어 있습니다.
앨범 콘텐츠 목록
앨범의 모든 미디어 항목을 나열하려면 검색 요청에 albumId 필드를 추가합니다. albumId에 대한 자세한 내용은 앨범 표시를 참고하세요. albumId가 유효하지 않으면 Bad Request 오류가 반환됩니다. ID가 유효하지만 인증된 사용자의 앨범이 없는 경우 Not Found 오류가 반환됩니다. 오류 처리에 관한 자세한 내용은 성능 도움말 및 권장사항을 참고하세요.
응답에는 nextPageToken 및 미디어 항목 목록이 포함됩니다. 라이브러리 콘텐츠를 나열할 때와 달리 미디어 항목은 앨범 내 순서에 따라 반환됩니다. 자세한 내용은 mediaItems 및 페이지로 나누기를 참고하세요. 사용자는 Google 포토 인터페이스에서 주문을 수정할 수 있습니다.
albumId로 설정하면 앨범 콘텐츠를 나열할 때 필터를 적용할 수 없습니다.
이렇게 하면 Bad Request 오류가 발생합니다.
REST의 페이징
성능을 개선하기 위해 많은 수의 결과를 반환하는 메서드(예: 목록 메서드)는 응답을 페이지로 나눌 수 있습니다. 각 페이지의 최대 결과 수는 pageSize 매개변수로 지정됩니다.
mediaItems.search 및 mediaItems.list 호출의 경우 기본 페이지 크기는 항목 25개입니다. 이 페이지 크기는 응답 크기와 유효노출률 사이의 균형을 이루므로 권장됩니다. 미디어 항목 검색 및 목록 요청의 최대 페이지 크기는 100개 항목입니다.
앨범을 나열할 때 기본 및 권장 페이지 크기는 앨범 20개이며 최대 50개까지 가능합니다.
사용 가능한 결과 수가 페이지 크기보다 크면 응답에 nextPageToken가 포함되며, 이는 애플리케이션에 서버에서 가져올 결과가 더 있음을 나타냅니다.
예
다음 예와 같이 pageToken 매개변수의 후속 요청에 nextPageToken를 추가해야 합니다. pageToken를 작업에 필요한 다른 매개변수와 함께 요청 본문 또는 쿼리 매개변수로 지정합니다.
[[["이해하기 쉬움","easyToUnderstand","thumb-up"],["문제가 해결됨","solvedMyProblem","thumb-up"],["기타","otherUp","thumb-up"]],[["필요한 정보가 없음","missingTheInformationINeed","thumb-down"],["너무 복잡함/단계 수가 너무 많음","tooComplicatedTooManySteps","thumb-down"],["오래됨","outOfDate","thumb-down"],["번역 문제","translationIssue","thumb-down"],["샘플/코드 문제","samplesCodeIssue","thumb-down"],["기타","otherDown","thumb-down"]],["최종 업데이트: 2025-08-29(UTC)"],[[["\u003cp\u003eThe Google Photos Library API allows you to access and list media items created by your application, including photos and videos.\u003c/p\u003e\n"],["\u003cp\u003eYou can list media items from specific app-created albums or the entire app-created library, applying filters (date, content category, media type) to refine results.\u003c/p\u003e\n"],["\u003cp\u003eWhen listing media items, you receive \u003ccode\u003emediaItem\u003c/code\u003e objects containing essential details like direct links and metadata; however, remember to store the \u003ccode\u003emediaItem\u003c/code\u003e ID and re-request details when needed to avoid caching issues.\u003c/p\u003e\n"],["\u003cp\u003eUtilize pagination to efficiently handle large result sets by using the \u003ccode\u003enextPageToken\u003c/code\u003e in subsequent requests to retrieve additional media items or albums.\u003c/p\u003e\n"]]],["To access app-created media, the `photoslibrary.readonly.appcreateddata` scope is required. You can list media items from specific app-created albums or the entire app-created library using `mediaItems.list` or `mediaItems.search`. Filtering by date, content category, or media type is available when listing the library, but not albums. Use `albums.list` to get album details like ID, title, and `coverPhotoBaseUrl`. Pagination is used for large datasets, using the `nextPageToken` for subsequent requests, with recommended and maximum page sizes.\n"],null,["# List app-created media items and albums\n\nRequired authorization scopes\n-----------------------------\n\nListing app-created content requires the `photoslibrary.readonly.appcreateddata`\nscope. For more information on scopes, see [Authorization\nscopes](/photos/overview/authorization).\n\nOverview\n--------\n\nThe Library API lets you to list and access media items that your application\nhas created.\n\nSome key features of listing media items include the following:\n\n- List media items from specific app-created albums or the entire app-created library\n- [Apply filters (date, content category, media\n type)](/photos/library/guides/apply-filters) when listing to narrow your\n results\n\n | **Note:** Filters are not supported when you list items from albums.\n- Retrieve [`mediaItem`](/photos/library/reference/rest/v1/mediaItems) objects\n with essential details like direct links and metadata.\n\nListing the library and album contents returns a list of media items.\n[Enrichments](/photos/library/guides/add-enrichments) that are part of an album\naren't included. Media items describe a photo, video, or other media. A\n`mediaItem` includes a direct link to the item, a link to the item in\nGoogle Photos, and other relevant metadata. For more information, see\n[Access media items](/photos/library/guides/access-media-items) and\n[`mediaItems`](/photos/library/reference/rest/v1/mediaItems).\n| **Caution:** Don't cache user photos and videos. Instead, store the media item `id` and request its details again when you need them. Images may change, and direct access through the `baseUrl` expires after 60 minutes. For more information, see [Access media items](/photos/library/guides/access-media-items).\n\nList app-created albums\n-----------------------\n\nYou can list albums that have been created by your app using\n[`albums.list`](/photos/library/reference/rest/v1/albums/list). \n\n### REST\n\nHere is a sample request: \n\n```\nGET https://photoslibrary.googleapis.com/v1/albums\n```\n\nThe request returns the following result: \n\n```restructuredtext\n{\n \"albums\": [\n {\n \"id\": \"album-id\",\n \"title\": \"album-title\",\n \"productUrl\": \"album-product-url\",\n \"coverPhotoBaseUrl\": \"album-cover-base-url_do-not-use-directly\",\n \"coverPhotoMediaItemId\": \"album-cover-media-item-id\",\n \"isWriteable\": \"whether-you-can-write-to-this-album\",\n \"mediaItemsCount\": \"number-of-media-items-in-album\"\n },\n ...\n ],\n \"nextPageToken\": \"\u003cvar translate=\"no\"\u003etoken-for-pagination\u003c/var\u003e\"\n}\n```\n\nEach returned album has an ID that can be used to retrieve the contents of the\nalbum as shown in [List album contents](#listing-album-contents). It also\nincludes the title and the number of media items it contains.\n\nThe `productUrl` points to the album in Google Photos that can be a\nopened by the user.\n\nThe `coverPhotoMediaItemId` contains the [media item\nID](/photos/library/reference/rest/v1/mediaItems) that represents the cover\nphoto of this album. To the access this cover image, use `coverPhotoBaseUrl`.\nYou shouldn't use the `coverPhotoBaseUrl` directly without specifying\n[additional parameters](/photos/library/guides/access-media-items#base-urls).\n\nThe response also contains a `nextPageToken`. For more information, see\n[Pagination](#pagination).\n\nThe response for empty albums varies in that, `mediaItemsCount` and\n`coverPhotoMediaItemId` are set to 0 by default and are omitted from the REST\nresponse. Also note that `coverPhotoBaseUrl` points to a default placeholder\nimage.\n\nList app-created library contents\n---------------------------------\n\nYou can list all the media items from the user's Google Photos library\nthat were created by your app.. This excludes archived and deleted items. You\ncan list media items based on their content, date, and other properties by\n[applying filters](/photos/library/guides/apply-filters).\n\nTo list a media items, call\n[`mediaItems.list`](/photos/library/reference/rest/v1/mediaItems/list). \n\n### REST\n\nHere is a sample request: \n\n```restructuredtext\nGET https://photoslibrary.googleapis.com/v1/mediaItems\nContent-type: application/json\nAuthorization: Bearer \u003cvar translate=\"no\"\u003eoauth2-token\u003c/var\u003e\n{\n \"pageSize\": \"100\",\n}\n```\n\nThe GET request returns the following response: \n\n```restructuredtext\n{\n \"mediaItems\": [\n ...\n ],\n \"nextPageToken\": \"\u003cvar translate=\"no\"\u003etoken-for-pagination\u003c/var\u003e\"\n}\n```\n\nThe response contains a list of media items, ordered from most to least recent.\nFor more information, see\n[`mediaItems`](/photos/library/reference/rest/v1/mediaItems#MediaItem). It also\ncontains a `nextPageToken`, which is described in more detail in\n[Pagination](#pagination).\n\nList album contents\n-------------------\n\nTo list all of the media items in an album, add the `albumId` field to your\nsearch request. For more information about `albumId`, see [Listing\nalbums](#listing-albums). If the `albumId` is invalid, a `Bad Request` error is\nreturned. If the ID is valid, but the album doesn't exist for the authenticated\nuser, a `Not Found` error is returned. For more details regarding error\nhandling,see [Performance tips](/photos/library/guides/performance-tips) and\n[Best practices](/photos/library/guides/best-practices). \n\n### REST\n\nHere is a sample request: \n\n```restructuredtext\nPOST https://photoslibrary.googleapis.com/v1/mediaItems:search\nContent-type: application/json\nAuthorization: Bearer \u003cvar translate=\"no\"\u003eoauth2-token\u003c/var\u003e\n{\n \"pageSize\": \"100\",\n \"albumId\": \"album-id\"\n}\n```\n\nThe POST request returns the following response: \n\n```restructuredtext\n{\n \"mediaItems\": [\n ...\n ],\n \"nextPageToken\": \"\u003cvar translate=\"no\"\u003etoken-for-pagination\u003c/var\u003e\"\n}\n```\n\nThe response contains a `nextPageToken` and the list of media items. Unlike when\nlisting library contents, the media items are returned by their order in the\nalbum. For more details, see\n[`mediaItems`](/photos/library/reference/rest/v1/mediaItems) and\n[Pagination](#pagination). The user can edit the order in the\nGoogle Photos interface.\n\nIf the `albumId` is set, you can't apply a filter when listing album contents.\nDoing so results in a `Bad Request` error.\n\nPagination for REST\n-------------------\n\nTo improve performance, methods that return a large number of results (such as\nlist methods) may paginate the response. The maximum number of results in each\npage is given by the `pageSize` parameter.\n\nFor calls to `mediaItems.search` and `mediaItems.list`, the default page size is\n25 items. We recommend this page size because it strikes a balance between the\nsize of the response and the fill rate. The maximum page size for media item\nsearch and list requests is 100 items.\n\nThe default and recommended page size when listing albums is 20 albums, with a\nmaximum of 50 albums.\n\nWhen the number of available results is greater than the page size, the response\nincludes a `nextPageToken`, which indicates to your application that there are\nmore results to be fetched from the server.\n| **Note:** The `pageSize` parameter is a maximum --- fewer results might be returned than are requested.\n\n### Example\n\nYou must append the `nextPageToken` to subsequent requests in the parameter\n`pageToken`, as shown in the following example. Specify the `pageToken` together\nwith other parameters required for the operation, either in the body of the\nrequest, or as a query parameter.\n\n#### Request #1\n\n```text\n{\n \"pageSize\": \"5\",\n \"filters\": { … }\n}\n```\n\n#### Response #1\n\n```text\n{\n \"mediaItem\": [ … ],\n \"nextPageToken\": \"next-page-token\"\n}\n```\n\n#### Request #2\n\n```text\n{\n \"pageSize\": \"5\",\n \"filters\": { … },\n \"pageToken\": \"page-token\"\n}\n```\n\n#### Response #2\n\n```text\n{\n \"mediaItem\": [ … ],\n \"nextPageToken\": \"next-page-token\"\n}\n```\n\nContinue this pattern until there are no more `nextPageToken` objects.\n\nThe `nextPageToken` is only valid for the same request. If any parameters are\nchanged, a previously used `nextPageToken` shouldn't be used in the same\nrequest.\n| **Note:** The existence of `nextPageToken` is the only indicator of whether or not there are more results to be fetched from the server. Don't count the number of results to determine if you should use your `nextPageToken`. A request may return fewer results than requested in the page size. If a `nextPageToken` is present, you can send a request for more results after your initial request."]]
