Image Search
Use the bundled CLI to find public images by text query:
/opt/hatch/bin/image-search "Golden Gate Bridge at sunset" --max-results 5
Optional result language:
/opt/hatch/bin/image-search "Paris architecture" \
--max-results 5 \
--language fr
The CLI returns structured results and omits unavailable fields. Interpret the
URLs as follows:
media_url is the public source image locator and the preferred full-image
URL when present.
thumbnail_cdn_url is Meta's renderable CDN preview and the fallback when
media_url is absent. Treat it as a cache URL, not the sole durable copy of
an artifact.
media_handle and candidate_ref are internal, non-renderable fields. Do
not fetch, display, or pass them as image URLs.
page_url is the source page. Retain it for provenance or attribution.
The service returns only results with media_url or thumbnail_cdn_url.
Ignore any result that lacks both renderable URL fields.
Choose the result that best matches the request rather than blindly taking the
first one.
This skill returns locators only: it does not download, upload, or turn an
image into a Muse media reference. A Feed may use a suitable remote image URL.
For an Artifact that needs a durable local copy, pass the chosen locator and
source page through the Artifact's supported media-ingestion path; do not treat
the CDN thumbnail as permanent storage.
For an Artifact, choose a download-safe locator before starting any fetch:
Inspect all returned results and prefer an HTTPS media_url with no URL
credentials, query string, or fragment. Preserve result order among those
simple public URLs.
Preflight each candidate like a browser, with a cross-origin referer, then
fetch one candidate at a time with bounded connect and total timeouts
(substitute real values for the placeholders):
curl -fsSLI -A 'Mozilla/5.0' -H 'Accept: image/png,image/jpeg,image/gif,image/webp,image/*;q=0.5' -H 'Referer: <any-https-origin-that-is-not-the-image-host>' '<image-url>'
curl -fsSL --connect-timeout 10 --max-time 60 -A 'Mozilla/5.0' -H 'Accept: image/png,image/jpeg,image/gif,image/webp,image/*;q=0.5' -o '<dest-file>' '<image-url>'
Accept only a final 2xx whose content type and file magic are an image,
then copy those bytes into Artifact-owned storage. Prefer PNG or JPEG:
WEBP is fine except in a Word document, and AVIF except on a web page,
which refuses it at share time with no retry that fixes it. Convert a HEIC
to JPEG anywhere. Reject hotlink-blocked, expiring, redirecting, 403/404,
non-image, watermarked, or unstable URLs. The referer matters: a
hotlink-protected host serves a plain fetch but refuses requests that look
like they come from someone else's page, so a URL that fails this probe
breaks after the Artifact ships even though it loads for you today. The
same preflight applies to any external image URL an Artifact uses, however
it was found.
If no simple media_url succeeds, consider a query-bearing media_url or
thumbnail_cdn_url. Use the returned locator byte-for-byte; never remove or
rewrite its query string to make it look simpler.
Search-result pre-approval records the returned locator's exact path and query,
so a plain GET/HEAD that uses it byte-for-byte is normally allowed without
another prompt even when it has a query string. Do not keep retrying or
substitute an unrelated local image when a fetch fails.
This is text-to-image search, not reverse-image identification. Do not use it
to identify an unknown person from a supplied photograph.
1---2name: image-search3description: "Search the web by text query for image URLs and source pages for feeds, artifacts, and visual references. Does not identify a supplied image or person."4metadata:5 source: https://skillmd.com/skills/win4r/image-search6 includeInPrompt: true7---89# Image Search1011Use the bundled CLI to find public images by text query:1213```sh14/opt/hatch/bin/image-search "Golden Gate Bridge at sunset" --max-results 515```1617Optional result language:1819```sh20/opt/hatch/bin/image-search "Paris architecture" \21 --max-results 5 \22 --language fr23```2425The CLI returns structured results and omits unavailable fields. Interpret the26URLs as follows:2728- `media_url` is the public source image locator and the preferred full-image29 URL when present.30- `thumbnail_cdn_url` is Meta's renderable CDN preview and the fallback when31 `media_url` is absent. Treat it as a cache URL, not the sole durable copy of32 an artifact.33- `media_handle` and `candidate_ref` are internal, non-renderable fields. Do34 not fetch, display, or pass them as image URLs.35- `page_url` is the source page. Retain it for provenance or attribution.3637The service returns only results with `media_url` or `thumbnail_cdn_url`.38Ignore any result that lacks both renderable URL fields.39Choose the result that best matches the request rather than blindly taking the40first one.4142This skill returns locators only: it does not download, upload, or turn an43image into a Muse media reference. A Feed may use a suitable remote image URL.44For an Artifact that needs a durable local copy, pass the chosen locator and45source page through the Artifact's supported media-ingestion path; do not treat46the CDN thumbnail as permanent storage.4748For an Artifact, choose a download-safe locator before starting any fetch:49501. Inspect all returned results and prefer an HTTPS `media_url` with no URL51 credentials, query string, or fragment. Preserve result order among those52 simple public URLs.532. Preflight each candidate like a browser, with a cross-origin referer, then54 fetch one candidate at a time with bounded connect and total timeouts55 (substitute real values for the placeholders):5657 ```sh58 curl -fsSLI -A 'Mozilla/5.0' -H 'Accept: image/png,image/jpeg,image/gif,image/webp,image/*;q=0.5' -H 'Referer: <any-https-origin-that-is-not-the-image-host>' '<image-url>'59 curl -fsSL --connect-timeout 10 --max-time 60 -A 'Mozilla/5.0' -H 'Accept: image/png,image/jpeg,image/gif,image/webp,image/*;q=0.5' -o '<dest-file>' '<image-url>'60 ```6162 Accept only a final `2xx` whose content type and file magic are an image,63 then copy those bytes into Artifact-owned storage. Prefer PNG or JPEG:64 WEBP is fine except in a Word document, and AVIF except on a web page,65 which refuses it at share time with no retry that fixes it. Convert a HEIC66 to JPEG anywhere. Reject hotlink-blocked, expiring, redirecting, 403/404,67 non-image, watermarked, or unstable URLs. The referer matters: a68 hotlink-protected host serves a plain fetch but refuses requests that look69 like they come from someone else's page, so a URL that fails this probe70 breaks after the Artifact ships even though it loads for you today. The71 same preflight applies to any external image URL an Artifact uses, however72 it was found.733. If no simple `media_url` succeeds, consider a query-bearing `media_url` or74 `thumbnail_cdn_url`. Use the returned locator byte-for-byte; never remove or75 rewrite its query string to make it look simpler.7677Search-result pre-approval records the returned locator's exact path and query,78so a plain GET/HEAD that uses it byte-for-byte is normally allowed without79another prompt even when it has a query string. Do not keep retrying or80substitute an unrelated local image when a fetch fails.8182This is text-to-image search, not reverse-image identification. Do not use it83to identify an unknown person from a supplied photograph.