Images API for legacy bundled services

The Images API provides the ability to serve images directly from Cloud Storage or Blobstore, and to manipulate those images on the fly. To view the contents of the image package, see the image package reference.

Cloud Storage buckets must use fine-grained Access Control Lists for the Images API to work. For buckets that have been configured for uniform bucket-level access, the Images API will not be able to fetch images in that bucket and throws the error message TransformationError. If your bucket is configured in this manner, you can disable uniform bucket-level access.

When you serve images from Cloud Storage, the Images API uses a Google-managed service account, dynamic_image_service@system.gserviceaccount.com, to fetch the image. This is normally done for you, but if this service account doesn't have the Storage Object Viewer role on the bucket, you might experience intermittent 403 Forbidden errors. This happens when the image isn't available in Google's serving cache and needs to be fetched from the origin bucket.

To grant the required permission, run the following gcloud command:

gcloud storage buckets add-iam-policy-binding gs://[BUCKET_NAME] \
  --member=serviceAccount:dynamic_image_service@system.gserviceaccount.com \
  --role=roles/storage.objectViewer

Image formats

The service accepts image data in the JPEG, PNG, WEBP, GIF (including animated GIF), BMP, TIFF and ICO formats. Transformed images can be returned in the JPEG, WEBP and PNG formats.

If the input format and the output format are different, the service converts the input data to the output format before performing the transformation.

Serving and re-sizing images

The image.ServingURL function allows you to generate a stable, dedicated URL for serving web-suitable image thumbnails.

You can store a single copy of your original image in Blobstore, and then request a high-performance per-image URL that can serve the image resized and/or cropped automatically. Serving from this URL does not incur any CPU or dynamic serving load on your application (though bandwidth is still charged as usual).

The URL returned by the function is always public, but not guessable; private URLs are not currently supported. If you wish to stop serving the URL, delete it using the image.DeleteServingURL function.

If you pass an image.ServingURLOptions value to the function, it returns a URL encoded with those options. If you pass nil, the function returns the default URL for the image, for example:

http://lhx.ggpht.com/randomStringImageId

You can resize and crop the image dynamically by specifying the arguments in the URL. The available arguments are:

  • =sxx where xx is an integer from 0–2560 representing the length, in pixels, of the image's longest side. For example, adding =s32 resizes the image so its longest dimension is 32 pixels.
  • =sxx-c where xx is an integer from 0–2560 representing the cropped image size in pixels, and -c tells the system to crop the image.
# Resize the image to 32 pixels (aspect-ratio preserved)
http://lhx.ggpht.com/randomStringImageId=s32

# Crop the image to 32 pixels
http://lhx.ggpht.com/randomStringImageId=s32-c

Serving images from Cloud Storage using the Blobstore API

If you are using Cloud Storage as a data store and serving the images using the Blobstore API, you need to create a blob key for the Cloud Storage object.

A note about deletion

To stop serving an image stored in Cloud Storage or Blobstore call the image.DeleteServingURL function.

You should avoid directly deleting images in Cloud Storage or Blobstore as doing so can leave them accessible through the serving URL.

Serving URLs will stop working if the application that created them is disabled or deleted, even if the underlying image remains available.