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",
}
}
支援的強化功能
文字擴充
文字強化內容包含單一文字字串 (最多 1,000 個半形字元)，如以下範例所示：
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 相簿應用程式修改強化內容。
除非另有註明，否則本頁面中的內容是採用創用 CC 姓名標示 4.0 授權，程式碼範例則為阿帕契 2.0 授權。詳情請參閱《Google Developers 網站政策》。Java 是 Oracle 和/或其關聯企業的註冊商標。
上次更新時間：2025-08-29 (世界標準時間)。
[null,null,["上次更新時間：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."]]
