앨범 관리
컬렉션을 사용해 정리하기
내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.
Google 포토에서 앨범을 사용하여 사진 및 기타 미디어 항목을 정리할 수 있습니다.
미디어 항목은 하나 이상의 앨범과 연결될 수 있습니다. 미디어 항목을 앨범과 연결하려면 먼저 앨범을 만들어야 합니다.
필수 승인 범위
앨범을 만들려면 photoslibrary.appendonly 범위가 필요합니다.
앨범을 만든 후 앨범의 제목이나 표지 사진을 변경하려면 photoslibrary.edit.appcreateddata 범위가 필요합니다.
범위에 관한 자세한 내용은 승인 범위를 참고하세요.
새 앨범 만들기
앨범을 만들려면 albums.create를 호출하고 title를 포함합니다. title는 500자(영문 기준)로 제한됩니다.
통화가 앨범을 반환합니다. 앱은 이 정보에서 앨범 ID를 저장하고 특정 앨범에 미디어 항목을 업로드하는 데 사용할 수 있습니다.
REST
다음은 POST 요청의 헤더입니다.
POST https://photoslibrary.googleapis.com/v1/albums
Content-type: application/json
Authorization: Bearer oauth2-token
요청 본문은 다음과 같습니다.
{
"album": {
"title": "new-album-title"
}
}
성공하면 응답은 앨범을 반환합니다.
{
"productUrl": "album-product-url",
"id": "album-id",
"title": "album-title",
"isWriteable": "whether-you-can-write-to-this-album"
}
앨범 세부정보 검색
앱에서 만든 기존 앨범의 세부정보를 검색하려면 albums.get를 호출하고 가져오려는 앨범의 albumId를 포함합니다.
이 호출은 앨범을 반환합니다.
REST
다음은 GET 요청의 헤더입니다.
GET https://photoslibrary.googleapis.com/v1/albums/{albumId}
Content-type: application/json
Authorization: Bearer oauth2-token
요청 본문은 다음과 같습니다.
{
"albumId": album-id
}
성공하면 응답은 앨범을 반환합니다.
{
"id": album-id,
"title": album-title,
"productUrl": album-product-url,
"mediaItemsCount": media-items-count,
"coverPhotoBaseUrl": cover-photo-base-url,
"coverPhotoMediaItemId": cover-photo-media-item-id
}
앨범 제목 및 표지 사진 변경하기
앨범 제목이나 표지 사진을 변경하려면 앨범 식별자로 album update
call를 만들고 요청에 새 제목 또는 새 표지 사진의 미디어 항목 ID를 포함합니다. 변경하려면 photoslibrary.edit.appcreateddata 승인 범위를 사용해야 합니다.
앨범 제목은 500자(영문 기준) 이하여야 합니다. 커버 미디어 항목은 앨범 소유자가 소유하고 있어야 하며 커버가 될 앨범에 속해야 합니다.
REST
다음은 앨범의 title 및 coverPhotomediaItemId를 업데이트하는 PATCH 요청 헤더입니다.
PATCH https://photoslibrary.googleapis.com/v1/albums/album-id?updateMask=title&updateMask=coverPhotoMediaItemId
이 요청은 URL의 updateMask 매개변수로 표시되는 필드 마스크를 포함하여 업데이트되는 속성을 결정합니다. 업데이트되는 각 앨범 속성에 updateMask 매개변수를 전달해야 합니다.
업데이트하는 각 속성에 대해 요청 본문에 세부정보를 포함합니다.
{
"title": "new-album-title",
"coverPhotoMediaItemId": "new-cover-media-item-id"
}
성공하면 응답은 업데이트된 album 세부정보를 반환합니다.
{
"id": "album-id",
"title": "new-album-title",
"productUrl": "album-product-url",
"isWriteable": "true-if-user-can-write-to-this-album",
"mediaItemsCount": "number-of-media-items-in-album",
"coverPhotoBaseUrl": "cover-photo-base-url_use-only-with-parameters",
"coverPhotoMediaItemId": "new-cover-media-item-id"
}
앨범에 미디어 항목 추가
albums.batchAddMediaItems를 호출하여 앱에서 만든 미디어 항목을 앱에서 만든 앨범에 추가할 수 있습니다.
미디어 항목은 이 호출에 지정된 순서대로 앨범 끝에 추가됩니다.
잘못된 미디어 항목이나 앨범을 지정하면 전체 요청이 실패합니다.
부분 성공은 지원되지 않습니다.
각 앨범에는 최대 20,000개의 미디어 항목을 포함할 수 있습니다. 이 한도를 초과하는 항목을 추가하라는 요청은 실패합니다.
앨범에 미디어 항목을 추가하려면 미디어 항목과 앨범의 식별자를 사용하여 albums.batchAddMediaItems를 호출합니다.
REST
다음은 POST 요청의 헤더입니다.
POST https://photoslibrary.googleapis.com/v1/albums/album-id:batchAddMediaItems
Content-type: application/json
Authorization: Bearer oauth2-token
요청 본문은 다음과 같습니다.
{
"mediaItemIds": [
"media-item-id",
"another-media-item-id",
...
]
}
성공하면 응답은 빈 JSON 응답과 HTTP 성공 상태를 반환합니다.
앨범에서 미디어 항목 삭제하기
albums.batchRemoveMediaItems를 호출하여 앱에서 만든 앨범에 앱에서 만든 미디어 항목을 삭제할 수 있습니다.
잘못된 미디어 항목을 지정하면 전체 요청이 실패합니다. 부분 성공은 지원되지 않습니다.
앨범에서 미디어 항목을 삭제하려면 미디어 항목 및 앨범의 식별자를 사용하여 albums.batchRemoveMediaItems를 호출합니다.
REST
다음은 POST 요청의 헤더입니다.
POST https://photoslibrary.googleapis.com/v1/albums/album-id:batchRemoveMediaItems
Content-type: application/json
Authorization: Bearer oauth2-token
요청 본문은 다음과 같습니다.
{
"mediaItemIds": [
"media-item-id",
"another-media-item-id",
...
]
}
성공하면 응답이 빈 JSON 응답과 HTTP 성공 상태를 반환합니다.
자바
try {
// List of media item IDs to remove
List<String> mediaItemIds = Arrays
.asList("MEDIA_ITEM_ID", "ANOTHER_MEDIA_ITEM_ID");
// ID of the album to remove media items from
String albumId = "ALBUM_ID";
// Remove all given media items from the album
photosLibraryClient.batchRemoveMediaItemsFromAlbum(albumId, mediaItemIds);
} catch (ApiException e) {
// An exception is thrown if the media items could not be removed
}
PHP
try {
// List of media item IDs to remove
$mediaItemIds = ["MEDIA_ITEM_ID", "ANOTHER_MEDIA_ITEM_ID"];
// ID of the album to remove media items from
$albumId = "ALBUM_ID";
// Remove all given media items from the album
$response = $photosLibraryClient->batchRemoveMediaItemsFromAlbum($albumId, $mediaItemIds);
} catch (\Google\ApiCore\ApiException $e) {
// Handle Error
}
달리 명시되지 않는 한 이 페이지의 콘텐츠에는 Creative Commons Attribution 4.0 라이선스에 따라 라이선스가 부여되며, 코드 샘플에는 Apache 2.0 라이선스에 따라 라이선스가 부여됩니다. 자세한 내용은 Google Developers 사이트 정책을 참조하세요. 자바는 Oracle 및/또는 Oracle 계열사의 등록 상표입니다.
최종 업데이트: 2025-08-29(UTC)
[null,null,["최종 업데이트: 2025-08-29(UTC)"],[[["\u003cp\u003eIn Google Photos, albums are used to organize photos and media items, with each item able to belong to multiple albums.\u003c/p\u003e\n"],["\u003cp\u003eYou can create, retrieve details of, and modify albums using the Google Photos Library API.\u003c/p\u003e\n"],["\u003cp\u003eThe API also allows you to add and remove media items from albums, managing their association.\u003c/p\u003e\n"],["\u003cp\u003eDifferent authorization scopes are required for creating albums and for changing their titles or cover photos, ensuring controlled access.\u003c/p\u003e\n"],["\u003cp\u003eEach album has a limit of 20,000 media items, and requests exceeding this limit will fail.\u003c/p\u003e\n"]]],["Google Photos allows album creation and management via API calls. Creating an album requires the `photoslibrary.appendonly` scope, while editing needs `photoslibrary.edit.appcreateddata`. Albums are created using `albums.create` with a title (max 500 characters). Details are retrieved with `albums.get` using the `albumId`. Titles and cover photos are updated with `albums.patch` by specifying the parameters to be modified. Media items are added and removed using `albums.batchAddMediaItems` and `albums.batchRemoveMediaItems` respectively, using media item IDs.\n"],null,["# Manage albums\n\nIn Google Photos, you can organize photos and other media items using albums.\nA media item can be associated with one or more albums. To start associating\nmedia items with an album, you need to create the album first.\n\nRequired authorization scopes\n-----------------------------\n\nCreating albums requires the `photoslibrary.appendonly` scope.\n\nChanging the title or cover photo of albums after their creation requires the\n`photoslibrary.edit.appcreateddata` scope.\n\nFor more information on scopes, see [Authorization\nscopes](/photos/overview/authorization).\n\nCreate a new album\n------------------\n\nTo create an album, call\n[`albums.create`](/photos/library/reference/rest/v1/albums/create) and include\nthe `title`. Note that `title` is restricted to 500 characters.\n\nThe call returns an [album](/photos/library/reference/rest/v1/albums). Your app\ncan store the album ID from this information and use it for [uploading media\nitems](/photos/library/guides/upload-media) to the specific album. \n\n### REST\n\nHere is a header for a POST request: \n\n```\nPOST https://photoslibrary.googleapis.com/v1/albums\nContent-type: application/json\nAuthorization: Bearer oauth2-token\n```\n\nThe request body looks like this: \n\n```restructuredtext\n{\n \"album\": {\n \"title\": \"new-album-title\"\n }\n}\n```\n\nIf successful, the response returns an\n[album](/photos/library/reference/rest/v1/albums): \n\n```restructuredtext\n{\n \"productUrl\": \"album-product-url\",\n \"id\": \"album-id\",\n \"title\": \"album-title\",\n \"isWriteable\": \"whether-you-can-write-to-this-album\"\n}\n```\n\nRetrieve album details\n----------------------\n\nTo retrieve the details of an existing album created by your app, call\n[`albums.get`](/photos/library/reference/rest/v1/albums/get) and include the\n`albumId` of the album you want to fetch.\n\nThe call returns an [album](/photos/library/reference/rest/v1/albums). \n\n### REST\n\nHere is a header for a GET request: \n\n```\nGET https://photoslibrary.googleapis.com/v1/albums/{albumId}\nContent-type: application/json\nAuthorization: Bearer oauth2-token\n```\n\nThe request body looks like this: \n\n```restructuredtext\n{\n \"albumId\": album-id\n}\n```\n\nIf successful, the response returns an\n[album](/photos/library/reference/rest/v1/albums): \n\n```restructuredtext\n{\n \"id\": album-id,\n \"title\": album-title,\n \"productUrl\": album-product-url,\n \"mediaItemsCount\": media-items-count,\n \"coverPhotoBaseUrl\": cover-photo-base-url,\n \"coverPhotoMediaItemId\": cover-photo-media-item-id\n}\n```\n\nChange album titles and cover photos\n------------------------------------\n\nTo change an album title or cover photo, make an [`album update\ncall`](/photos/library/reference/rest/v1/albums/patch) with the identifier of\nthe album, and include the new title or the new cover photo's media item ID in\nthe request. You'll need to use the `photoslibrary.edit.appcreateddata`\n[authorization](/photos/library/guides/authorization) scope to make the change.\n\nAlbum titles can be no more than 500 characters in length. Cover media items\nmust be owned by the album owner, and belong to the album they will be a cover\nfor. \n\n### REST\n\nHere's a PATCH request header to update an album's `title` and\n`coverPhotomediaItemId`. \n\n```\nPATCH https://photoslibrary.googleapis.com/v1/albums/album-id?updateMask=title&updateMask=coverPhotoMediaItemId\n```\n\nThis request determines what properties are being updated by including\na field mask, indicated by the `updateMask` parameters in the\nURL. The `updateMask` parameter needs to be passed for each\nalbum property that is being updated.\n\nFor each property you are updating, include its details in\nthe body of the request: \n\n```restructuredtext\n{\n \"title\": \"new-album-title\",\n \"coverPhotoMediaItemId\": \"new-cover-media-item-id\"\n}\n```\n\nIf successful, the response returns the updated `album`\ndetails: \n\n```restructuredtext\n{\n \"id\": \"album-id\",\n \"title\": \"\u003cvar translate=\"no\"\u003enew-album-title\u003c/var\u003e\",\n \"productUrl\": \"album-product-url\",\n \"isWriteable\": \"true-if-user-can-write-to-this-album\",\n \"mediaItemsCount\": \"number-of-media-items-in-album\",\n \"coverPhotoBaseUrl\": \"/photos/library/guides/access-media-items#base-urls\",\n \"coverPhotoMediaItemId\": \"\u003cvar translate=\"no\"\u003enew-cover-media-item-id\u003c/var\u003e\"\n}\n```\n\nAdd media items to an album\n---------------------------\n\nYou can add media items created by your app to albums created by your app by\ncalling\n[`albums.batchAddMediaItems`](/photos/library/reference/rest/v1/albums/batchAddMediaItems).\nMedia items are added to the end of the album in the order given in this call.\n\nThe entire request will fail if an invalid media item or album is specified.\nPartial success is not supported.\n\nEach album can contain up to 20,000 media items. Requests to add more items that\nwould exceed this limit will fail.\n\nTo add media items to an album, call\n[`albums.batchAddMediaItems`](/photos/library/reference/rest/v1/albums/batchAddMediaItems)\nwith the identifiers of the media items and the album. \n\n### REST\n\nHere is a header for a POST request: \n\n```\nPOST https://photoslibrary.googleapis.com/v1/albums/album-id:batchAddMediaItems\nContent-type: application/json\nAuthorization: Bearer oauth2-token\n```\n\nThe request body looks like this: \n\n```restructuredtext\n{\n \"mediaItemIds\": [\n \"media-item-id\",\n \"another-media-item-id\",\n ...\n ]\n}\n```\n\nIf successful, the response returns an empty JSON response and the HTTP\nSuccess status.\n\nRemove media items from an album\n--------------------------------\n\nYou can remove media items created by your app to albums created by your app by\ncalling\n[`albums.batchRemoveMediaItems`](/photos/library/reference/rest/v1/albums/batchRemoveMediaItems).\n\nThe entire request will fail if invalid media items are specified. Partial\nsuccess is not supported.\n\nTo remove media items from an album, call\n[`albums.batchRemoveMediaItems`](/photos/library/reference/rest/v1/albums/batchRemoveMediaItems)\nwith the identifiers of the media items and the album. \n\n### REST\n\nHere is a header for a POST request: \n\n```\nPOST https://photoslibrary.googleapis.com/v1/albums/album-id:batchRemoveMediaItems\nContent-type: application/json\nAuthorization: Bearer oauth2-token\n```\n\nThe request body looks like this: \n\n```restructuredtext\n{\n \"mediaItemIds\": [\n \"media-item-id\",\n \"another-media-item-id\",\n ...\n ]\n}\n```\n\nIf successful, the response returns an empty JSON response and the HTTP\nSuccess status.\n\n### Java\n\n```java\ntry {\n // List of media item IDs to remove\n List\u003cString\u003e mediaItemIds = Arrays\n .asList(\"MEDIA_ITEM_ID\", \"ANOTHER_MEDIA_ITEM_ID\");\n\n // ID of the album to remove media items from\n String albumId = \"ALBUM_ID\";\n\n // Remove all given media items from the album\n photosLibraryClient.batchRemoveMediaItemsFromAlbum(albumId, mediaItemIds);\n\n} catch (ApiException e) {\n // An exception is thrown if the media items could not be removed\n}\n```\n\n### PHP\n\n```php\ntry {\n\n // List of media item IDs to remove\n $mediaItemIds = [\"MEDIA_ITEM_ID\", \"ANOTHER_MEDIA_ITEM_ID\"];\n\n // ID of the album to remove media items from\n $albumId = \"ALBUM_ID\";\n\n // Remove all given media items from the album\n $response = $photosLibraryClient-\u003ebatchRemoveMediaItemsFromAlbum($albumId, $mediaItemIds);\n\n} catch (\\Google\\ApiCore\\ApiException $e) {\n // Handle Error\n}\n```"]]
