Gerenciar álbuns
Mantenha tudo organizado com as coleções
Salve e categorize o conteúdo com base nas suas preferências.
No Google Fotos, você pode organizar fotos e outros itens de mídia usando álbuns.
Um item de mídia pode ser associado a um ou mais álbuns. Para começar a associar
itens de mídia a um álbum, você precisa criar o álbum primeiro.
Escopos de autorização necessários
A criação de álbuns requer o escopo photoslibrary.appendonly.
Para mudar o título ou a foto da capa dos álbuns após a criação, é necessário o
escopo photoslibrary.edit.appcreateddata.
Para mais informações sobre escopos, consulte Escopos de autorização.
Criar um novo álbum
Para criar um álbum, chame
albums.create e inclua
o title. O title é restrito a 500 caracteres.
A chamada retorna um álbum. O app
pode armazenar o ID do álbum com essas informações e usá-lo para fazer upload de itens
de mídia para o álbum específico.
REST
Aqui está um cabeçalho para uma solicitação POST:
POST https://photoslibrary.googleapis.com/v1/albums
Content-type: application/json
Authorization: Bearer oauth2-token
O corpo da solicitação tem esta aparência:
{
"album": {
"title": "new-album-title"
}
}
Se for bem-sucedido, a resposta vai retornar um
álbum:
{
"productUrl": "album-product-url",
"id": "album-id",
"title": "album-title",
"isWriteable": "whether-you-can-write-to-this-album"
}
Extrair detalhes do álbum
Para recuperar os detalhes de um álbum criado pelo app, chame
albums.get e inclua o
albumId do álbum que você quer buscar.
A chamada retorna um álbum.
REST
Aqui está um cabeçalho para uma solicitação GET:
GET https://photoslibrary.googleapis.com/v1/albums/{albumId}
Content-type: application/json
Authorization: Bearer oauth2-token
O corpo da solicitação tem a seguinte aparência:
{
"albumId": album-id
}
Se for bem-sucedido, a resposta vai retornar um
álbum:
{
"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
}
Mudar os títulos e as fotos de capa dos álbuns
Para mudar o título ou a foto da capa de um álbum, crie um album update
call com o identificador
dele e inclua o novo título ou o ID do item de mídia da nova foto da capa na
solicitação. Você vai precisar usar o escopo de autorização photoslibrary.edit.appcreateddata para fazer a alteração.
Os títulos dos álbuns não podem ter mais de 500 caracteres. Os itens de mídia da capa
precisam ser de propriedade do proprietário do álbum e pertencer ao álbum para o qual serão a capa.
REST
Este é um cabeçalho de solicitação PATCH para atualizar o title e o
coverPhotomediaItemId de um álbum.
PATCH https://photoslibrary.googleapis.com/v1/albums/album-id?updateMask=title&updateMask=coverPhotoMediaItemId
Essa solicitação determina quais propriedades estão sendo atualizadas incluindo uma máscara de campo, indicada pelos parâmetros updateMask no URL. O parâmetro updateMask precisa ser transmitido para cada
propriedade de álbum que está sendo atualizada.
Para cada propriedade que você está atualizando, inclua os detalhes dela no
corpo da solicitação:
{
"title": "new-album-title",
"coverPhotoMediaItemId": "new-cover-media-item-id"
}
Se for bem-sucedido, a resposta vai retornar os detalhes atualizados de 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"
}
Adicionar itens de mídia a um álbum
É possível adicionar itens de mídia criados pelo app aos álbuns criados pelo app
chamando
albums.batchAddMediaItems.
Os itens de mídia são adicionados ao final do álbum na ordem informada nesta chamada.
Toda a solicitação falhará se um item de mídia ou álbum inválido for especificado.
Não há suporte para sucesso parcial.
Cada álbum pode conter até 20.000 itens de mídia. As solicitações para adicionar mais itens que
excederiam esse limite falharão.
Para adicionar itens de mídia a um álbum, chame
albums.batchAddMediaItems
com os identificadores dos itens de mídia e do álbum.
REST
Aqui está um cabeçalho para uma solicitação POST:
POST https://photoslibrary.googleapis.com/v1/albums/album-id:batchAddMediaItems
Content-type: application/json
Authorization: Bearer oauth2-token
O corpo da solicitação tem esta aparência:
{
"mediaItemIds": [
"media-item-id",
"another-media-item-id",
...
]
}
Se bem-sucedida, a resposta retorna uma resposta JSON vazia e o status de sucesso HTTP.
Remover itens de mídia de um álbum
É possível remover itens de mídia criados pelo app para álbuns criados por ele chamando
albums.batchRemoveMediaItems.
Toda a solicitação falhará se itens de mídia inválidos forem especificados. Não é possível
ter sucesso parcial.
Para remover itens de mídia de um álbum, chame
albums.batchRemoveMediaItems
com os identificadores dos itens de mídia e do álbum.
REST
Aqui está um cabeçalho para uma solicitação POST:
POST https://photoslibrary.googleapis.com/v1/albums/album-id:batchRemoveMediaItems
Content-type: application/json
Authorization: Bearer oauth2-token
O corpo da solicitação tem esta aparência:
{
"mediaItemIds": [
"media-item-id",
"another-media-item-id",
...
]
}
Se for bem-sucedida, a resposta retornará uma resposta JSON vazia e o status de sucesso 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
}
Exceto em caso de indicação contrária, o conteúdo desta página é licenciado de acordo com a Licença de atribuição 4.0 do Creative Commons, e as amostras de código são licenciadas de acordo com a Licença Apache 2.0. Para mais detalhes, consulte as políticas do site do Google Developers. Java é uma marca registrada da Oracle e/ou afiliadas.
Última atualização 2025-09-04 UTC.
[[["Fácil de entender","easyToUnderstand","thumb-up"],["Meu problema foi resolvido","solvedMyProblem","thumb-up"],["Outro","otherUp","thumb-up"]],[["Não contém as informações de que eu preciso","missingTheInformationINeed","thumb-down"],["Muito complicado / etapas demais","tooComplicatedTooManySteps","thumb-down"],["Desatualizado","outOfDate","thumb-down"],["Problema na tradução","translationIssue","thumb-down"],["Problema com as amostras / o código","samplesCodeIssue","thumb-down"],["Outro","otherDown","thumb-down"]],["Última atualização 2025-09-04 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,["In 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\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\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\nREST\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\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\nREST\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\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\nREST\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\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\nREST\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\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\nREST\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\nJava \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\nPHP \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```"]]
