Color Palette Generator
Pricing
Pay per usage
Generate color palettes from a hex color, a theme in plain words, or an image URL. Get hex, RGB, HSL, color names, WCAG contrast grades, and copy-paste CSS, SCSS and Tailwind. Fully offline, no API key, no scraping.
Pricing
Pay per usage
Rating
0.0
(0)
Developer
Mangudäi
Maintained by CommunityActor stats
0
Bookmarked
2
Total users
1
Monthly active users
4 hours ago
Last modified
Categories
Share
{ "actorSpecification": 1, "dockerfile": "../Dockerfile", "name": "color-palette-generator", "title": "Color Palette Generator - Text, Image, Harmony & WCAG", "description": "Generate color palettes from a hex color, a theme in words, or an image URL. Returns hex, RGB, HSL, color names, WCAG contrast, and CSS, SCSS and Tailwind exports. Offline, no API key.", "version": "0.1", "meta": { "templateId": "python-start" }, "input": { "title": "Color Palette Generator input", "type": "object", "schemaVersion": 1, "properties": { "queries": { "title": "Colors, themes, or image URLs", "type": "array", "description": "One line per palette. Each line can be a hex color (e.g. #2E86DE), a theme in plain words (e.g. sunset, dark forest, corporate), or a public image URL to extract colors from.", "editor": "stringList", "prefill": ["#2E86DE", "sunset", "dark forest"] }, "scheme": { "title": "Harmony scheme", "type": "string", "description": "Color harmony to build around the base color. Auto picks a fitting scheme for each query.", "editor": "select", "default": "auto", "enum": ["auto", "complementary", "analogous", "triadic", "split_complementary", "tetradic", "square", "monochromatic", "shades", "tints"], "enumTitles": ["Auto (recommended)", "Complementary", "Analogous", "Triadic", "Split complementary", "Tetradic", "Square", "Monochromatic", "Shades", "Tints"] }, "includeAllSchemes": { "title": "Include every harmony scheme", "type": "boolean", "description": "Add an allSchemes object with the hex list for all nine harmony schemes, not just the selected one.", "default": true }, "colorsPerImage": { "title": "Colors to extract per image", "type": "integer", "description": "How many dominant colors to pull from each image URL.", "editor": "number", "default": 6, "minimum": 2, "maximum": 10 } }, "required": ["queries"] }, "storages": { "dataset": { "actorSpecification": 1, "title": "Generated palettes", "views": { "overview": { "title": "Palette overview", "transformation": { "fields": ["query", "mode", "baseColor", "scheme", "temperature", "hasReadableColor", "exports"] }, "display": { "component": "table", "properties": { "query": {"label": "Query", "format": "text"}, "mode": {"label": "Mode", "format": "text"}, "baseColor": {"label": "Base color", "format": "text"}, "scheme": {"label": "Scheme", "format": "text"}, "temperature": {"label": "Temp", "format": "text"}, "hasReadableColor": {"label": "Readable", "format": "boolean"} } } } } } }, "output": { "actorOutputSchemaVersion": 1, "title": "Palette output", "properties": { "palettes": { "type": "string", "title": "Generated palettes", "template": "{{links.apiDefaultDatasetUrl}}/items" } } }}1
1import asyncio2
3from .main import main4
5if __name__ == '__main__':6 asyncio.run(main())1"""2Color Palette Studio - Apify Actor.3
4Generate harmonious color palettes from a seed color, a theme in plain words,5or an image URL. Every palette comes with hex, RGB and HSL values, algorithmic6color names, WCAG contrast grades, and ready-to-paste CSS, SCSS and Tailwind7exports.8
9Fully offline and deterministic. No third-party API, no API key, no scraping.10The only optional network call is fetching an image the user points at.11"""12
13import asyncio14import colorsys15import hashlib16import re17from datetime import datetime, timezone18
19from apify import Actor20
21# ===========================================================================22# Color-space conversions23# ===========================================================================24
25
26def hex_to_rgb(value):27 s = str(value).strip().lstrip("#")28 if len(s) == 3:29 s = "".join(c * 2 for c in s)30 if len(s) != 6 or re.search(r"[^0-9a-fA-F]", s):31 raise ValueError(f"Not a valid hex color: {value!r}")32 return tuple(int(s[i:i + 2], 16) for i in (0, 2, 4))33
34
35def rgb_to_hex(rgb):36 r, g, b = (max(0, min(255, int(round(c)))) for c in rgb)37 return f"#{r:02X}{g:02X}{b:02X}"38
39
40def rgb_to_hsl(rgb):41 r, g, b = (c / 255 for c in rgb)42 h, l, s = colorsys.rgb_to_hls(r, g, b)43 return (round(h * 360, 1), round(s * 100, 1), round(l * 100, 1))44
45
46def hsl_to_rgb(h, s, l):47 r, g, b = colorsys.hls_to_rgb((h % 360) / 360, l / 100, s / 100)48 return (r * 255, g * 255, b * 255)49
50
51# ===========================================================================52# Luminance, contrast, WCAG53# ===========================================================================54
55
56def _linear(channel):57 c = channel / 25558 return c / 12.92 if c <= 0.03928 else ((c + 0.055) / 1.055) ** 2.459
60
61def relative_luminance(rgb):62 r, g, b = rgb63 return 0.2126 * _linear(r) + 0.7152 * _linear(g) + 0.0722 * _linear(b)64
65
66def contrast_ratio(rgb1, rgb2):67 l1, l2 = relative_luminance(rgb1), relative_luminance(rgb2)68 hi, lo = max(l1, l2), min(l1, l2)69 return round((hi + 0.05) / (lo + 0.05), 2)70
71
72def _wcag_grade(ratio):73 if ratio >= 7:74 return "AAA"75 if ratio >= 4.5:76 return "AA"77 if ratio >= 3:78 return "AA Large"79 return "Fail"80
81
82def best_text_color(rgb):83 white, black = (255, 255, 255), (0, 0, 0)84 return "#FFFFFF" if contrast_ratio(rgb, white) >= contrast_ratio(rgb, black) else "#000000"85
86
87# ===========================================================================88# Algorithmic color naming89# ===========================================================================90
91_HUE_NAMES = [92 (15, "red"), (45, "orange"), (70, "yellow"), (95, "lime"),93 (145, "green"), (175, "teal"), (200, "cyan"), (235, "blue"),94 (275, "indigo"), (300, "violet"), (330, "magenta"), (360, "red"),95]96
97
98def name_color(rgb):99 h, s, l = rgb_to_hsl(rgb)100 if l <= 6:101 return "black"102 if l >= 96:103 return "white"104 if s <= 8:105 if l < 25:106 return "charcoal"107 if l < 45:108 return "dark gray"109 if l < 65:110 return "gray"111 return "light gray"112 base = next(name for bound, name in _HUE_NAMES if h < bound)113 light = ""114 if l < 22:115 light = "very dark "116 elif l < 38:117 light = "dark "118 elif l > 82:119 light = "very light "120 elif l > 66:121 light = "light "122 sat = ""123 if s < 25:124 sat = "muted "125 elif s > 85 and 30 <= l <= 70:126 sat = "vivid "127 return (light + sat + base).strip()128
129
130def temperature(hue):131 h = hue % 360132 if h < 75 or h >= 300:133 return "warm"134 if 150 <= h < 270:135 return "cool"136 return "neutral"137
138
139# ===========================================================================140# Harmony schemes141# ===========================================================================142
143
144def _rot(h, s, l, offsets):145 return [((h + o) % 360, s, l) for o in offsets]146
147
148def scheme_colors(h, s, l, scheme):149 table = {150 "complementary": [0, 180],151 "analogous": [-60, -30, 0, 30, 60],152 "triadic": [0, 120, 240],153 "split_complementary": [0, 150, 210],154 "tetradic": [0, 60, 180, 240],155 "square": [0, 90, 180, 270],156 }157 if scheme in table:158 return _rot(h, s, l, table[scheme])159 if scheme == "monochromatic":160 return [(h, s, lv) for lv in (20, 35, 50, 65, 80)]161 if scheme == "shades":162 return [(h, s, lv) for lv in (10, 25, 40, 55, 70)]163 if scheme == "tints":164 return [(h, s, lv) for lv in (50, 62, 74, 86, 94)]165 raise ValueError(f"Unknown scheme: {scheme}")166
167
168ALL_SCHEMES = [169 "complementary", "analogous", "triadic", "split_complementary",170 "tetradic", "square", "monochromatic", "shades", "tints",171]172
173
174# ===========================================================================175# Theme / keyword mapping176# ===========================================================================177
178THEMES = {179 "sunset": (18, 85, 55, "analogous"), "ocean": (200, 70, 45, "analogous"),180 "sea": (195, 68, 47, "analogous"), "forest": (130, 50, 33, "analogous"),181 "jungle": (140, 60, 30, "analogous"), "pastel": (330, 55, 82, "analogous"),182 "vibrant": (350, 90, 55, "triadic"), "corporate": (215, 45, 40, "monochromatic"),183 "business": (210, 40, 42, "monochromatic"), "earth": (30, 42, 40, "analogous"),184 "earthy": (30, 42, 40, "analogous"), "candy": (325, 80, 70, "triadic"),185 "retro": (35, 70, 50, "split_complementary"), "vintage": (35, 45, 48, "analogous"),186 "cyberpunk": (300, 90, 55, "split_complementary"), "neon": (140, 100, 55, "triadic"),187 "monochrome": (0, 0, 50, "monochromatic"), "autumn": (25, 70, 45, "analogous"),188 "fall": (25, 70, 45, "analogous"), "spring": (100, 60, 60, "analogous"),189 "summer": (48, 85, 58, "triadic"), "winter": (210, 30, 62, "analogous"),190 "coffee": (25, 50, 30, "monochromatic"), "luxury": (280, 40, 35, "monochromatic"),191 "gold": (45, 75, 50, "analogous"), "rose": (345, 60, 62, "analogous"),192 "mint": (155, 55, 65, "analogous"), "lavender": (270, 45, 70, "analogous"),193 "fire": (12, 90, 50, "analogous"), "ice": (195, 45, 78, "analogous"),194 "tropical": (165, 75, 50, "triadic"), "desert": (35, 55, 55, "analogous"),195 "berry": (330, 65, 40, "analogous"), "midnight": (230, 60, 22, "monochromatic"),196}197
198_MOD_LIGHT = {"pastel": 18, "light": 15, "soft": 10, "dark": -18, "deep": -18, "night": -20}199_MOD_SAT = {"pastel": -25, "muted": -30, "soft": -15, "vivid": 25, "bright": 25, "bold": 20, "neon": 35}200
201
202def _stable_hue(text):203 return int(hashlib.md5(text.encode("utf-8")).hexdigest(), 16) % 360204
205
206def theme_to_base(text):207 words = re.findall(r"[a-z]+", str(text).lower())208 base = None209 for w in words:210 if w in THEMES:211 base = THEMES[w]212 break213 if base is None:214 h = _stable_hue(str(text).lower().strip())215 schemes = ["analogous", "triadic", "complementary", "split_complementary"]216 base = (h, 65, 52, schemes[sum(ord(c) for c in str(text)) % len(schemes)])217 h, s, l, scheme = base218 for w in words:219 l += _MOD_LIGHT.get(w, 0)220 s += _MOD_SAT.get(w, 0)221 return (h, max(0, min(100, s)), max(8, min(94, l)), scheme)222
223
224# ===========================================================================225# Swatch and palette assembly226# ===========================================================================227
228
229def swatch_from_rgb(rgb):230 rgb = tuple(int(round(c)) for c in rgb)231 hsl = rgb_to_hsl(rgb)232 on_white = contrast_ratio(rgb, (255, 255, 255))233 on_black = contrast_ratio(rgb, (0, 0, 0))234 return {235 "hex": rgb_to_hex(rgb),236 "rgb": {"r": rgb[0], "g": rgb[1], "b": rgb[2]},237 "hsl": {"h": hsl[0], "s": hsl[1], "l": hsl[2]},238 "name": name_color(rgb),239 "luminance": round(relative_luminance(rgb), 4),240 "bestTextColor": best_text_color(rgb),241 "contrast": {"onWhite": on_white, "onBlack": on_black},242 "wcag": {"onWhite": _wcag_grade(on_white), "onBlack": _wcag_grade(on_black)},243 }244
245
246def make_swatch(h, s, l):247 return swatch_from_rgb(hsl_to_rgb(h, s, l))248
249
250def build_swatches(h, s, l, scheme):251 return [make_swatch(*c) for c in scheme_colors(h, s, l, scheme)]252
253
254def _export_blocks(swatches):255 hexes = [sw["hex"] for sw in swatches]256 css = ":root {\n" + "\n".join(f" --color-{i + 1}: {hx};" for i, hx in enumerate(hexes)) + "\n}"257 scss = "\n".join(f"$color-{i + 1}: {hx};" for i, hx in enumerate(hexes))258 tailwind = (259 "module.exports = {\n theme: {\n extend: {\n colors: {\n"260 + "\n".join(f" 'brand-{i + 1}': '{hx}'," for i, hx in enumerate(hexes))261 + "\n }\n }\n }\n}"262 )263 return {"hexList": hexes, "css": css, "scss": scss, "tailwind": tailwind}264
265
266def generate(base_hsl, scheme, include_all=True):267 h, s, l = base_hsl268 swatches = build_swatches(h, s, l, scheme)269 base_rgb = hsl_to_rgb(h, s, l)270 result = {271 "baseColor": rgb_to_hex(base_rgb),272 "scheme": scheme,273 "temperature": temperature(h),274 "colors": swatches,275 "exports": _export_blocks(swatches),276 "hasReadableColor": any(277 sw["contrast"]["onWhite"] >= 4.5 or sw["contrast"]["onBlack"] >= 4.5278 for sw in swatches279 ),280 }281 if include_all:282 result["allSchemes"] = {283 name: [sw["hex"] for sw in build_swatches(h, s, l, name)]284 for name in ALL_SCHEMES285 }286 return result287
288
289# ===========================================================================290# Image extraction (optional, lazy imports)291# ===========================================================================292
293
294def extract_from_image_bytes(raw, n_colors):295 from io import BytesIO296 import numpy as np297 from PIL import Image298
299 img = Image.open(BytesIO(raw)).convert("RGB")300 img.thumbnail((200, 200))301 arr = np.asarray(img, dtype=float).reshape(-1, 3)302 k = max(2, min(10, int(n_colors)))303 rng = np.random.default_rng(42)304 centers = arr[rng.choice(len(arr), k, replace=False)].copy()305 labels = np.zeros(len(arr), dtype=int)306 for _ in range(15):307 dists = ((arr[:, None, :] - centers[None, :, :]) ** 2).sum(2)308 labels = dists.argmin(1)309 new_centers = np.array([310 arr[labels == i].mean(0) if (labels == i).any() else centers[i]311 for i in range(k)312 ])313 if np.allclose(new_centers, centers):314 centers = new_centers315 break316 centers = new_centers317 counts = np.bincount(labels, minlength=k)318 total = float(len(arr))319 swatches = []320 for i in counts.argsort()[::-1]:321 sw = swatch_from_rgb(tuple(centers[i]))322 sw["proportion"] = round(float(counts[i]) / total, 4)323 swatches.append(sw)324 return swatches325
326
327def fetch_image(url):328 from urllib.request import Request, urlopen329 req = Request(url, headers={"User-Agent": "Mozilla/5.0 (Apify Color Palette Studio)"})330 with urlopen(req, timeout=30) as resp:331 return resp.read()332
333
334# ===========================================================================335# Query handling336# ===========================================================================337
338_HEX_RE = re.compile(r"^#?[0-9a-fA-F]{3}([0-9a-fA-F]{3})?$")339
340
341def classify(query):342 s = str(query).strip()343 if s.lower().startswith(("http://", "https://")):344 return "image"345 if _HEX_RE.match(s):346 return "color"347 return "theme"348
349
350def process_query(query, scheme_opt, include_all, colors_per_image):351 mode = classify(query)352 now = datetime.now(timezone.utc).isoformat()353
354 if mode == "color":355 h, s, l = rgb_to_hsl(hex_to_rgb(query))356 scheme = "analogous" if scheme_opt == "auto" else scheme_opt357 result = generate((h, s, l), scheme, include_all)358 result.update({"query": str(query), "mode": "color", "generatedAt": now})359 return result360
361 if mode == "theme":362 h, s, l, default_scheme = theme_to_base(query)363 scheme = default_scheme if scheme_opt == "auto" else scheme_opt364 result = generate((h, s, l), scheme, include_all)365 result.update({"query": str(query), "mode": "theme", "generatedAt": now})366 return result367
368 # image369 raw = fetch_image(query)370 swatches = extract_from_image_bytes(raw, colors_per_image)371 dominant = swatches[0]372 h, s, l = dominant["hsl"]["h"], dominant["hsl"]["s"], dominant["hsl"]["l"]373 scheme = "analogous" if scheme_opt == "auto" else scheme_opt374 suggested = generate((h, s, l), scheme, include_all)375 return {376 "query": str(query),377 "mode": "image",378 "baseColor": dominant["hex"],379 "temperature": temperature(h),380 "colors": swatches,381 "exports": _export_blocks(swatches),382 "suggestedHarmony": {"scheme": scheme, "colors": suggested["colors"]},383 "allSchemes": suggested.get("allSchemes"),384 "generatedAt": now,385 }386
387
388# ===========================================================================389# Actor entry point390# ===========================================================================391
392
393async def main():394 async with Actor:395 actor_input = await Actor.get_input() or {}396 queries = actor_input.get("queries") or ["#2E86DE", "sunset", "forest"]397 if isinstance(queries, str):398 queries = [queries]399 scheme_opt = actor_input.get("scheme", "auto")400 include_all = actor_input.get("includeAllSchemes", True)401 colors_per_image = actor_input.get("colorsPerImage", 6)402
403 cleaned = [str(q).strip() for q in queries if str(q).strip()]404 if not cleaned:405 cleaned = ["#2E86DE", "sunset"]406
407 Actor.log.info(f"Generating palettes for {len(cleaned)} query(ies).")408 ok = 0409 for query in cleaned:410 try:411 item = process_query(query, scheme_opt, include_all, colors_per_image)412 await Actor.push_data(item)413 try:414 await Actor.charge("palette")415 except Exception as charge_err:416 Actor.log.debug(f"charge skipped: {charge_err}")417 ok += 1418 Actor.log.info(f"OK [{item['mode']}] {query} -> {item['baseColor']}")419 except Exception as err:420 Actor.log.warning(f"Failed for {query!r}: {err}")421 await Actor.push_data({422 "query": str(query),423 "error": str(err),424 "generatedAt": datetime.now(timezone.utc).isoformat(),425 })426 Actor.log.info(f"Done. {ok}/{len(cleaned)} palettes generated.")
.git.mise.toml.nvim.luastorage
# The rest is copied from https://github.com/github/gitignore/blob/main/Python.gitignore
# Byte-compiled / optimized / DLL files__pycache__/*.py[cod]*$py.class
# C extensions*.so
# Distribution / packaging.Pythonbuild/develop-eggs/dist/downloads/eggs/.eggs/lib/lib64/parts/sdist/var/wheels/share/python-wheels/*.egg-info/.installed.cfg*.eggMANIFEST
# PyInstaller# Usually these files are written by a python script from a template# before PyInstaller builds the exe, so as to inject date/other infos into it.*.manifest*.spec
# Installer logspip-log.txtpip-delete-this-directory.txt
# Unit test / coverage reportshtmlcov/.tox/.nox/.coverage.coverage.*.cachenosetests.xmlcoverage.xml*.cover*.py,cover.hypothesis/.pytest_cache/cover/
# Translations*.mo*.pot
# Django stuff:*.loglocal_settings.pydb.sqlite3db.sqlite3-journal
# Flask stuff:instance/.webassets-cache
# Scrapy stuff:.scrapy
# Sphinx documentationdocs/_build/
# PyBuilder.pybuilder/target/
# Jupyter Notebook.ipynb_checkpoints
# IPythonprofile_default/ipython_config.py
# pyenv# For a library or package, you might want to ignore these files since the code is# intended to run in multiple environments; otherwise, check them in:.python-version
# pdm# Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.#pdm.lock# pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it# in version control.# https://pdm.fming.dev/latest/usage/project/#working-with-version-control.pdm.toml.pdm-python.pdm-build/
# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm__pypackages__/
# Celery stuffcelerybeat-schedulecelerybeat.pid
# SageMath parsed files*.sage.py
# Environments.env.venvenv/venv/ENV/env.bak/venv.bak/
# Spyder project settings.spyderproject.spyproject
# Rope project settings.ropeproject
# mkdocs documentation/site
# mypy.mypy_cache/.dmypy.jsondmypy.json
# Pyre type checker.pyre/
# pytype static type analyzer.pytype/
# Cython debug symbolscython_debug/
# PyCharm# JetBrains specific template is maintained in a separate JetBrains.gitignore that can# be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore# and can be added to the global gitignore or merged into this file. For a more nuclear# option (not recommended) you can uncomment the following to ignore the entire idea folder..idea/
# Visual Studio Code# Ignores the folder created by VS Code when changing workspace settings, doing debugger# configuration, etc. Can be commented out to share Workspace Settings within a team.vscode
# Zed editor# Ignores the folder created when setting Project Settings in the Zed editor. Can be commented out# to share Project Settings within a team.zed.mise.toml.nvim.luastorage
# The rest is copied from https://github.com/github/gitignore/blob/main/Python.gitignore
# Byte-compiled / optimized / DLL files__pycache__/*.py[cod]*$py.class
# C extensions*.so
# Distribution / packaging.Pythonbuild/develop-eggs/dist/downloads/eggs/.eggs/lib/lib64/parts/sdist/var/wheels/share/python-wheels/*.egg-info/.installed.cfg*.eggMANIFEST
# PyInstaller# Usually these files are written by a python script from a template# before PyInstaller builds the exe, so as to inject date/other infos into it.*.manifest*.spec
# Installer logspip-log.txtpip-delete-this-directory.txt
# Unit test / coverage reportshtmlcov/.tox/.nox/.coverage.coverage.*.cachenosetests.xmlcoverage.xml*.cover*.py,cover.hypothesis/.pytest_cache/cover/
# Translations*.mo*.pot
# Django stuff:*.loglocal_settings.pydb.sqlite3db.sqlite3-journal
# Flask stuff:instance/.webassets-cache
# Scrapy stuff:.scrapy
# Sphinx documentationdocs/_build/
# PyBuilder.pybuilder/target/
# Jupyter Notebook.ipynb_checkpoints
# IPythonprofile_default/ipython_config.py
# pyenv# For a library or package, you might want to ignore these files since the code is# intended to run in multiple environments; otherwise, check them in:.python-version
# pdm# Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.#pdm.lock# pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it# in version control.# https://pdm.fming.dev/latest/usage/project/#working-with-version-control.pdm.toml.pdm-python.pdm-build/
# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm__pypackages__/
# Celery stuffcelerybeat-schedulecelerybeat.pid
# SageMath parsed files*.sage.py
# Environments.env.venvenv/venv/ENV/env.bak/venv.bak/
# Spyder project settings.spyderproject.spyproject
# Rope project settings.ropeproject
# mkdocs documentation/site
# mypy.mypy_cache/.dmypy.jsondmypy.json
# Pyre type checker.pyre/
# pytype static type analyzer.pytype/
# Cython debug symbolscython_debug/
# PyCharm# JetBrains specific template is maintained in a separate JetBrains.gitignore that can# be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore# and can be added to the global gitignore or merged into this file. For a more nuclear# option (not recommended) you can uncomment the following to ignore the entire idea folder..idea/
# Visual Studio Code# Ignores the folder created by VS Code when changing workspace settings, doing debugger# configuration, etc. Can be commented out to share Workspace Settings within a team.vscode
# Zed editor# Ignores the folder created when setting Project Settings in the Zed editor. Can be commented out# to share Project Settings within a team.zed1# Apify Actors Development Guide2
3Important: Before you begin, fill in the `generatedBy` property in the meta section of `.actor/actor.json`. Replace it with the tool and model you're currently using, such as "Claude Code with Claude Sonnet 4.5". This helps Apify monitor and improve AGENTS.md for specific AI tools and models.4
5## What are Apify Actors?6
7- Actors are serverless programs that run in the cloud. They're inspired by the UNIX philosophy - programs that do one thing well and can be easily combined to build complex systems.8- Actors are programs packaged as Docker images that run in isolated containers9
10## Core Concepts11
12- Accept well-defined JSON input13- Perform isolated tasks (web scraping, automation, data processing)14- Produce structured JSON output to datasets and/or store data in key-value stores15- Can run from seconds to hours or even indefinitely16- Persist state and can be restarted17
18## Do19
20- accept well-defined JSON input and produce structured JSON output21- use Apify SDK (`apify`) for code running ON Apify platform22- validate input early with proper error handling and fail gracefully23- use CheerioCrawler for static HTML content (10x faster than browsers)24- use PlaywrightCrawler only for JavaScript-heavy sites and dynamic content25- use router pattern (createCheerioRouter/createPlaywrightRouter) for complex crawls26- implement retry strategies with exponential backoff for failed requests27- use proper concurrency settings (HTTP: 10-50, Browser: 1-5)28- set sensible defaults in `.actor/input_schema.json` for all optional fields29- set up output schema in `.actor/output_schema.json`30- clean and validate data before pushing to dataset31- use semantic CSS selectors and fallback strategies for missing elements32- respect robots.txt, ToS, and implement rate limiting with delays33- check which tools (cheerio/playwright/crawlee) are installed before applying guidance34- use `Actor.log` for logging (censors sensitive data)35- implement readiness probe handler for standby Actors36- handle the `aborting` event to gracefully shut down when Actor is stopped37
38## Don't39
40- do not rely on `Dataset.getInfo()` for final counts on Cloud platform41- do not use browser crawlers when HTTP/Cheerio works (massive performance gains with HTTP)42- do not hard code values that should be in input schema or environment variables43- do not skip input validation or error handling44- do not overload servers - use appropriate concurrency and delays45- do not scrape prohibited content or ignore Terms of Service46- do not store personal/sensitive data unless explicitly permitted47- do not use deprecated options like `requestHandlerTimeoutMillis` on CheerioCrawler (v3.x)48- do not use `additionalHttpHeaders` - use `preNavigationHooks` instead49- do not assume that local storage is persistent or automatically synced to Apify Console - when running locally with `apify run`, the `storage/` directory is local-only and is NOT pushed to the Cloud50- do not disable standby mode (`usesStandbyMode: false`) without explicit permission51
52## Logging53
54- **ALWAYS use `Actor.log` for logging** - This logger contains critical security logic including censoring sensitive data (Apify tokens, API keys, credentials) to prevent accidental exposure in logs55
56### Available Log Levels57
58The Apify Actor logger provides the following methods for logging:59
60- `Actor.log.debug()` - Debug level logs (detailed diagnostic information)61- `Actor.log.info()` - Info level logs (general informational messages)62- `Actor.log.warning()` - Warning level logs (warning messages for potentially problematic situations)63- `Actor.log.error()` - Error level logs (error messages for failures)64- `Actor.log.exception()` - Exception level logs (for exceptions with stack traces)65
66**Best practices:**67
68- Use `Actor.log.debug()` for detailed operation-level diagnostics (inside functions)69- Use `Actor.log.info()` for general informational messages (API requests, successful operations)70- Use `Actor.log.warning()` for potentially problematic situations (validation failures, unexpected states)71- Use `Actor.log.error()` for actual errors and failures72- Use `Actor.log.exception()` for caught exceptions with stack traces73
74## Graceful Abort Handling75
76Handle the `aborting` event to terminate the Actor quickly when stopped by user or platform, minimizing costs especially for PPU/PPE+U billing.77
78```python79import asyncio80
81async def on_aborting() -> None:82 # Persist any state, do any cleanup you need, and terminate the Actor using `await Actor.exit()` explicitly as soon as possible83 # This will help ensure that the Actor is doing best effort to honor any potential limits on costs of a single run set by the user84 # Wait 1 second to allow Crawlee/SDK state persistence operations to complete85 # This is a temporary workaround until SDK implements proper state persistence in the aborting event86 await asyncio.sleep(1)87 await Actor.exit()88
89Actor.on('aborting', on_aborting)90```91
92## Standby Mode93
94- **NEVER disable standby mode (`usesStandbyMode: false`) in `.actor/actor.json` without explicit permission** - Actor Standby mode solves this problem by letting you have the Actor ready in the background, waiting for the incoming HTTP requests. In a sense, the Actor behaves like a real-time web server or standard API server instead of running the logic once to process everything in batch. Always keep `usesStandbyMode: true` unless there is a specific documented reason to disable it95- **ALWAYS implement readiness probe handler for standby Actors** - Handle the `x-apify-container-server-readiness-probe` header at GET / endpoint to ensure proper Actor lifecycle management96
97You can recognize a standby Actor by checking the `usesStandbyMode` property in `.actor/actor.json`. Only implement the readiness probe if this property is set to `true`.98
99### Readiness Probe Implementation Example100
101```python102# Apify standby readiness probe103from http.server import SimpleHTTPRequestHandler104
105class GetHandler(SimpleHTTPRequestHandler):106 def do_GET(self):107 # Handle Apify standby readiness probe108 if 'x-apify-container-server-readiness-probe' in self.headers:109 self.send_response(200)110 self.end_headers()111 self.wfile.write(b'Readiness probe OK')112 return113
114 self.send_response(200)115 self.end_headers()116 self.wfile.write(b'Actor is ready')117```118
119Key points:120
121- Detect the `x-apify-container-server-readiness-probe` header in incoming requests122- Respond with HTTP 200 status code for both readiness probe and normal requests123- This enables proper Actor lifecycle management in standby mode124
125## Commands126
127```bash128# Bootstrap & local development129apify create [name] # Create new Actor project from a template130apify init # Initialize Actor in current directory131apify run # Run Actor locally with simulated platform env132apify run --purge # Run after clearing previous local storage133apify validate-schema # Validate .actor/input_schema.json134
135# Authentication & account136apify login # Authenticate account (token stored in ~/.apify)137apify logout # Remove stored credentials138apify info # Print currently authenticated account info139
140# Deployment & remote execution141apify push # Deploy Actor to platform per .actor/actor.json142apify pull <actor> # Download Actor code from the platform143apify call <actor> # Execute Actor remotely on the platform144apify actors build <actor> # Create a new build of an Actor145apify runs ls # List recent runs146
147# Discovery (search Apify Store for community Actors)148apify actors search "<query>" --user-agent <your-agent-name>149apify actors info <actor> # Get details about a specific Actor150
151# Secrets (referenced from actor.json via "@mySecret")152apify secrets add <name> <value> # Store a secret locally; uploaded on push153apify secrets ls # List stored secret keys154
155# Direct API access156apify api <endpoint> # Send an authenticated HTTP request to Apify API157
158# Help159apify help # List all commands160apify <command> --help # Get help for a specific command161```162
163Note: If no dedicated Actor exists for your target, search Apify Store for community options with `apify actors search "<query>" --user-agent <your-agent-name>` before building from scratch.164
165Tip: Inside a running Actor, prefer the SDK (`Actor.get_input()`, `Actor.push_data()`, `Actor.set_value()`) over the equivalent `apify actor` runtime subcommands.166
167## Apify Platform Environment168
169When the Actor runs on the Apify platform, the API token is automatically available via the `APIFY_TOKEN` environment variable (note: the variable is `APIFY_TOKEN`, not `APIFY_API_TOKEN`). The Apify SDK reads it automatically, so you do not need to pass it explicitly. Locally, run `apify login` once and the SDK will use your stored credentials.170
171## Safety and Permissions172
173Allowed without prompt:174
175- read files with `Actor.get_value()`176- push data with `Actor.push_data()`177- set values with `Actor.set_value()`178- enqueue requests to RequestQueue179- run locally with `apify run`180
181Ask first:182
183- npm/pip package installations184- apify push (deployment to cloud)185- proxy configuration changes (requires paid plan)186- Dockerfile changes affecting builds187- deleting datasets or key-value stores188
189## Project Structure190
191.actor/192├── actor.json # Actor config: name, version, env vars, runtime settings193├── input_schema.json # Input validation & Console form definition194└── output_schema.json # Specifies where an Actor stores its output195src/196└── main.js # Actor entry point and orchestrator197storage/ # Local-only storage for development (NOT synced to Cloud)198├── datasets/ # Output items (JSON objects)199├── key_value_stores/ # Files, config, INPUT200└── request_queues/ # Pending crawl requests201Dockerfile # Container image definition202AGENTS.md # AI agent instructions (this file)203
204## Local vs Cloud Storage205
206When running locally with `apify run`, the Apify SDK emulates Cloud storage APIs using the local `storage/` directory. This local storage behaves differently from Cloud storage:207
208- **Local storage is NOT persistent** - The `storage/` directory is meant for local development and testing only. Data stored there (datasets, key-value stores, request queues) exists only on your local disk.209- **Local storage is NOT automatically pushed to Apify Console** - Running `apify run` does not upload any storage data to the Apify platform. The data stays local.210- **Each local run may overwrite previous data** - The local `storage/` directory is reused between runs, but this is local-only behavior, not Cloud persistence.211- **Cloud storage only works when running on Apify platform** - After deploying with `apify push` and running the Actor in the Cloud, storage calls (`Actor.push_data()`, `Actor.set_value()`, etc.) interact with real Apify Cloud storage, which is then visible in the Apify Console.212- **To verify Actor output, deploy and run in Cloud** - Do not rely on local `storage/` contents as proof that data will appear in the Apify Console. Always test by deploying (`apify push`) and running the Actor on the platform.213
214## Actor Input Schema215
216The input schema defines the input parameters for an Actor. It's a JSON object comprising various field types supported by the Apify platform.217
218### Structure219
220```json221{222 "title": "<INPUT-SCHEMA-TITLE>",223 "type": "object",224 "schemaVersion": 1,225 "properties": {/* define input fields here */},226 "required": []227}228```229
230### Example231
232```json233{234 "title": "E-commerce Product Scraper Input",235 "type": "object",236 "schemaVersion": 1,237 "properties": {238 "startUrls": {239 "title": "Start URLs",240 "type": "array",241 "description": "URLs to start scraping from (category pages or product pages)",242 "editor": "requestListSources",243 "default": [{ "url": "https://example.com/category" }],244 "prefill": [{ "url": "https://example.com/category" }]245 },246 "followVariants": {247 "title": "Follow Product Variants",248 "type": "boolean",249 "description": "Whether to scrape product variants (different colors, sizes)",250 "default": true251 },252 "maxRequestsPerCrawl": {253 "title": "Max Requests per Crawl",254 "type": "integer",255 "description": "Maximum number of pages to scrape (0 = unlimited)",256 "default": 1000,257 "minimum": 0258 },259 "proxyConfiguration": {260 "title": "Proxy Configuration",261 "type": "object",262 "description": "Proxy settings for anti-bot protection",263 "editor": "proxy",264 "default": { "useApifyProxy": false }265 },266 "locale": {267 "title": "Locale",268 "type": "string",269 "description": "Language/country code for localized content",270 "default": "cs",271 "enum": ["cs", "en", "de", "sk"],272 "enumTitles": ["Czech", "English", "German", "Slovak"]273 }274 },275 "required": ["startUrls"]276}277```278
279## Actor Output Schema280
281The Actor output schema builds upon the schemas for the dataset and key-value store. It specifies where an Actor stores its output and defines templates for accessing that output. Apify Console uses these output definitions to display run results.282
283### Structure284
285```json286{287 "actorOutputSchemaVersion": 1,288 "title": "<OUTPUT-SCHEMA-TITLE>",289 "properties": {/* define your outputs here */}290}291```292
293### Example294
295```json296{297 "actorOutputSchemaVersion": 1,298 "title": "Output schema of the files scraper",299 "properties": {300 "files": {301 "type": "string",302 "title": "Files",303 "template": "{{links.apiDefaultKeyValueStoreUrl}}/keys"304 },305 "dataset": {306 "type": "string",307 "title": "Dataset",308 "template": "{{links.apiDefaultDatasetUrl}}/items"309 }310 }311}312```313
314### Output Schema Template Variables315
316- `links` (object) - Contains quick links to most commonly used URLs317- `links.publicRunUrl` (string) - Public run url in format `https://console.apify.com/view/runs/:runId`318- `links.consoleRunUrl` (string) - Console run url in format `https://console.apify.com/actors/runs/:runId`319- `links.apiRunUrl` (string) - API run url in format `https://api.apify.com/v2/actor-runs/:runId`320- `links.apiDefaultDatasetUrl` (string) - API url of default dataset in format `https://api.apify.com/v2/datasets/:defaultDatasetId`321- `links.apiDefaultKeyValueStoreUrl` (string) - API url of default key-value store in format `https://api.apify.com/v2/key-value-stores/:defaultKeyValueStoreId`322- `links.containerRunUrl` (string) - URL of a webserver running inside the run in format `https://<containerId>.runs.apify.net/`323- `run` (object) - Contains information about the run same as it is returned from the `GET Run` API endpoint324- `run.defaultDatasetId` (string) - ID of the default dataset325- `run.defaultKeyValueStoreId` (string) - ID of the default key-value store326
327## Dataset Schema Specification328
329The dataset schema defines how your Actor's output data is structured, transformed, and displayed in the Output tab in the Apify Console.330
331### Example332
333Consider an example Actor that calls `Actor.pushData()` to store data into dataset:334
335```python336# Dataset push example (Python)337import asyncio338from datetime import datetime339from apify import Actor340
341async def main():342 await Actor.init()343
344 # Actor code345 await Actor.push_data({346 'numericField': 10,347 'pictureUrl': 'https://www.google.com/images/branding/googlelogo/2x/googlelogo_color_92x30dp.png',348 'linkUrl': 'https://google.com',349 'textField': 'Google',350 'booleanField': True,351 'dateField': datetime.now().isoformat(),352 'arrayField': ['#hello', '#world'],353 'objectField': {},354 })355
356 # Exit successfully357 await Actor.exit()358
359if __name__ == '__main__':360 asyncio.run(main())361```362
363To set up the Actor's output tab UI, reference a dataset schema file in `.actor/actor.json`:364
365```json366{367 "actorSpecification": 1,368 "name": "book-library-scraper",369 "title": "Book Library Scraper",370 "version": "1.0.0",371 "storages": {372 "dataset": "./dataset_schema.json"373 }374}375```376
377Then create the dataset schema in `.actor/dataset_schema.json`:378
379```json380{381 "actorSpecification": 1,382 "fields": {},383 "views": {384 "overview": {385 "title": "Overview",386 "transformation": {387 "fields": [388 "pictureUrl",389 "linkUrl",390 "textField",391 "booleanField",392 "arrayField",393 "objectField",394 "dateField",395 "numericField"396 ]397 },398 "display": {399 "component": "table",400 "properties": {401 "pictureUrl": {402 "label": "Image",403 "format": "image"404 },405 "linkUrl": {406 "label": "Link",407 "format": "link"408 },409 "textField": {410 "label": "Text",411 "format": "text"412 },413 "booleanField": {414 "label": "Boolean",415 "format": "boolean"416 },417 "arrayField": {418 "label": "Array",419 "format": "array"420 },421 "objectField": {422 "label": "Object",423 "format": "object"424 },425 "dateField": {426 "label": "Date",427 "format": "date"428 },429 "numericField": {430 "label": "Number",431 "format": "number"432 }433 }434 }435 }436 }437}438```439
440### Structure441
442```json443{444 "actorSpecification": 1,445 "fields": {},446 "views": {447 "<VIEW_NAME>": {448 "title": "string (required)",449 "description": "string (optional)",450 "transformation": {451 "fields": ["string (required)"],452 "unwind": ["string (optional)"],453 "flatten": ["string (optional)"],454 "omit": ["string (optional)"],455 "limit": "integer (optional)",456 "desc": "boolean (optional)"457 },458 "display": {459 "component": "table (required)",460 "properties": {461 "<FIELD_NAME>": {462 "label": "string (optional)",463 "format": "text|number|date|link|boolean|image|array|object (optional)"464 }465 }466 }467 }468 }469}470```471
472**Dataset Schema Properties:**473
474- `actorSpecification` (integer, required) - Specifies the version of dataset schema structure document (currently only version 1)475- `fields` (JSONSchema object, required) - Schema of one dataset object (use JsonSchema Draft 2020-12 or compatible)476- `views` (DatasetView object, required) - Object with API and UI views description477
478**DatasetView Properties:**479
480- `title` (string, required) - Visible in UI Output tab and API481- `description` (string, optional) - Only available in API response482- `transformation` (ViewTransformation object, required) - Data transformation applied when loading from Dataset API483- `display` (ViewDisplay object, required) - Output tab UI visualization definition484
485**ViewTransformation Properties:**486
487- `fields` (string[], required) - Fields to present in output (order matches column order)488- `unwind` (string[], optional) - Deconstructs nested children into parent object489- `flatten` (string[], optional) - Transforms nested object into flat structure490- `omit` (string[], optional) - Removes specified fields from output491- `limit` (integer, optional) - Maximum number of results (default: all)492- `desc` (boolean, optional) - Sort order (true = newest first)493
494**ViewDisplay Properties:**495
496- `component` (string, required) - Only `table` is available497- `properties` (Object, optional) - Keys matching `transformation.fields` with ViewDisplayProperty values498
499**ViewDisplayProperty Properties:**500
501- `label` (string, optional) - Table column header502- `format` (string, optional) - One of: `text`, `number`, `date`, `link`, `boolean`, `image`, `array`, `object`503
504## Key-Value Store Schema Specification505
506The key-value store schema organizes keys into logical groups called collections for easier data management.507
508### Example509
510Consider an example Actor that calls `Actor.setValue()` to save records into the key-value store:511
512```python513# Key-Value Store set example (Python)514import asyncio515from apify import Actor516
517async def main():518 await Actor.init()519
520 # Actor code521 await Actor.set_value('document-1', 'my text data', content_type='text/plain')522
523 image_id = '123' # example placeholder524 image_buffer = b'...' # bytes buffer with image data525 await Actor.set_value(f'image-{image_id}', image_buffer, content_type='image/jpeg')526
527 # Exit successfully528 await Actor.exit()529
530if __name__ == '__main__':531 asyncio.run(main())532```533
534To configure the key-value store schema, reference a schema file in `.actor/actor.json`:535
536```json537{538 "actorSpecification": 1,539 "name": "data-collector",540 "title": "Data Collector",541 "version": "1.0.0",542 "storages": {543 "keyValueStore": "./key_value_store_schema.json"544 }545}546```547
548Then create the key-value store schema in `.actor/key_value_store_schema.json`:549
550```json551{552 "actorKeyValueStoreSchemaVersion": 1,553 "title": "Key-Value Store Schema",554 "collections": {555 "documents": {556 "title": "Documents",557 "description": "Text documents stored by the Actor",558 "keyPrefix": "document-"559 },560 "images": {561 "title": "Images",562 "description": "Images stored by the Actor",563 "keyPrefix": "image-",564 "contentTypes": ["image/jpeg"]565 }566 }567}568```569
570### Structure571
572```json573{574 "actorKeyValueStoreSchemaVersion": 1,575 "title": "string (required)",576 "description": "string (optional)",577 "collections": {578 "<COLLECTION_NAME>": {579 "title": "string (required)",580 "description": "string (optional)",581 "key": "string (conditional - use key OR keyPrefix)",582 "keyPrefix": "string (conditional - use key OR keyPrefix)",583 "contentTypes": ["string (optional)"],584 "jsonSchema": "object (optional)"585 }586 }587}588```589
590**Key-Value Store Schema Properties:**591
592- `actorKeyValueStoreSchemaVersion` (integer, required) - Version of key-value store schema structure document (currently only version 1)593- `title` (string, required) - Title of the schema594- `description` (string, optional) - Description of the schema595- `collections` (Object, required) - Object where each key is a collection ID and value is a Collection object596
597**Collection Properties:**598
599- `title` (string, required) - Collection title shown in UI tabs600- `description` (string, optional) - Description appearing in UI tooltips601- `key` (string, conditional\*) - Single specific key for this collection602- `keyPrefix` (string, conditional\*) - Prefix for keys included in this collection603- `contentTypes` (string[], optional) - Allowed content types for validation604- `jsonSchema` (object, optional) - JSON Schema Draft 07 format for `application/json` content type validation605
606\*Either `key` or `keyPrefix` must be specified for each collection, but not both.607
608## Actor README609
610**Always generate a README.md file as part of Actor development.** The README is the Actor's public landing page on Apify Store - it serves as SEO, first impression, documentation, and support page combined.611
612### Required: Generate README automatically613
614When building an Actor, always create a `README.md` in the project root. Do not wait for the user to ask for it. The README is a critical part of a complete Actor.615
616### README structure617
618Write in Markdown. Use H2 (`##`) for main sections (these become the table of contents) and H3 (`###`) for subsections. Do not use H1 - the Actor name is automatically the H1. Aim for at least 300 words.619
620Include these sections in order:621
6221. **What does [Actor name] do?** - 2-3 sentences explaining what it does, what data it extracts, and how to try it. Link to the target website. Mention Apify platform advantages (API access, scheduling, integrations, proxy rotation, monitoring).6232. **Why use [Actor name]?** - Business use cases and benefits.6243. **How to use [Actor name]** - Numbered step-by-step tutorial. Keep it simple and reassuring.6254. **Input** - Describe input fields. Reference the Input tab. Optionally include a screenshot or JSON example of the input schema.6265. **Output** - Show a simplified JSON output example. Mention "You can download the dataset in various formats such as JSON, HTML, CSV, or Excel."6276. **Data table** - If the Actor extracts data, include a table of the main data fields it outputs.6287. **Pricing / Cost estimation** - Set expectations on cost. Mention free tier limits if applicable. Frame as "How much does it cost to scrape [target site]?"6298. **Tips or Advanced options** - How to optimize runs, limit compute units, improve speed or accuracy.6309. **FAQ, disclaimers, and support** - Legality disclaimer for scrapers, known limitations, link to Issues tab for feedback, mention custom solution availability.631
632### README best practices633
634- Write SEO-friendly headings with relevant keywords (e.g., "How to scrape [site] data" not just "Tutorial")635- Bold the most important words in the intro636- The first 25% of the README matters most - front-load the value proposition637- Match the tone to the target audience: simple language for no-code users, technical details for developers638- Include a JSON output example showing 1-2 representative items639- Reference these top Actors for README best practices: https://apify.com/apify/instagram-scraper and https://apify.com/compass/crawler-google-places640- Embed YouTube video URLs on their own line (Apify Console auto-renders them)641- Use HTML for image sizing if needed; CSS is not supported642
643## MCP Tools644
645### Apify MCP646
647If the Apify MCP server is configured, use these tools for documentation:648
649- `search-apify-docs` - Search documentation650- `fetch-apify-docs` - Get full doc pages651
652Otherwise, reference: `@https://mcp.apify.com/`653
654### Playwright MCP (debugging)655
656The Playwright MCP server is a useful tool for debugging Actors that interact with the web - it lets the agent drive a real browser to inspect pages, capture selectors, and reproduce issues.657
658Install with the Claude Code CLI:659
660```bash661claude mcp add playwright npx @playwright/mcp@latest662```663
664Or add it manually to your MCP config:665
666```json667{668 "mcpServers": {669 "playwright": {670 "command": "npx",671 "args": ["@playwright/mcp@latest"]672 }673 }674}675```676
677## Resources678
679- [docs.apify.com/llms.txt](https://docs.apify.com/llms.txt) - Quick reference680- [docs.apify.com/llms-full.txt](https://docs.apify.com/llms-full.txt) - Complete docs681- [crawlee.dev](https://crawlee.dev) - Crawlee documentation682- [whitepaper.actor](https://raw.githubusercontent.com/apify/actor-whitepaper/refs/heads/master/README.md) - Complete Actor specification1@AGENTS.mdFROM apify/actor-python:3.11
COPY requirements.txt ./RUN echo "Python version:" && python3 --version \ && echo "Installing dependencies:" \ && pip install -U pip \ && pip install -r requirements.txt \ && echo "All dependencies installed:" \ && pip freeze
COPY . ./
CMD ["python3", "-m", "my_actor"]1apify2Pillow>=10.03numpy>=1.26