Downloading Photos

To download the full size original photo file or resized image files generated for a photo, the application needs to construct an image URL and issue a regular HTTP GET request to download the file. This section describes how to construct image URLs suitable for immediate downloading.

If access to a photo is restricted, the application needs to provide the authentication token or the keyring along with the GET request in a manner similar to the Zenfolio API calls. To specify the authentication token, the application should include an X-Zenfolio-Token header or a zf_token cookie. To specify the keyring, the application should include an X-Zenfolio-Keyring header or a zf_keyring cookie. See the Authentication and Using the Keyring chapters for more information.

Downloading Original Files

Applications obtain the URL to the original file from the OriginalUrl field of the Photo, File, or GalleryFile snapshot. This URL is directly downloadable provided that the authentication information is correct and the original photo image is not protected with a password.

Note that Zenfolio does not store the original file for videos. A URL to the highest quality generated video file is returned in the OriginalUrl field for Photo snapshots that represent a video.

If the original photo image is protected with a password, the application needs to obtain the password from the user, validate it using the GetDownloadOriginalKey method, and add the returned download key as the "key" query parameter to the download URL.

To determine if the original image is protected with a password, check for the PasswordProtectedOriginals flag in the access mask of the corresponding access descriptor. The application can also use the SrcPasswordHint field of the access descriptor to display the password hint provided by the owner when querying the user for the password.

Once the password is obtained, the application should call the GetDownloadOriginalKey method with the identifier of the photo it intends to download and the password. When called with a correct password, the method returns a string download key. The application then should add the returned key as the "key" query parameter. For example, if photo's OriginalUrl field contains "" and GetDownloadOriginalKey returns "50B80FB0A7554ab", the application should use the following URL to download the original file:

Note that the download key does not replace the authentication token. If the photo itself is not public, a valid authentication token has to be provided in the request in order to successfully download the original image.

Downloading Generated Resized Images

To download generated display images, use the following URL:


Where the components of the URL are:

  • UrlHost is the download host name obtained from the UrlHost field of the corresponding Photo or File snapshot.
  • UrlCore is the photo URL core that contains the invariant portion of the photo URL. Use the UrlCore field of the Photo or File snapshot to obtain this value.
  • Size specifies the desired image size. Currently, the following sizes are available for photos:




    Small thumbnail (up to 80 x 80)


    Square thumbnail (60 x 60, cropped square)


    Small (up to 400 x 400)


    Medium (up to 580 x 450)


    Large (up to 800 x 630)


    X-Large (up to 1100 x 850)


    XX-Large (up to 1550 x 960)


    Medium thumbnail (up to 120 x 120)


    Large thumbnail (up to 120 x 120)

  • In addition, the following image sizes are available for the user file object that represents the user photo in the user's public profile:




    Large thumbnail (up to 120 x 120)


    Small thumbnail (up to 80 x 80)

  • Sequence is the photo sequence number, which you can obtain from the Sequence field of the Photo or File snapshot.
  • UrlToken is the additional URL token obtained from the UrlToken field of the Photo snapshot. This value is only used when downloading photo images.

URLs constructed this way may become invalid after some time. This URL format should only be used when your application downloads the image and does not save the URL for later use or displays it to the user.

Downloading Raw Files

The API allows downloading of Raw files by the owner only. To download a Raw file, use the OriginalUrl field of the GalleryFile snapshot to obtain the URL to download from.

Caching Images

Applications should use the standard HTTP caching semantics when caching images retrieved with download URLs described in this section. Zenfolio servers will return appropriate Cache-Control and Expires headers when returned content is cacheable.