image-sourcing

name	image-sourcing
description	Find and download existing images from the web using stock photo services like Unsplash, Pexels, and Pixabay. Use when the user wants to find real photographs, stock photos, or existing images rather than generating new ones with AI. Also useful when the user needs royalty-free images, creative commons photos, or reference material from the web.

Image Sourcing from the Web

Step 0 — plan first. Before searching, run the visual-planning skill: clarify the ask, lock the style, pin the message, decide what's IN/OUT, then draft the search query (via media-prompt-craft).

Use WebSearch and WebFetch (or curl via Bash) to find and download existing images from stock photo services and the web.

When to Use

• User asks to "find an image", "get a photo", "download a picture", "search for images"
• User needs real photographs (not AI-generated) — e.g., photos of real places, people, products
• User wants stock photos or royalty-free images for a project
• User mentions Unsplash, Pexels, Pixabay, or other stock photo services
• User needs a quick placeholder or reference image without waiting for AI generation
• User wants images with known licensing (Creative Commons, royalty-free)

When NOT to Use (Use Image Generation Instead)

• User wants a custom illustration, concept art, or something that doesn't exist
• User needs a specific composition that wouldn't be found in stock photos
• User wants to modify or restyle an existing image with AI

CRITICAL RULES

1. NEVER guess or construct image URLs. You cannot know the URL of an image without finding it first. Do not fabricate URLs like https://images.unsplash.com/photo-{id} — these will not work.
2. NEVER try to WebFetch Unsplash/Pexels/Pixabay photo pages to extract download URLs. These sites are JavaScript-heavy and WebFetch cannot extract usable image URLs from them.
3. Always search first, then present options to the user. The workflow is: search → present results → let user choose → download.
4. If you cannot find a suitable image, say so honestly. Do not silently fall back to AI generation. Tell the user what you searched for and that no good match was found, then suggest alternatives (different search terms, or AI generation).

Sourcing Workflow

Step 1: Search for Images Using the Unsplash API

Use WebFetch to query the Unsplash Source/Search API which returns JSON with actual image URLs.

Use the Unsplash search endpoint (no API key needed for basic search):

WebFetch: https://unsplash.com/napi/search/photos?query={keywords}&per_page=9

This returns JSON with an array of results, each containing:

• urls.regular — direct image URL (1080px wide, good for most uses)
• urls.small — smaller version (400px)
• urls.full — full resolution
• urls.raw — raw image (append ?w=1920&q=80 for custom size)
• description or alt_description — what the image shows
• user.name — photographer name
• user.links.html — photographer profile URL
• links.html — link to the photo page on Unsplash

Example:

WebFetch: https://unsplash.com/napi/search/photos?query=mountain+sunset+landscape&per_page=9

You can also search Pexels and Pixabay via web search as a fallback:

WebSearch: "site:pexels.com {subject} photo"
WebSearch: "site:pixabay.com {subject}"

Step 2: Review and Present Options to the User

From the API response, review the results:

• Look at the description and alt_description fields to understand what each image shows
• Select the 3-5 most relevant results
• Present them to the user with:
  • A brief description of each image
  • The photographer's name
  • The Unsplash page link (links.html) so the user can preview
  • A note on which one you'd recommend and why

IMPORTANT: Let the user choose which image(s) they want. Do not download without presenting options first, unless the user explicitly asked for "any" image or the first result.

Step 3: Download the Selected Image

Once the user has chosen (or if they asked for "any"), download using the urls.regular or urls.raw URL from the API response:

# Determine output directory
OUTPUT_DIR="${MEDIA_OUTPUT_DIR:-.}"

# Download using the ACTUAL URL from the API response (not a guessed URL)
curl -L -o "$OUTPUT_DIR/descriptive-name.jpg" "ACTUAL_URL_FROM_API_RESPONSE"

Size options using urls.raw:

• Thumbnail: append ?w=640&q=80
• Medium: append ?w=1280&q=80
• Large: append ?w=1920&q=80
• 4K: append ?w=3840&q=80

Or just use urls.regular for a sensible default size.

Step 4: Report the Result

After downloading, report:

• The file path of the downloaded image
• The source URL (Unsplash page link) and photographer name
• The license type (Unsplash License — free for commercial and non-commercial use)
• Suggested attribution text

Fallback: When the Unsplash API Doesn't Work

If the Unsplash napi endpoint is blocked or returns errors:

1. Use WebSearch with queries like {subject} photo site:unsplash.com or {subject} royalty free stock photo
2. Look at the search result snippets — they often contain useful context about the images
3. Present the search result links to the user so they can browse and choose
4. Do NOT try to WebFetch individual photo pages on Unsplash/Pexels/Pixabay — these are JS-rendered and won't give you download URLs
5. If the user picks an image from search results, ask them to provide the direct image URL, or suggest using AI image generation instead

Stock Photo Services

Unsplash (Recommended — has usable API)

• License: Unsplash License — free for commercial and non-commercial use, no attribution required (but appreciated)
• Quality: High-resolution professional photography
• API endpoint: https://unsplash.com/napi/search/photos?query={keywords}&per_page=9

Pexels

• License: Pexels License — free for commercial and non-commercial use, no attribution required
• Quality: Professional photography and some video
• Search: site:pexels.com {keywords} via WebSearch

Pixabay

• License: Pixabay Content License — free for commercial and non-commercial use
• Quality: Mix of professional and community photos, illustrations, vectors
• Search: site:pixabay.com {keywords} via WebSearch

Other Sources

• Wikimedia Commons: site:commons.wikimedia.org {keywords} — CC-licensed media
• Flickr Creative Commons: site:flickr.com {keywords} creative commons

Attribution Best Practices

Even when not legally required, it's good practice to credit photographers:

Photo by [Photographer Name](https://unsplash.com/@username) on [Unsplash](https://unsplash.com)

Always inform the user of the license terms so they can decide on attribution.

Output Handling — MEDIA_OUTPUT_DIR

When MEDIA_OUTPUT_DIR is set, save downloaded images there to keep them alongside generated media assets. Use descriptive filenames that indicate the content (e.g., mountain-sunset-hero.jpg not image1.jpg).

Tips

• Prefer Unsplash for highest quality — and use its API for reliable image URLs
• Use Pexels or Pixabay as alternatives via web search
• Never guess or fabricate image URLs — always get them from API responses or confirmed sources
• When the user's need is ambiguous, ask whether they want an existing photo or an AI-generated image
• If no suitable stock photo exists for the user's need, say so and suggest AI generation
• Downloaded images can be used as reference_images for the AI image generation tool to create variations