📸 Yupoo Album Downloader

Download all product images from any Yupoo album into a single .zip file — with full album metadata included in the output.

---

⚠️ Only individual album URLs are accepted

Use the direct link to the specific album, not category or store pages.

	Example
✅ Correct	https://martinreps.x.yupoo.com/albums/205649537?uid=1
❌ Wrong	https://martinreps.x.yupoo.com/categories
❌ Wrong	https://martinreps.x.yupoo.com/albums

---

🚀 Features

• Extracts all image URLs via JavaScript evaluation (fast, single browser call)
• Downloads images in parallel (up to 20 simultaneous connections)
• Handles password-protected albums
• Extracts album metadata: title, description, category, external links (Weidian / Taobao), product ID
• Compresses all images into a .zip file
• Automatically handles Yupoo's referer protection

---

📥 Input

Field	Required	Description
product_url	✅	Full URL of the Yupoo album
password	❌	Password for protected albums

Example:

{
  "product_url": "https://scarlettluxury.x.yupoo.com/albums/189703081?uid=1",
  "password": ""
}

---

📤 Output

ZIP (Key-Value Store)

A .zip archive containing all downloaded images, stored under the key ZIP.

Dataset (JSON)

{
  "product_url": "https://example.x.yupoo.com/albums/12345678?uid=1",
  "seller_name": "example",
  "seller_url": "https://example.x.yupoo.com",
  "album_id": "12345678",
  "password_used": false,
  "total_downloaded": 18,
  "zip_file": "example_12345678.zip",
  "image_urls": ["https://photo.yupoo.com/.../large.jpg", "..."],
  "album_title": "Nike Air Max 90",
  "album_description": "Available sizes: 36-45",
  "photo_count_displayed": 18,
  "cover_image_url": "https://photo.yupoo.com/.../small.jpg",
  "links": [
    {
      "url": "https://weidian.com/item.html?itemID=1234567890",
      "text": "Weidian",
      "original_href": "/link?url=https%3A%2F%2Fweidian.com..."
    }
  ],
  "main_link": "https://weidian.com/item.html?itemID=1234567890",
  "product_id": "1234567890",
  "category_id": "987654",
  "category_title": "Sneakers",
  "category_url": "/categories/987654",
  "subcategory_id": "111222",
  "subcategory_title": "Nike",
  "subcategory_url": "/categories/111222"
}

---

🛠️ How It Works

1. Opens the album with a headless Chromium browser (Playwright)
2. Handles password entry if needed
3. Runs a single JavaScript call to extract all image URLs and metadata at once
4. Downloads all images in parallel (up to 20 threads) with a shared HTTP session
5. Compresses images into a ZIP and uploads to Apify Key-Value Store
6. Pushes full metadata to the dataset

---

🧪 Example: Run via API and download the ZIP

import time
import requests

API_TOKEN = "YOUR_API_TOKEN"
ACTOR_ID = "pizani~yupoo-images-downloader"
PRODUCT_URL = "https://example.x.yupoo.com/albums/12345678?uid=1"

# Start the Actor
run_resp = requests.post(
    f"https://api.apify.com/v2/acts/{ACTOR_ID}/runs?token={API_TOKEN}",
    json={"product_url": PRODUCT_URL}
)
run_id = run_resp.json()["data"]["id"]

# Wait for completion
status_url = f"https://api.apify.com/v2/actor-runs/{run_id}?token={API_TOKEN}"
while True:
    data = requests.get(status_url).json()["data"]
    if data["status"] in {"SUCCEEDED", "FAILED", "ABORTED", "TIMED-OUT"}:
        break
    time.sleep(5)

# Download ZIP
kv_id = data["defaultKeyValueStoreId"]
zip_url = f"https://api.apify.com/v2/key-value-stores/{kv_id}/records/ZIP?token={API_TOKEN}"
with open("album_images.zip", "wb") as f:
    f.write(requests.get(zip_url).content)

print("✅ Download complete: album_images.zip")

---

🧵 Example: Run multiple albums in parallel

import requests
from concurrent.futures import ThreadPoolExecutor

API_TOKEN = "YOUR_API_TOKEN"
ACTOR_ID = "pizani~yupoo-images-downloader"

urls = [
    "https://store1.x.yupoo.com/albums/11111111",
    "https://store2.x.yupoo.com/albums/22222222",
    "https://store3.x.yupoo.com/albums/33333333",
]

def run(url):
    requests.post(
        f"https://api.apify.com/v2/acts/{ACTOR_ID}/runs?token={API_TOKEN}",
        json={"product_url": url}
    )

with ThreadPoolExecutor(max_workers=3) as executor:
    executor.map(run, urls)

Increase max_workers based on your Apify plan's concurrency limit.

---

📎 Notes

• Yupoo blocks direct image downloads without a valid referer — handled automatically
• The ZIP is named {seller}_{album_id}.zip (e.g. martinreps_205649537.zip)
• main_link priority: Weidian > Taobao
• product_id is extracted from Weidian (itemID) or Taobao (id) query parameters