2025 年 4 月 1 日，Library API 中的部分範圍已遭到移除。
詳情請參閱這篇文章。
管理相簿
透過集合功能整理內容
你可以依據偏好儲存及分類內容。
在 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"
}
}
如果成功，回應會傳回 album：
{
"productUrl": "album-product-url",
"id": "album-id",
"title": "album-title",
"isWriteable": "whether-you-can-write-to-this-album"
}
擷取相簿詳細資料
如要擷取應用程式建立的現有相簿詳細資料，請呼叫 albums.get，並加入要擷取的相簿 albumId。
這個呼叫會傳回 album。
REST
以下是 GET 要求的標頭：
GET https://photoslibrary.googleapis.com/v1/albums/{albumId}
Content-type: application/json
Authorization: Bearer oauth2-token
要求主體如下所示：
{
"albumId": album-id
}
如果成功，回應會傳回 album：
{
"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
}
變更相簿標題和封面相片
如要變更相簿標題或封面相片，請使用相簿的 ID 建立 album update
call，並在要求中加入新的標題或新封面相片的媒體項目 ID。您必須使用 photoslibrary.edit.appcreateddata authorization 範圍才能進行變更。
相簿名稱長度不可超過 500 個字元。封面媒體項目擁有者必須為相簿擁有者，且屬於其封面。
REST
以下 PATCH 要求標頭可更新相簿的 title 和 coverPhotomediaItemId。
PATCH https://photoslibrary.googleapis.com/v1/albums/album-id?updateMask=title&updateMask=coverPhotoMediaItemId
這項要求會透過網址中的 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 個媒體項目。如果要求新增的項目超過此限制，系統就會失敗。
如要將媒體項目新增至相簿，請使用媒體項目和相簿的 ID 呼叫 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，將應用程式建立的媒體項目移除至應用程式建立的相簿。
如果指定無效的媒體項目，整個要求都會失敗。系統不支援部分成功。
如要從相簿中移除媒體項目，請使用媒體項目和相簿的 ID 呼叫 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 成功狀態。
Java
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
}
除非另有註明，否則本頁面中的內容是採用創用 CC 姓名標示 4.0 授權，程式碼範例則為阿帕契 2.0 授權。詳情請參閱《Google Developers 網站政策》。Java 是 Oracle 和/或其關聯企業的註冊商標。
上次更新時間：2025-08-29 (世界標準時間)。
[null,null,["上次更新時間：2025-08-29 (世界標準時間)。"],[[["\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```"]]
