Download entire iCloud shared albums icloud-album-download.sh

gistfile1.txt

#!/bin/bash

# requires jq
# arg 1: iCloud web album URL
# arg 2: folder to download into (optional)
#
# Credits: https://gist.github.com/zneak/8f719cd81967e0eb2234897491e051ec
# icloud-album-download.sh

function curl_post_json {
	curl -sH "Content-Type: application/json" -X POST -d "@-" "$@"
}

BASE_API_URL="https://p23-sharedstreams.icloud.com/$(echo $1 | cut -d# -f2)/sharedstreams"

pushd $2 > /dev/null
STREAM=$(echo '{"streamCtag":null}' | curl_post_json "$BASE_API_URL/webstream")
HOST=$(echo $STREAM | jq '.["X-Apple-MMe-Host"]' | cut -c 2- | rev | cut -c 2- | rev)

if [ "$HOST" ]; then
    BASE_API_URL="https://$(echo $HOST)/$(echo $1 | cut -d# -f2)/sharedstreams"
    STREAM=$(echo '{"streamCtag":null}' | curl_post_json "$BASE_API_URL/webstream")
fi

CHECKSUMS=$(echo $STREAM | jq -r '.photos[] | [(.derivatives[] | {size: .fileSize | tonumber, value: .checksum})] | max_by(.size | tonumber).value')

echo $STREAM \
| jq -c "{photoGuids: [.photos[].photoGuid]}" \
| curl_post_json "$BASE_API_URL/webasseturls" \
| jq -r '.items | to_entries[] | "https://" + .value.url_location + .value.url_path + "&" + .key' \
| while read URL; do
	for CHECKSUM in $CHECKSUMS; do
		if echo $URL | grep $CHECKSUM > /dev/null; then
			curl -sOJ $URL &
			break
		fi
	done
done

popd > /dev/null
wait

Hi!

Thanks for providing this script, it helped me to build a digital picture frame. 👍

I'm wondering why you did this

HOST=$(echo $STREAM | jq '.["X-Apple-MMe-Host"]' | cut -c 2- | rev | cut -c 2- | rev)

instead of this:

HOST=$(echo $STREAM | jq -r '.["X-Apple-MMe-Host"]')

Cheers,
Dennis

Hi

I cam across this while trying to find a way to download a shared icloud album.
I have the link to the album but is looking for a method / tool to paste the link in and it download the entire album to my local computer.
This seems to do the job but I don't know how to use this.
Can someone show me please...or point me to where I can learn to use this.

Thank you.

Quickly wrote a new Powershell script to download iCloud shared album (photos + videos):
https://gist.github.com/GodSaveEarth/9ba8d574d0f5ab789aebdfdb2db59b8df

Works like charm, even 5 years later! Thank you so much!

I know I'm more than 2 years late @SDK665 but in case someone else needs this:
Download the bash file, then open a terminal and navigate to the folder where the script is. First argument is the iCloud Shared Album URL, second argument is the output folder where pictures will be downloaded to. Make sure your output folder exists. So in the terminal type:

cd ~/Downloads
mkdir downloaded_pictures
sh download-icloud-sharedalbum.sh https://www.icloud.com/sharedalbum/#YOUR-FOLDER_ID ~/Downloads/downloaded_pictures

I simply couldnt get this to work. Is the api endpoint still valid? and Does this work for private shared albums?

Just in the case it helps anyone else... you can get this done using Gemini AI... and python

below is the direct copy paste from Gemini chat...

You will need to udpate the album ID... and might also need to update the p23 with the server that hosts your album.

import requests
import json
import os

# 1. SETUP: Paste your Shared Album ID here
ALBUM_ID = "B1234567890ABC" 
BASE_URL = f"https://p23-sharedstreams.icloud.com/{ALBUM_ID}/sharedstreams"

def download_icloud_album():
    headers = {'Content-Type': 'application/json'}
    
    # STEP 1: Get the Metadata
    print("Fetching album metadata...")
    stream_url = f"{BASE_URL}/webstream"
    response = requests.post(stream_url, data=json.dumps({"streamCtag": None}), headers=headers)
    
    # Handle Redirect
    if response.status_code == 330:
        new_host = response.json().get('X-Apple-MMe-Host')
        print(f"Redirecting to {new_host}...")
        stream_url = f"https://{new_host}/{ALBUM_ID}/sharedstreams/webstream"
        response = requests.post(stream_url, data=json.dumps({"streamCtag": None}), headers=headers)

    data = response.json()
    photos = data.get('photos', [])
    
    # Filter out thumbnails by prioritizing the best derivative
    # We want 'original' or the highest numbered 'p' (720p, 1080p, etc.)
    best_guids = {}
    for p in photos:
        guid = p['photoGuid']
        derivs = p.get('derivatives', {})
        
        # Priority list for high quality
        priority = ['original', '1080p', '720p', '960p']
        found_best = False
        
        for key in priority:
            if key in derivs:
                best_guids[guid] = derivs[key]['checksum']
                found_best = True
                break
        
        # Fallback: if no standard high-res key, take the largest file that isn't 'thumb'
        if not found_best:
            for key in derivs:
                if 'thumb' not in key.lower() and 'square' not in key.lower():
                    best_guids[guid] = derivs[key]['checksum']
                    break

    print(f"Filtered out thumbnails. Found {len(best_guids)} high-res items.")

    # STEP 2: Get Download URLs
    print("Requesting download URLs...")
    urls_endpoint = stream_url.replace('webstream', 'webasseturls')
    # We send the specific checksums we found to ensure we get the right files
    asset_data = {"photoGuids": list(best_guids.keys())}
    asset_response = requests.post(urls_endpoint, data=json.dumps(asset_data), headers=headers)
    
    items = asset_response.json().get('items', {})
    
    # STEP 3: Download
    output_dir = 'icloud_high_res'
    os.makedirs(output_dir, exist_ok=True)

    for guid, details in items.items():
        url = f"https://{details['url_location']}{details['url_path']}"
        
        # Check type and download
        r = requests.get(url, stream=True)
        if r.status_code == 200:
            ctype = r.headers.get('Content-Type', '')
            ext = '.mov' if 'video' in ctype else '.jpg'
            
            filename = os.path.join(output_dir, f"{guid}{ext}")
            print(f"Downloading {ext.upper()}: {guid[:8]}...")
            
            with open(filename, 'wb') as f:
                for chunk in r.iter_content(chunk_size=1024*1024):
                    f.write(chunk)

    print(f"\nSuccess! Files saved in: {os.path.abspath(output_dir)}")

if __name__ == "__main__":
    download_icloud_album()