AI-Task-Builder-Image-Collection

Collect images from Prolific participants using the AI Task Builder Collections API. You configure the whole request in config.yaml — no need to edit the code.

Based on the Prolific cookbook: Collecting original data with AI Task Builder Collections.

What this does

Need real-world images for your research — photos of people's desks, pets, groceries, handwriting, anything? This repo is an end-to-end example of collecting exactly that from real participants on Prolific, driven entirely from the command line.

You write one line in config.yaml describing what you want photographed. From there a single script:

1. builds the upload task and a draft study,
2. launches it to recruit real participants,
3. downloads every submitted image — each paired with the participant's age, gender and country.

A companion dashboard streams submissions as they arrive and can summarize the whole batch with Claude vision. The end result is a folder of genuine, demographically-labelled photos ready to analyze — collected in minutes, no manual review UI required.

How it works

Step	What happens	API call
create	Builds a Collection (the upload task) + a draft study	POST /data-collection/collections, POST /studies/
launch	Publishes the study so participants can join	POST /studies/{id}/transition/
status	Shows study status + submission counts	GET /studies/{id}/, GET /studies/{id}/submissions/counts/
results	Exports, downloads and unzips the uploaded images	POST /data-collection/collections/{id}/export

create writes the new collection/study IDs to prolific_state.json so the later steps know what to act on.

Setup

Install dependencies:

pip install -r requirements.txt

Copy the example env file and fill in your credentials:

cp .env.example .env

Then edit .env:

PROLIFIC_API_TOKEN=your_token_here       # app.prolific.com → Settings → API tokens
PROLIFIC_WORKSPACE_ID=your_workspace_id  # from your workspace URL
PROLIFIC_PROJECT_ID=your_project_id      # prolific project list -w <workspace_id>

.env is git-ignored — credentials never live in config.yaml or the code.

Note: AI Task Builder Collections must be enabled on your account, and you should review/launch collection-based studies via this script or the CLI — the researcher web UI isn't fully wired up for them yet.

Run the demo

python prolific_image_collection.py check     # confirm the token works
python prolific_image_collection.py create    # make the collection + draft study
python prolific_image_collection.py launch    # publish (recruits real people, costs funds!)
python prolific_image_collection.py status    # check progress whenever you like
python prolific_image_collection.py results   # download images into ./results/

launch asks for confirmation because it spends real money. Skip it with --yes once you're sure.

Watch submissions live (dashboard)

Instead of re-running status, open a self-refreshing web dashboard that shows submissions arriving in real time:

python dashboard.py                       # serve at http://127.0.0.1:8050
python dashboard.py --port 9000           # different port
python dashboard.py --interval 3          # feed/demographics refresh (default 5s)
python dashboard.py --image-interval 30   # image sync cadence (default 45s)
python dashboard.py --no-images           # counts + demographics only (skip images)
python dashboard.py --study <id>          # watch a specific study (default: prolific_state.json)

Caution: the dashboard shows participant images, age and location. It binds to 127.0.0.1 (your machine only) by default. Don't pass --host 0.0.0.0 unless you intend to expose that participant data to your whole network.

Open the printed URL in a browser. It reuses the same .env credentials and the study id saved by create, and shows:

• a progress bar toward your total_available_places;
• counts by status (approved / awaiting review / active / returned …);
• a live activity feed of individual submissions — new ones flash in — where each row shows the participant's uploaded image plus their age, gender (sex) and location (country of residence). Click an image to view it full-size.

Where each piece comes from, and how live it is:

Data	Source	Freshness
status / counts / feed	GET /studies/{id}/, /submissions/counts/, /submissions/	every --interval (≈5s)
age / gender / location	GET /studies/{id}/export/ (demographics CSV)	every --interval (≈5s)
the uploaded image	POST /data-collection/collections/{id}/export (a batch zip Prolific builds on demand)	every --image-interval (≈45s)

The image is the slow part on purpose: Prolific only exposes uploaded files through that batch export, so the dashboard syncs them on a slower background loop and caches them locally (under your temp dir). An image therefore appears a little after its row does — the row says "image syncing…" until it lands. For large studies, raise --image-interval (or use --no-images) so you're not re-downloading a growing zip too often. Returned / consent-revoked submissions show no demographics or image, by design.

✨ Insights (Claude vision)

If a CLAUDE_API_KEY is set in your .env, the dashboard shows an Insights button. Click it and the synced images (each labelled with the participant's age, gender and country) are sent to Claude, which returns a written analysis for the researcher — what was submitted, recurring themes and outliers, quality/compliance issues, and any measured tendencies across demographics.

CLAUDE_API_KEY=sk-ant-...   # platform.claude.com → API keys

It uses the anthropic Python SDK with the claude-opus-4-8 vision model. To keep cost and latency reasonable it sends up to 16 images per click (raise the MAX_INSIGHT_IMAGES constant in dashboard.py if you want more). No key → the button simply doesn't appear; everything else still works.

Changing the request for participants

Open config.yaml. The main thing to edit is one line:

request:
  what_to_photograph: "a photo of your toothbrush"

Change it to whatever you need — "a photo of your cat", "an image of the view from your window", "a picture of what's in your fridge right now". That text drives the study description, the on-screen instructions, and the upload prompt.

This task collects images only — there are no text questions. You can also tune the upload rules (number_of_images, accepted_file_types, max_file_size_mb) and the study settings (reward, number of participants, time estimate, filters).

Tip: to target a specific population, ask the /prolific-beta-skills:recommend-study-filters skill to generate the study.filters block for you.

Where the images end up

After results, look in ./results/:

results/
└── collection-export-.../
    ├── responses.jsonl   # one JSON record per submission (which file they uploaded)
    ├── collection.json   # maps question IDs → labels
    └── files/            # the uploaded images

---

Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.

Important Notice

This project is provided as-is for educational and research purposes only.

• 🔬 Beta Status: This is experimental code and may contain bugs or incomplete features
• 📚 Not Maintained: No active development or support is provided
• 🎓 Educational Use: Intended as a learning resource
• ⚖️ Use at Your Own Risk: Test thoroughly before using in production environments