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

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()