2025 年 4 月 1 日，我们移除了 Library API 中的部分镜重。
点击此处了解详情。
添加扩充项
使用集合让一切井井有条
根据您的偏好保存内容并对其进行分类。
扩展项可以让您的应用控制照片在 Google 相册影集中的结构和呈现方式。利用扩展项，您可以通过文本或位置注释向用户展示其他内容，并对讲述同一故事的图片进行排序/分组。
必需的授权范围
如需向应用创建的影集添加丰富内容，需要 photoslibrary.appendonly 范围。如需详细了解镜，请参阅授权范围。
扩充项类型
Google 相册在影集中支持三种类型的丰富内容：文字、地点和地图。
文本扩充项
文本丰富功能是纯文本字符串，可作为注释插入影集。
位置扩充项
位置扩展项是一种表示地点名称的标记，可作为位置注释插入影集。
地图扩充项
地图扩展项是具有指定出发地和目的地的地图，可插入影集。
位置
如需插入媒体内容和影集扩充项，请指定影集中的插入位置。对于媒体项来说，位置是可选的，但必须为影集扩充项指定位置。
只有在创建媒体内容或添加扩充项时，您才能指定位置。影集中的现有媒体内容无法重新排列，因此请务必在添加内容时设置其位置。
影集开头
媒体/扩充项内容可作为绝对定位添加到影集开头。
影集末尾
媒体/扩充项内容可作为绝对定位添加到影集末尾。
在影集中，媒体/扩充项内容可添加到相对于媒体内容后面的第一个位置。
相对于扩展项
在影集中，媒体/扩充项内容可添加到相对于扩充项内容后面的第一个位置。
向影集添加丰富内容
一次只能添加一个扩充项，必须将其添加到影集中的某个位置。
如需为影集添加丰富内容，请调用 albums.addEnrichment。
如果请求成功，则返回扩充项内容的 id，该返回值可用于定位媒体内容或其他扩充项内容。
REST
以下是 POST 请求：
POST https://photoslibrary.googleapis.com/v1/albums/album-id:addEnrichment
Content-type: application/json
Authorization: Bearer oauth2-token
request-body
请求正文包含扩充项内容及其位置：
{
"newEnrichmentItem": {
enrichment-to-be-added
},
"albumPosition": {
position-of-enrichment
}
以下是示例响应：
{
"enrichmentItem": {
"id": "enrichment-item-id",
}
}
支持的丰富功能
文本丰富功能
文本丰富功能包含单个文本字符串（不超过 1000 个字符），如下例所示：
REST
{
"text": "Text to be shown"
}
Java
// Use the NewEnrichmentItemFactory helper to create a text enrichment item
NewEnrichmentItem newEnrichmentItem =
NewEnrichmentItemFactory.createTextEnrichment("text to be shown");
PHP
$newEnrichmentItem = PhotosLibraryResourceFactory::newEnrichmentItemWithText("text to be shown");
位置扩充项
位置扩充项包含任意地点的名称和经纬度定位。locationName 不得超过 500 个字符。
REST
{
"location": {
"locationName": "Australia",
"latlng": {
"latitude": "-21.197",
"longitude": "95.821"
}
}
}
Java
// Use the NewEnrichmentItemFactory helper to create a location enrichment
// with the name, latitude, and longitude of the location
NewEnrichmentItem newEnrichmentItem =
NewEnrichmentItemFactory.createLocationEnrichment("Australia", -21.197, 95.821);
PHP
// Create a new location object and set the name, latitude, and longitude of the location
$newLocation = new Location();
$newLocation->setLocationName("Australia");
$newLocation->setLatlng((new LatLng())->setLatitude(-21.197)->setLongitude(95.821));
$newEnrichmentItem = PhotosLibraryResourceFactory::newEnrichmentItemWithLocation($newLocation);
地图扩充项
地图扩充项会显示两个位置，每个位置都由名称以及经纬度组成。与位置扩充项类似，源站和 destination 中的 locationName 限制为 500 个字符。
REST
{
"origin": {
"locationName": "Australia",
"latlng": {
"latitude": "-21.197",
"longitude": "95.821"
}
},
"destination": {
"locationName": "San Francisco",
"latlng": {
"latitude": "37.757",
"longitude": "122.507"
}
}
}
Java
// Use the NewEnrichmentItemFactory helper to create a map enrichment item for
// an origin and a destination location
NewEnrichmentItem newEnrichmentItem = NewEnrichmentItemFactory.createMapEnrichment(
"Australia", -21.197, 95.821, // origin
"San Francisco", 37.757, 122.507 // destination
);
PHP
// Create two new location objects to create a map enrichment item
// for an origin and a destination location
$locationAustralia = new Location();
$locationAustralia->setLocationName("Australia");
$locationAustralia->setLatlng((new LatLng())->setLatitude(-21.197)->setLongitude(95.821));
$locationSanFrancisco = new Location();
$locationSanFrancisco->setLocationName("San Francisco");
$locationSanFrancisco->setLatlng((new LatLng())->setLatitude(37.757)->setLongitude(122.507));
$newEnrichmentItem =
PhotosLibraryResourceFactory::newEnrichmentItemWithMap($locationAustralia, $locationSanFrancisco);
支持的定位
影集开头
FIRST_IN_ALBUM 位置指的是影集开头。用户首先会看到位于此处的内容：
REST
{
"position": "FIRST_IN_ALBUM",
}
Java
AlbumPosition albumPosition = AlbumPositionFactory.createFirstInAlbum();
PHP
$albumPosition = new AlbumPosition();
$albumPosition->setPosition(PositionType::FIRST_IN_ALBUM);
影集末尾
LAST_IN_ALBUM 位置指的是影集的末尾。用户最后才能看到位于此处的内容。
REST
{
"position": "LAST_IN_ALBUM",
}
Java
AlbumPosition albumPosition = AlbumPositionFactory.createLastInAlbum();
PHP
$albumPosition = new AlbumPosition();
$albumPosition->setPosition(PositionType::LAST_IN_ALBUM);
指定 relativeMediaItem 位置指的是媒体内容的相对位置。这些内容会添加到指定媒体项之后。
REST
{
"position": "after-media-item",
"relativeMediaItemId": "media-item-id"
}
Java
AlbumPosition albumPosition = AlbumPositionFactory.createAfterMediaItem(mediaItemId);
PHP
$albumPosition = PhotosLibraryResourceFactory::albumPositionAfterMediaItem($mediaItemId);
相对于扩展项
指定 relativeEnrichmentItemId 是指相对于扩充项内容的位置。在此情况中，内容将添加到指定扩充项内容的后面。
REST
{
"position": "after-enrichment-item",
"relativeEnrichmentItemId": "enrichment-item-id"
}
Java
AlbumPosition albumPosition = AlbumPositionFactory.createAfterEnrichmentItem(enrichmentItemId);
PHP
$albumPosition = PhotosLibraryResourceFactory::albumPositionAfterEnrichmentItem($enrichmentItemId);
修改扩充项
目前不支持修改丰富内容。不过，在创建扩充项并将其添加到影集后，用户可以通过 Google 相册应用修改扩充项。
如未另行说明，那么本页面中的内容已根据知识共享署名 4.0 许可获得了许可，并且代码示例已根据 Apache 2.0 许可获得了许可。有关详情，请参阅 Google 开发者网站政策。Java 是 Oracle 和/或其关联公司的注册商标。
最后更新时间 (UTC)：2025-08-29。
[null,null,["最后更新时间 (UTC)：2025-08-29。"],[[["\u003cp\u003eEnrichments allow you to add text, location markers, and maps to Google Photos albums for better storytelling and context.\u003c/p\u003e\n"],["\u003cp\u003eYou need the \u003ccode\u003ephotoslibrary.appendonly\u003c/code\u003e scope to use the Enrichments feature within your application.\u003c/p\u003e\n"],["\u003cp\u003eWhen adding enrichments, specify their position relative to other items or the start/end of the album.\u003c/p\u003e\n"],["\u003cp\u003eEnrichments are added one at a time using the \u003ccode\u003ealbums.addEnrichment\u003c/code\u003e API call and cannot be programmatically modified after creation.\u003c/p\u003e\n"],["\u003cp\u003eUsers can manually modify enrichments within the Google Photos app after they have been added.\u003c/p\u003e\n"]]],["Enrichments enhance Google Photos albums with text, location, or map annotations, requiring the `photoslibrary.appendonly` scope. To add an enrichment, use the `albums.addEnrichment` API call, providing the enrichment type and its position. Positions can be at the start, end, or relative to a media or enrichment item, specified by ID. Supported enrichments include text (max 1000 characters), location (name and coordinates), and maps (origin and destination locations). Enrichments are added one at a time, and the server returns its `id`. Existing enrichments cannot be modified through the API.\n"],null,["# Add enrichments\n\nEnrichments let your application control the structure and presentation of\nphotos within an album in Google Photos. They allow you to present the user\nwith additional context through text or location annotations and order/group\nimages that tell a story together.\n\nRequired authorization scope\n----------------------------\n\nAdding enrichments to app-created albums requires the `photoslibrary.appendonly`\nscope. For more information on scopes, see [Authorization\nscopes](/photos/overview/authorization).\n\nEnrichment types\n----------------\n\nGoogle Photos supports three types of enrichments in albums: text,\nlocations, and maps.\n\n### Text enrichments\n\nA text enrichment is a plain text string that can be inserted to annotate the\nalbum.\n\n### Location enrichments\n\nA location enrichment is a marker and the name of the place that can be inserted\nto annotate a location.\n\n### Map enrichments\n\nA map enrichment is a map with a specified origin and destination that can be\ninserted in the album.\n\nPositions\n---------\n\nTo insert media items and album enrichments, specify the position of the album.\nA position is optional for media items, but must be specified for album\nenrichment.\n\nA position can only be specified when [creating a media\nitem](/photos/library/guides/upload-media#creating-media-item) or adding\nenrichments. Existing media items in an album can't be reorganized, so it's\nimportant to set the position of an item when it's being added.\n\n### Start of album\n\nA media/enrichment item can be added to the start of the album as absolute\npositioning.\n\n### End of album\n\nA media/enrichment item can be added to the end of the album as absolute\npositioning.\n\n### Relative to media item\n\nA media/enrichment item can be added relative to a media item beginning after\nits position in the album.\n\n### Relative to enrichment item\n\nA media/enrichment item can be added relative to an enrichment item beginning\nafter its position in the album.\n\nAdding enrichments to album\n---------------------------\n\nEnrichments are added one at a time and must be added to a position in an album.\nTo add enrichments to an album, call\n[`albums.addEnrichment`](/photos/library/reference/rest/v1/albums/addEnrichment).\n\nIf the request is successful, it returns the `id` of the enrichment item, which\ncan be used to position media items or other enrichments. \n\n### REST\n\nHere is a POST request: \n\n```\nPOST https://photoslibrary.googleapis.com/v1/albums/album-id:addEnrichment\nContent-type: application/json\nAuthorization: Bearer oauth2-token\n\u003cvar translate=\"no\"\u003erequest-body\u003c/var\u003e\n```\n\nThe request body consists of the enrichment item and its position: \n\n```restructuredtext\n{\n \"newEnrichmentItem\": {\n enrichment-to-be-added\n },\n \"albumPosition\": {\n position-of-enrichment\n}\n```\n\nHere is a sample response: \n\n```restructuredtext\n{\n \"enrichmentItem\": {\n \"id\": \"enrichment-item-id\",\n }\n}\n```\n\nSupported enrichments\n---------------------\n\n### Text enrichments\n\nText enrichments contain a single text string (no more than 1000 characters), as\nshown in the following example: \n\n### REST\n\n```restructuredtext\n{\n \"text\": \"Text to be shown\"\n}\n```\n\n### Java\n\n```java\n// Use the NewEnrichmentItemFactory helper to create a text enrichment item\nNewEnrichmentItem newEnrichmentItem =\n NewEnrichmentItemFactory.createTextEnrichment(\"text to be shown\");\n```\n\n### PHP\n\n```php\n$newEnrichmentItem = PhotosLibraryResourceFactory::newEnrichmentItemWithText(\"text to be shown\");\n```\n\n### Location enrichments\n\nLocation enrichments consist of an arbitrary location name and the latitude and\nlongitude position. The `locationName` is limited to 500 characters. \n\n### REST\n\n```restructuredtext\n{\n \"location\": {\n \"locationName\": \"Australia\",\n \"latlng\": {\n \"latitude\": \"-21.197\",\n \"longitude\": \"95.821\"\n }\n }\n}\n```\n\n### Java\n\n```java\n// Use the NewEnrichmentItemFactory helper to create a location enrichment\n// with the name, latitude, and longitude of the location\nNewEnrichmentItem newEnrichmentItem =\n NewEnrichmentItemFactory.createLocationEnrichment(\"Australia\", -21.197, 95.821);\n```\n\n### PHP\n\n```php\n// Create a new location object and set the name, latitude, and longitude of the location\n$newLocation = new Location();\n$newLocation-\u003esetLocationName(\"Australia\");\n$newLocation-\u003esetLatlng((new LatLng())-\u003esetLatitude(-21.197)-\u003esetLongitude(95.821));\n\n$newEnrichmentItem = PhotosLibraryResourceFactory::newEnrichmentItemWithLocation($newLocation);\n```\n\n### Map enrichments\n\nMap enrichments show two locations, each consisting of a name and the latitude\nand longitude. Similar to the location enrichment, the `locationName` within the\norigin and `destination` is limited to 500 characters. \n\n### REST\n\n```restructuredtext\n{\n \"origin\": {\n \"locationName\": \"Australia\",\n \"latlng\": {\n \"latitude\": \"-21.197\",\n \"longitude\": \"95.821\"\n }\n },\n \"destination\": {\n \"locationName\": \"San Francisco\",\n \"latlng\": {\n \"latitude\": \"37.757\",\n \"longitude\": \"122.507\"\n }\n }\n}\n```\n\n### Java\n\n```java\n// Use the NewEnrichmentItemFactory helper to create a map enrichment item for\n// an origin and a destination location\nNewEnrichmentItem newEnrichmentItem = NewEnrichmentItemFactory.createMapEnrichment(\n \"Australia\", -21.197, 95.821, // origin\n \"San Francisco\", 37.757, 122.507 // destination\n);\n```\n\n### PHP\n\n```php\n// Create two new location objects to create a map enrichment item\n// for an origin and a destination location\n$locationAustralia = new Location();\n$locationAustralia-\u003esetLocationName(\"Australia\");\n$locationAustralia-\u003esetLatlng((new LatLng())-\u003esetLatitude(-21.197)-\u003esetLongitude(95.821));\n\n$locationSanFrancisco = new Location();\n$locationSanFrancisco-\u003esetLocationName(\"San Francisco\");\n$locationSanFrancisco-\u003esetLatlng((new LatLng())-\u003esetLatitude(37.757)-\u003esetLongitude(122.507));\n\n$newEnrichmentItem =\n PhotosLibraryResourceFactory::newEnrichmentItemWithMap($locationAustralia, $locationSanFrancisco);\n```\n\nSupported positioning\n---------------------\n\n### Start of album\n\nThe position `FIRST_IN_ALBUM` refers to the start of the album. Items located\nhere are shown to the user first: \n\n### REST\n\n```restructuredtext\n{\n \"position\": \"FIRST_IN_ALBUM\",\n}\n```\n\n### Java\n\n```java\nAlbumPosition albumPosition = AlbumPositionFactory.createFirstInAlbum();\n```\n\n### PHP\n\n```php\n$albumPosition = new AlbumPosition();\n$albumPosition-\u003esetPosition(PositionType::FIRST_IN_ALBUM);\n```\n\n### End of album\n\nThe position `LAST_IN_ALBUM` refers to the end of the album. Items located here\nare shown to the user last. \n\n### REST\n\n```restructuredtext\n{\n \"position\": \"LAST_IN_ALBUM\",\n}\n```\n\n### Java\n\n```java\nAlbumPosition albumPosition = AlbumPositionFactory.createLastInAlbum();\n```\n\n### PHP\n\n```php\n$albumPosition = new AlbumPosition();\n$albumPosition-\u003esetPosition(PositionType::LAST_IN_ALBUM);\n```\n\n### Relative to media item\n\nSpecifying the position `relativeMediaItem` refers to a position relative to a\nmedia item. The items are added after the specified media item. \n\n### REST\n\n```restructuredtext\n{\n \"position\": \"after-media-item\",\n \"relativeMediaItemId\": \"media-item-id\"\n}\n```\n\n### Java\n\n```java\nAlbumPosition albumPosition = AlbumPositionFactory.createAfterMediaItem(mediaItemId);\n```\n\n### PHP\n\n```php\n$albumPosition = PhotosLibraryResourceFactory::albumPositionAfterMediaItem($mediaItemId);\n```\n\n### Relative to enrichment item\n\nSpecifying a `relativeEnrichmentItemId` refers to a position relative to an\nenrichment item. The items are added after the specified enrichment item. \n\n### REST\n\n```restructuredtext\n{\n \"position\": \"after-enrichment-item\",\n \"relativeEnrichmentItemId\": \"enrichment-item-id\"\n}\n```\n\n### Java\n\n```java\nAlbumPosition albumPosition = AlbumPositionFactory.createAfterEnrichmentItem(enrichmentItemId);\n```\n\n### PHP\n\n```php\n$albumPosition = PhotosLibraryResourceFactory::albumPositionAfterEnrichmentItem($enrichmentItemId);\n```\n\nModifying enrichments\n---------------------\n\nCurrently, there is no way to modify enrichments. However, once an enrichment\nhas been created and added to an album, the user can modify the enrichments\nthrough the Google Photos app."]]
