🌟 Facebook Image / Photos Downloader

One‑liner: Instantly extract and archive images from Facebook page or post URLs — production-ready, privacy-aware, and plug‑and‑play on Apify Console.

---

📖 Summary

This Actor visits one or more Facebook page/post URLs (provided as startUrls) and collects direct image files it finds (OG image and hosted images). Images are saved to Apify Key‑Value Store (or the local OUTPUT folder when running without Apify). Runs in seconds and is designed for high‑volume, reliable scraping.

💡 Use cases — when to use

• Archive images from a public Facebook post or page for analytics.
• Collect visual assets for moderation or offline review.
• Integrate with downstream pipelines that consume image URLs or stored KV records.
• Quick one-off downloads of images referenced by a URL.

---

⚡ Quick Start (Console — one‑click)

1. Go to this Actor in Apify Console.
2. Paste a startUrls value (see example in input.example.json) into the Input field.
3. Click Run — results appear in the Dataset and images in Key‑Value Store.

(Hero screenshot / GIF: add a short Console run GIF for best conversion.)

---

⚙️ Quick Start (CLI + API)

CLI

$apify run --actor <ACTOR_ID> --input input.example.json

Python (apify-client)

from apify_client import ApifyClient
client = ApifyClient('<APIFY_TOKEN>')
run = client.actor('USERNAME/ACTOR_NAME').call(run_input={"startUrls": ["https://www.facebook.com/somepage/posts/12345"]})
print('Run ID:', run['id'])

---

📝 Inputs (fields & schema)

Console JSON input example (also saved as input.example.json)

{
  "startUrls": [
    "https://www.facebook.com/somepage/posts/12345",
    "https://www.facebook.com/anotherpage"
  ],
  "preserve_downloads": false
}

Input schema (inferred)

{
  "type": "object",
  "properties": {
    "startUrls": {"type": ["array","string"]},
    "preserve_downloads": {"type": "boolean"}
  },
  "required": ["startUrls"]
}

---

⚙️ Configuration (defaults inferred)

🔑 Name	📝 Type	❓ Required	⚙️ Default	📌 Example	🧠 Notes
startUrls	array/string	✅ Yes	—	["https://facebook.com/..."]	One or many page/post URLs
preserve_downloads	boolean	⚙️ Optional	false	true	If true, local files are kept in output
proxyConfig	object	⚙️ Optional	{}	{"useApifyProxy": true}	Use Apify Proxy or custom proxy (see Proxy Configuration)

Example Console setup: Paste one URL into startUrls, set preserve_downloads if you need local copies, then click Run Actor.

---

📄 Outputs (Dataset / KV examples)

What you get

• Each image produces a record pushed to the Dataset (streamed during the run).
• All images are also stored in Key‑Value Store (when running on Apify) or saved in output/ locally.

Example output record (Dataset item)

{
  "source_url": "https://www.facebook.com/somepage/posts/12345",
  "image_url": "https://scontent.xx.fbcdn.net/....jpg",
  "kv_key_or_path": "IMAGE_1",
  "stored_as_kv": true,
  "scraped_at": "2025-12-19T12:34:56Z",
  "direct_url": "https://api.apify.com/v2/key-value-stores/~/records/IMAGE_1"
}

Notes

• kv_key_or_path will be a Key‑Value record key when running in Console (and a local path when running outside Apify).
• A final OUTPUT JSON (array of records) is saved to Key‑Value Store or output/all_images.json locally.

---

🔑 Environment Variables

Name	Purpose	Example / Placeholder
APIFY_TOKEN	API auth for apify-client	<APIFY_TOKEN>
HTTP_PROXY / HTTPS_PROXY	Custom proxy endpoints (if not using Apify Proxy)	<PROXY_USER:PASS@HOST:PORT>

---

▶️ How to Run (Console, CLI, API)

Console

• Paste input.example.json into the Input field. Click Run. Monitor Dataset & Key‑Value Store.

CLI

$apify run --actor <ACTOR_ID> --input input.example.json

API (create run) Use the apify-client example above — pass run_input containing startUrls.

---

⏰ Scheduling & Webhooks

• Schedule runs in Apify Console using the built‑in scheduler (select cron or interval).
• Add a webhook in Settings to receive an HTTP POST when the run finishes; webhook payload contains runId and result links.

---

🕾️ Logs & Troubleshooting

Where to find logs: Apify Console → Run → Logs. Common issues & quick fixes

• No images found — confirm URL is public and not blocked by login.
• 403 / access errors — enable Apify Proxy or add credentials for a legitimate proxy.
• Empty output — ensure startUrls exists in input JSON.

---

🔒 Permissions & Storage Notes

• Uses Apify Dataset and Key‑Value Store when running in Console.
• Images stored in KV are accessible via the Apify API (signed/controlled by your token).
• Privacy: This Actor scrapes publicly available images only. Do not use it for credentialed access or to bypass protected resources.

---

🔟 Changelog / Versioning

• 1.0.0 — Initial release: reliable image extraction and KV storage.

---

🖌 Notes / TODOs

• TODO: confirm output schema — inferred from actor behavior but not explicitly described in source.
• TODO: add demo GIF/screenshots (provide images for best conversion).

---

🌍 Proxy Configuration

This Actor performs network requests. You can use Apify Proxy (recommended) or your own proxy.

Enable Apify Proxy (Console) — one‑line

• In Actor run settings → Networking → Enable Apify Proxy.

Custom proxies

• Set environment variables in run configuration: HTTP_PROXY=<PROXY_USER:PASS@HOST:PORT> HTTPS_PROXY=<PROXY_USER:PASS@HOST:PORT>

CLI example (env override)

$HTTP_PROXY='<PROXY_USER:PASS@HOST:PORT>' apify run --actor <ACTOR_ID> --input input.example.json

Security note: store credentials as secrets in Apify Console — do not paste them in plaintext. Advanced: TODO: Consider proxy rotation for large‑scale scraping.

---

📚 References

1. Apify Actors: README guidelines — official docs.
2. Apify Input & Output schema — official docs.
3. Apify CLI & API usage — official docs.

---

🤔 What I inferred from main.py

• The Actor accepts startUrls (string or array) and preserve_downloads boolean.
• It performs HTTP requests to fetch HTML and extracts images (OG + hosted images).
• Images are streamed to the Dataset during the run and stored in Key‑Value Store (or output/ locally).
• The Actor returns a final OUTPUT JSON containing all image records.

---

Why this Actor? Instant results, production‑ready, privacy‑aware — run on Apify Console and get image records and downloadable KV links in seconds.

Run this Actor on Apify Console — get instant results in seconds.