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"
}
}
如果请求成功，则该响应将返回一个影集：
{
"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
此请求通过包含字段掩码（由网址中的 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 成功状态。
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
}
如未另行说明，那么本页面中的内容已根据知识共享署名 4.0 许可获得了许可，并且代码示例已根据 Apache 2.0 许可获得了许可。有关详情，请参阅 Google 开发者网站政策。Java 是 Oracle 和/或其关联公司的注册商标。
最后更新时间 (UTC)：2025-08-29。
[null,null,["最后更新时间 (UTC)：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```"]]
