Image Search

Image Search

Use the bundled CLI to find public images by text query:

shCopy code
/opt/hatch/bin/image-search "Golden Gate Bridge at sunset" --max-results 5

Optional result language:

shCopy code
/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:

1. 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.

2. 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):

   shCopy code
   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.

3. 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.