Skill: sprintmint/cpbox-images-search (version 1.0.0)

--- name: images-search description: USE FOR image search. Returns images with title, source URL, thumbnail. Supports SafeSearch filter. Up to 200 results. --- # Images Search Paid Images Search proxy via **x402 pay-per-use** (HTTP 402). > **Prerequisites**: This skill requires x402-payment. Complete the [setup steps](../../README.md#prerequisites) before first use. ## Service URLs | Role | Domain | |------|--------| | **API Provider** | https://www.cpbox.io | | **Facilitator** | https://www.cppay.finance | ## Endpoint (Agent Interface) ```http GET /api/x402/images-search ``` ## Payment Flow (x402 Protocol) 1. **First request** -> `402 Payment Required` with requirements JSON 2. **Sign & retry** with `PAYMENT-SIGNATURE` -> result JSON With `@springmint/x402-payment` or `x402-sdk-go`, payment is **automatic**. ## Quick Start (cURL) ### Basic Search ```bash curl -s "https://www.cpbox.io/api/x402/images-search?q=mountain+landscape" \ -H "Accept: application/json" ``` ### With Parameters ```bash curl -s "https://www.cpbox.io/api/x402/images-search" \ -H "Accept: application/json" \ -G \ --data-urlencode "q=northern lights photography" \ --data-urlencode "country=US" \ --data-urlencode "search_lang=en" \ --data-urlencode "count=20" \ --data-urlencode "safesearch=strict" ``` ## Using with x402-payment ```bash npx @springmint/x402-payment \ --url "https://www.cpbox.io/api/x402/images-search?q=mountain+landscape&count=20" \ --method GET ``` ## Parameters | Parameter | Type | Required | Default | Description | |--|--|--|--|--| | `q` | string | **Yes** | - | Search query (1-400 chars, max 50 words) | | `country` | string | No | `US` | Search country (2-letter country code or `ALL`) | | `search_lang` | string | No | `en` | 2+ char language code | | `count` | int | No | 50 | Results to return (1-200) | | `safesearch` | string | No | `strict` | `off` or `strict` (no `moderate` for images) | | `spellcheck` | bool | No | true | Auto-correct query; corrected query in `query.altered` | ## Response Format ```json { "type": "images", "query": { "original": "mountain landscape", "altered": null, "spellcheck_off": false, "show_strict_warning": false }, "results": [ { "type": "image_result", "title": "Beautiful Mountain Landscape", "url": "https://example.com/mountain-photo", "source": "example.com", "page_fetched": "2025-09-15T10:30:00Z", "thumbnail": { "src": "https://imgs.search.provider/...", "width": 200, "height": 150 }, "properties": { "url": "https://example.com/images/mountain.jpg", "placeholder": "https://imgs.search.provider/placeholder/...", "width": 1920, "height": 1080 }, "meta_url": { "scheme": "https", "netloc": "example.com", "hostname": "example.com", "favicon": "https://imgs.search.provider/favicon/...", "path": "/mountain-photo" }, "confidence": "high" } ], "extra": { "might_be_offensive": false } } ``` ## Response Fields | Field | Type | Description | |--|--|--| | `type` | string | Always `"images"` | | `query.original` | string | Original query | | `query.altered` | string? | Spellchecked query (null if no correction) | | `query.spellcheck_off` | bool? | Whether spellcheck was disabled | | `query.show_strict_warning` | bool? | True if strict safesearch hid relevant results | | `results[]` | array | List of image results | | `results[].type` | string | Always `"image_result"` | | `results[].title` | string? | Image title | | `results[].url` | string? | Page URL where image was found | | `results[].source` | string? | Source domain | | `results[].page_fetched` | string? | ISO datetime of last page crawl | | `results[].thumbnail.src` | string? | Proxy-served thumbnail URL (~500px width) | | `results[].thumbnail.width` | int? | Thumbnail width | | `results[].thumbnail.height` | int? | Thumbnail height | | `results[].properties.url` | string? | Original full-size image URL | | `results[].properties.placeholder` | string? | Low-res placeholder URL (proxy-served) | | `results[].properties.width` | int? | Original image width (may be null) | | `results[].properties.height` | int? | Original image height (may be null) | | `results[].meta_url.scheme` | string? | URL protocol scheme | | `results[].meta_url.netloc` | string? | Network location | | `results[].meta_url.hostname` | string? | Lowercased domain | | `results[].meta_url.favicon` | string? | Favicon URL | | `results[].meta_url.path` | string? | URL path | | `results[].confidence` | string? | Relevance: `low`, `medium`, or `high` | | `extra.might_be_offensive` | bool | Whether results may contain offensive content | ## Use Cases - **Visual content discovery**: Build image galleries, mood boards, or visual research tools. Use `count=200` for comprehensive coverage. Prefer over `web-search` when you need image-specific metadata (dimensions, thumbnails). - **Content enrichment**: Add relevant images to articles or generated content. Use `country` and `search_lang` to target your audience's locale. - **Safe image retrieval**: Default `safesearch=strict` ensures family-friendly results out of the box. Only two modes (off/strict) — no moderate option, unlike web/video/news search. - **High-volume batch retrieval**: Up to 200 images per request (vs 20 for web, 50 for videos/news). Ideal for bulk image sourcing or visual analysis pipelines. ## Notes - **SafeSearch**: Defaults to `strict` for images (stricter than web search) - **High volume**: Can return up to 200 results per request - **Thumbnails**: Proxy-served for user privacy (500px width). Use `properties.url` for original full-resolution image. - **Dimensions**: `properties.width/height` may be missing for some images - **Placeholder**: `properties.placeholder` is a low-res URL (not inline base64) useful for progressive loading UX


Security scan verdicts — ClawScan: suspicious | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (MEDIUM)