amazon-photos-album-download
Self-Evolving Skill: This skill improves through use. If instructions are wrong, parameters drifted, or a workaround was needed — fix this file immediately, don't defer. Only update for real, reproducible issues.
Download every original file from a public Amazon Photos shared album —
the kind of link you get from "Share → Copy link", e.g.
https://www.amazon.ca/photos/share/qGAyl…. No Amazon login is needed for a
public share; the album authorizes anonymously via its shareId.
When to use
- You shared an album with someone and need the originals back locally to
re-process them (the #1 case: convert iPhone HEIC originals to JPEG for a
recipient who can't open HEIC — then see the
heic-to-jpeg-bundle skill).
- You want to re-host an album's photos yourself (a static gallery, a ZIP).
- You need a verified, complete local backup of a share you (or someone) sent.
How it works
Amazon Photos is a React app over Amazon Drive's /drive/v1/ JSON API. A
public share exposes, with just the shareId as auth:
GET /drive/v1/shares/<shareId> → the root SHARED_COLLECTION node id.
GET /drive/v1/nodes/<root>/children?limit=1… → the album folder node id.
GET /drive/v1/nodes/<album>/children?filters=…image*+OR+video*…&limit=200…
→ the list of asset nodes (name, contentProperties.contentType, size).
- per node:
GET /drive/v1/nodes/<id>/contentRedirection?download=true&shareId=…
→ the original bytes.
The script runs the JSON calls inside a headless Chrome page (via Playwright)
so they carry the exact cookies/headers the web app uses, then writes each file
under its real name and verifies the byte size against contentProperties.size.
A manifest.json records every node id, name, type, and size.
Prerequisites
bun, playwright-core, and Google Chrome installed.
- The album link must be public (open it once in a logged-out browser to
confirm it doesn't redirect to a sign-in wall).
# one-time, in the dir you'll run from (or any scratch dir):
mkdir -p ~/scratch/amazon-album && cd ~/scratch/amazon-album
bun add playwright-core
Quick start
SKILL_DIR="$(dirname "$(find ~/.claude ~/eon -path '*/amazon-photos-album-download/scripts/download-album.ts' 2>/dev/null | head -1)")"
ALBUM_URL="https://www.amazon.ca/photos/share/REPLACE_WITH_SHARE_ID" \
ALBUM_OUT="$HOME/Pictures/my-album-originals" \
bun "$SKILL_DIR/download-album.ts"
Then convert + bundle for sharing:
BUNDLE="$(dirname "$(find ~/.claude ~/eon -path '*/heic-to-jpeg-bundle/scripts/make-bundle.sh' 2>/dev/null | head -1)")"
bash "$BUNDLE/make-bundle.sh" --src "$HOME/Pictures/my-album-originals" --zip --zip-cap-mib 25
Options (env vars)
| Env |
Default |
Meaning |
ALBUM_URL |
(required) |
The /photos/share/<id> URL |
ALBUM_OUT |
./album-originals |
Output directory |
ALBUM_INCLUDE |
image |
image, image,video, or all |
ALBUM_PROFILE_DIR |
~/.cache/amazon-album/chrome |
Persistent Chrome profile dir |
ALBUM_CHROME_CHANNEL |
chrome |
Playwright Chrome channel |
ALBUM_PAUSE_MS |
800 |
Delay between downloads (be gentle) |
Key facts and gotchas
- The album may hold more than you think. A "~40 photo" album can list 100+
asset nodes once you count Live-Photo stills and videos. The default
ALBUM_INCLUDE=image keeps just still images; widen it if you want videos.
contentRedirection?download=true returns the original, not a thumbnail.
The album-listing tempLinks can be downsized (the app requests
lowResThumbnail=true); always pull originals via contentRedirection.
- Run the JSON calls in-page. Calling
/drive/v1/ from plain curl fails —
the share auth rides on the browser context. The script uses page.evaluate
(JSON) + context.request (binaries), both inside the loaded album context.
- Size-verify. Each file is checked against
contentProperties.size (±2%);
the manifest.json verified count should equal selected.
- Undocumented API. This is Amazon's internal Drive API. It works today; if
it breaks, load the album in a headed browser and re-watch the
/drive/v1/
requests to re-derive the endpoints.
- Privacy. Originals often carry GPS EXIF, license plates, VIN/odometer, and
home surroundings. Store them outside any git repo and don't re-host them
publicly without thought (an unlisted host + the
heic-to-jpeg-bundle password
ZIP is the cautious default).
Post-Execution Reflection
After running, before closing:
- Did
verified < selected? Investigate the failed nodes (rate limiting,
a node type without contentRedirection); note the fix.
- Did an API call 4xx/5xx? Amazon may have changed an endpoint — re-derive
from a headed browser and update
download-album.ts + the steps above.
- Only update this SKILL.md for real, reproduced changes.
1---
2name: amazon-photos-album-download
3description: Download the original photo and video files from a public Amazon Photos shared album (an amazon.com/amazon.ca /photos/share/<id> link) via Amazon Drive's own JSON API, no login required. Drives headless Chrome with Playwright, lists the album nodes, and pulls size-verified originals. Use when you need a local copy of every file in a shared Amazon Photos album, to re-process or re-host them (e.g. convert HEIC to JPEG, build a gallery). TRIGGERS - amazon photos download, download shared album, amazon photos share link, pull amazon album, amazon drive share, save amazon photos.
4allowed-tools: Bash, Read, AskUserQuestion
5argument-hint: "[Amazon Photos share URL]"
6metadata:
7 source: https://skillmd.com/skills/terrylica/amazon-photos-album-download
8---
9
10# amazon-photos-album-download
11
12> **Self-Evolving Skill**: This skill improves through use. If instructions are wrong, parameters drifted, or a workaround was needed — fix this file immediately, don't defer. Only update for real, reproducible issues.
13
14Download every **original** file from a **public Amazon Photos shared album** —
15the kind of link you get from "Share → Copy link", e.g.
16`https://www.amazon.ca/photos/share/qGAyl…`. No Amazon login is needed for a
17public share; the album authorizes anonymously via its `shareId`.
18
19## When to use
20
21- You shared an album with someone and need the originals back locally to
22 re-process them (the #1 case: **convert iPhone HEIC originals to JPEG** for a
23 recipient who can't open HEIC — then see the `heic-to-jpeg-bundle` skill).
24- You want to re-host an album's photos yourself (a static gallery, a ZIP).
25- You need a verified, complete local backup of a share you (or someone) sent.
26
27## How it works
28
29Amazon Photos is a React app over **Amazon Drive's `/drive/v1/` JSON API**. A
30public share exposes, with just the `shareId` as auth:
31
321. `GET /drive/v1/shares/<shareId>` → the root `SHARED_COLLECTION` node id.
332. `GET /drive/v1/nodes/<root>/children?limit=1…` → the album **folder** node id.
343. `GET /drive/v1/nodes/<album>/children?filters=…image*+OR+video*…&limit=200…`
35 → the list of asset nodes (name, `contentProperties.contentType`, `size`).
364. per node: `GET /drive/v1/nodes/<id>/contentRedirection?download=true&shareId=…`
37 → the original bytes.
38
39The script runs the JSON calls **inside a headless Chrome page** (via Playwright)
40so they carry the exact cookies/headers the web app uses, then writes each file
41under its real name and **verifies the byte size** against `contentProperties.size`.
42A `manifest.json` records every node id, name, type, and size.
43
44## Prerequisites
45
46- `bun`, `playwright-core`, and **Google Chrome** installed.
47- The album link must be **public** (open it once in a logged-out browser to
48 confirm it doesn't redirect to a sign-in wall).
49
50```bash
51# one-time, in the dir you'll run from (or any scratch dir):
52mkdir -p ~/scratch/amazon-album && cd ~/scratch/amazon-album
53bun add playwright-core
54```
55
56## Quick start
57
58```bash
59SKILL_DIR="$(dirname "$(find ~/.claude ~/eon -path '*/amazon-photos-album-download/scripts/download-album.ts' 2>/dev/null | head -1)")"
60
61ALBUM_URL="https://www.amazon.ca/photos/share/REPLACE_WITH_SHARE_ID" \
62ALBUM_OUT="$HOME/Pictures/my-album-originals" \
63bun "$SKILL_DIR/download-album.ts"
64```
65
66Then convert + bundle for sharing:
67
68```bash
69BUNDLE="$(dirname "$(find ~/.claude ~/eon -path '*/heic-to-jpeg-bundle/scripts/make-bundle.sh' 2>/dev/null | head -1)")"
70bash "$BUNDLE/make-bundle.sh" --src "$HOME/Pictures/my-album-originals" --zip --zip-cap-mib 25
71```
72
73## Options (env vars)
74
75| Env | Default | Meaning |
76| ---------------------- | ------------------------------ | ----------------------------------- |
77| `ALBUM_URL` | (required) | The `/photos/share/<id>` URL |
78| `ALBUM_OUT` | `./album-originals` | Output directory |
79| `ALBUM_INCLUDE` | `image` | `image`, `image,video`, or `all` |
80| `ALBUM_PROFILE_DIR` | `~/.cache/amazon-album/chrome` | Persistent Chrome profile dir |
81| `ALBUM_CHROME_CHANNEL` | `chrome` | Playwright Chrome channel |
82| `ALBUM_PAUSE_MS` | `800` | Delay between downloads (be gentle) |
83
84## Key facts and gotchas
85
86- **The album may hold more than you think.** A "~40 photo" album can list 100+
87 asset nodes once you count Live-Photo stills and videos. The default
88 `ALBUM_INCLUDE=image` keeps just still images; widen it if you want videos.
89- **`contentRedirection?download=true` returns the original**, not a thumbnail.
90 The album-listing `tempLink`s can be downsized (the app requests
91 `lowResThumbnail=true`); always pull originals via `contentRedirection`.
92- **Run the JSON calls in-page.** Calling `/drive/v1/` from plain `curl` fails —
93 the share auth rides on the browser context. The script uses `page.evaluate`
94 (JSON) + `context.request` (binaries), both inside the loaded album context.
95- **Size-verify.** Each file is checked against `contentProperties.size` (±2%);
96 the `manifest.json` `verified` count should equal `selected`.
97- **Undocumented API.** This is Amazon's internal Drive API. It works today; if
98 it breaks, load the album in a **headed** browser and re-watch the `/drive/v1/`
99 requests to re-derive the endpoints.
100- **Privacy.** Originals often carry GPS EXIF, license plates, VIN/odometer, and
101 home surroundings. Store them outside any git repo and don't re-host them
102 publicly without thought (an unlisted host + the `heic-to-jpeg-bundle` password
103 ZIP is the cautious default).
104
105## Post-Execution Reflection
106
107After running, before closing:
108
1091. **Did `verified` < `selected`?** Investigate the failed nodes (rate limiting,
110 a node type without `contentRedirection`); note the fix.
1112. **Did an API call 4xx/5xx?** Amazon may have changed an endpoint — re-derive
112 from a headed browser and update `download-album.ts` + the steps above.
1133. Only update this SKILL.md for real, reproduced changes.