shutterstock-mcp 0.1.0__tar.gz

shutterstock_mcp-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,22 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python: ['3.10', '3.12', '3.14']
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v7
+        with:
+          python-version: ${{ matrix.python }}
+      - run: uv venv && uv pip install -e . pytest anyio ruff mypy
+      - run: .venv/bin/ruff format --check . && .venv/bin/ruff check .
+      - run: .venv/bin/mypy
+      - run: .venv/bin/pytest

shutterstock_mcp-0.1.0/.gitignore

@@ -0,0 +1,6 @@
+.venv
+__pycache__
+dist
+.pytest_cache
+.mypy_cache
+.ruff_cache

shutterstock_mcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Manfred Obumma
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

shutterstock_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,103 @@
+Metadata-Version: 2.5
+Name: shutterstock-mcp
+Version: 0.1.0
+Summary: An MCP server for Shutterstock: search photos, footage, music and editorial images, look at previews, find similar images, manage collections, and license with your own subscription.
+Project-URL: Homepage, https://github.com/fredobumma/shutterstock-mcp
+Project-URL: Issues, https://github.com/fredobumma/shutterstock-mcp/issues
+Author-email: Manfred Obumma <fredobumma@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: claude,mcp,model-context-protocol,shutterstock,stock-footage,stock-photos
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Requires-Dist: mcp<3,>=2.3
+Description-Content-Type: text/markdown
+
+# shutterstock-mcp
+
+<!-- mcp-name: io.github.Fredobumma/shutterstock-mcp -->
+
+An MCP server for [Shutterstock](https://www.shutterstock.com). It lets Claude and other assistants search Shutterstock's photos, illustrations, vectors, video footage, music and editorial news photos, look at previews, find similar images, keep picks in collections, and, if you turn it on, license what you've chosen with your own subscription.
+
+## Why
+
+Finding the right stock asset is slow, manual work: search, scroll, preview, compare, search again. An assistant helping with a design, a deck, a video edit or an article can't reach Shutterstock at all. Shutterstock has no official MCP server, and what exists is a demo that returns page links.
+
+## What you can ask for
+
+- "Find warm, candid photos of a small team in an office, no faces, landscape, that would work on a dark website header." The assistant searches, looks at the previews, and shows you the ones that fit.
+- "Find a 15 to 30 second drone shot of a coastline in 4K, and an uplifting instrumental track around 100 BPM to go under it."
+- "Find editorial photos of last night's final for the match report."
+- "Here's a sketch of the layout we want. Find stock photos that look like it." This is reverse image search, from a file or a URL.
+- "Find more like this one." That works for images and video.
+- "Put these five in the *Spring campaign* collection" for the team to review.
+- "License the second one at full size." This needs licensing turned on; see below.
+
+## Setup
+
+1. Create a free app at [shutterstock.com/account/developers/apps](https://www.shutterstock.com/account/developers/apps). Its **key and secret** are enough to search.
+2. For collections, license history and licensing, the server also needs an **OAuth access token** for your account. You can generate one from the same app page, with the scopes you want: `user.view`, `collections.view`, `collections.edit`, `licenses.view` and `licenses.create`.
+
+### Claude Code
+
+```sh
+claude mcp add shutterstock -e SHUTTERSTOCK_API_KEY=… -e SHUTTERSTOCK_API_SECRET=… -- uvx shutterstock-mcp
+```
+
+### Claude Desktop, Cursor and others
+
+```json
+{
+  "mcpServers": {
+    "shutterstock": {
+      "command": "uvx",
+      "args": ["shutterstock-mcp"],
+      "env": {
+        "SHUTTERSTOCK_API_KEY": "…",
+        "SHUTTERSTOCK_API_SECRET": "…"
+      }
+    }
+  }
+}
+```
+
+With an OAuth token, set `SHUTTERSTOCK_API_TOKEN` instead of the key and secret.
+
+### Licensing
+
+Licensing spends your subscription's downloads or credits and can't be undone, so the `license_asset` tool doesn't exist unless you set `SHUTTERSTOCK_ENABLE_LICENSING=true`. When it's on, it's marked as destructive, so clients that respect tool hints ask you before each use. Editorial photos are licensed only once you've confirmed they're for news or commentary.
+
+## Tools
+
+| Tool | Needs | |
+| --- | --- | --- |
+| `search_images` | key | Photos, illustrations and vectors, by orientation, colour, people, licence and more |
+| `search_videos` | key | Footage, by resolution, length, aspect ratio and orientation |
+| `search_music` | key | Tracks, by genre, mood, instruments, tempo, length and vocals |
+| `search_editorial` | key | News, sport and entertainment photos, by date, cleared for a country |
+| `get_asset` | key | Full details of one asset |
+| `find_similar` | key | More images or videos like one from Shutterstock |
+| `reverse_image_search` | key | Shutterstock images like one of your own |
+| `view_preview` | key | The watermarked preview, as an image the assistant can look at |
+| `list_subscriptions` | token | Your subscriptions and what's left on them |
+| `list_licenses` | token | What you've licensed before |
+| `list_collections`, `get_collection` | token | Your collections and what's in them |
+| `create_collection`, `add_to_collection` | token | Make and fill collections |
+| `license_asset` | token, opt-in | License an image, clip, track or editorial photo |
+
+Free Shutterstock apps search a smaller part of the library, see only the first results of a search, and are limited to about 100 requests an hour.
+
+## Status
+
+Built from Shutterstock's API reference and its official SDK's models, and tested against a fake of the API that checks what the server sends, through a real MCP client. It hasn't yet been run against the live API; if something doesn't match, please [open an issue](https://github.com/fredobumma/shutterstock-mcp/issues).
+
+## Development
+
+```sh
+uv venv && uv pip install -e . pytest anyio ruff mypy
+pytest && ruff check . && mypy
+```
+
+## License
+
+MIT. Not affiliated with Shutterstock. Shutterstock is a trademark of Shutterstock, Inc.

shutterstock_mcp-0.1.0/README.md

@@ -0,0 +1,88 @@
+# shutterstock-mcp
+
+<!-- mcp-name: io.github.Fredobumma/shutterstock-mcp -->
+
+An MCP server for [Shutterstock](https://www.shutterstock.com). It lets Claude and other assistants search Shutterstock's photos, illustrations, vectors, video footage, music and editorial news photos, look at previews, find similar images, keep picks in collections, and, if you turn it on, license what you've chosen with your own subscription.
+
+## Why
+
+Finding the right stock asset is slow, manual work: search, scroll, preview, compare, search again. An assistant helping with a design, a deck, a video edit or an article can't reach Shutterstock at all. Shutterstock has no official MCP server, and what exists is a demo that returns page links.
+
+## What you can ask for
+
+- "Find warm, candid photos of a small team in an office, no faces, landscape, that would work on a dark website header." The assistant searches, looks at the previews, and shows you the ones that fit.
+- "Find a 15 to 30 second drone shot of a coastline in 4K, and an uplifting instrumental track around 100 BPM to go under it."
+- "Find editorial photos of last night's final for the match report."
+- "Here's a sketch of the layout we want. Find stock photos that look like it." This is reverse image search, from a file or a URL.
+- "Find more like this one." That works for images and video.
+- "Put these five in the *Spring campaign* collection" for the team to review.
+- "License the second one at full size." This needs licensing turned on; see below.
+
+## Setup
+
+1. Create a free app at [shutterstock.com/account/developers/apps](https://www.shutterstock.com/account/developers/apps). Its **key and secret** are enough to search.
+2. For collections, license history and licensing, the server also needs an **OAuth access token** for your account. You can generate one from the same app page, with the scopes you want: `user.view`, `collections.view`, `collections.edit`, `licenses.view` and `licenses.create`.
+
+### Claude Code
+
+```sh
+claude mcp add shutterstock -e SHUTTERSTOCK_API_KEY=… -e SHUTTERSTOCK_API_SECRET=… -- uvx shutterstock-mcp
+```
+
+### Claude Desktop, Cursor and others
+
+```json
+{
+  "mcpServers": {
+    "shutterstock": {
+      "command": "uvx",
+      "args": ["shutterstock-mcp"],
+      "env": {
+        "SHUTTERSTOCK_API_KEY": "…",
+        "SHUTTERSTOCK_API_SECRET": "…"
+      }
+    }
+  }
+}
+```
+
+With an OAuth token, set `SHUTTERSTOCK_API_TOKEN` instead of the key and secret.
+
+### Licensing
+
+Licensing spends your subscription's downloads or credits and can't be undone, so the `license_asset` tool doesn't exist unless you set `SHUTTERSTOCK_ENABLE_LICENSING=true`. When it's on, it's marked as destructive, so clients that respect tool hints ask you before each use. Editorial photos are licensed only once you've confirmed they're for news or commentary.
+
+## Tools
+
+| Tool | Needs | |
+| --- | --- | --- |
+| `search_images` | key | Photos, illustrations and vectors, by orientation, colour, people, licence and more |
+| `search_videos` | key | Footage, by resolution, length, aspect ratio and orientation |
+| `search_music` | key | Tracks, by genre, mood, instruments, tempo, length and vocals |
+| `search_editorial` | key | News, sport and entertainment photos, by date, cleared for a country |
+| `get_asset` | key | Full details of one asset |
+| `find_similar` | key | More images or videos like one from Shutterstock |
+| `reverse_image_search` | key | Shutterstock images like one of your own |
+| `view_preview` | key | The watermarked preview, as an image the assistant can look at |
+| `list_subscriptions` | token | Your subscriptions and what's left on them |
+| `list_licenses` | token | What you've licensed before |
+| `list_collections`, `get_collection` | token | Your collections and what's in them |
+| `create_collection`, `add_to_collection` | token | Make and fill collections |
+| `license_asset` | token, opt-in | License an image, clip, track or editorial photo |
+
+Free Shutterstock apps search a smaller part of the library, see only the first results of a search, and are limited to about 100 requests an hour.
+
+## Status
+
+Built from Shutterstock's API reference and its official SDK's models, and tested against a fake of the API that checks what the server sends, through a real MCP client. It hasn't yet been run against the live API; if something doesn't match, please [open an issue](https://github.com/fredobumma/shutterstock-mcp/issues).
+
+## Development
+
+```sh
+uv venv && uv pip install -e . pytest anyio ruff mypy
+pytest && ruff check . && mypy
+```
+
+## License
+
+MIT. Not affiliated with Shutterstock. Shutterstock is a trademark of Shutterstock, Inc.

shutterstock_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,45 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "shutterstock-mcp"
+version = "0.1.0"
+description = "An MCP server for Shutterstock: search photos, footage, music and editorial images, look at previews, find similar images, manage collections, and license with your own subscription."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Manfred Obumma", email = "fredobumma@gmail.com" }]
+requires-python = ">=3.10"
+keywords = ["mcp", "model-context-protocol", "shutterstock", "stock-photos", "stock-footage", "claude"]
+dependencies = ["mcp>=2.3,<3", "httpx>=0.27"]
+
+[project.urls]
+Homepage = "https://github.com/fredobumma/shutterstock-mcp"
+Issues = "https://github.com/fredobumma/shutterstock-mcp/issues"
+
+[project.scripts]
+shutterstock-mcp = "shutterstock_mcp.server:main"
+
+[dependency-groups]
+dev = ["pytest>=9", "anyio>=4", "ruff>=0.17", "mypy>=2"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/shutterstock_mcp"]
+
+[tool.ruff]
+line-length = 120
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "B", "UP", "SIM", "RUF"]
+
+[tool.ruff.format]
+quote-style = "single"
+
+[tool.mypy]
+strict = true
+files = ["src", "tests"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

shutterstock_mcp-0.1.0/server.json

@@ -0,0 +1,42 @@
+{
+	"$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
+	"name": "io.github.Fredobumma/shutterstock-mcp",
+	"title": "Shutterstock",
+	"description": "Search Shutterstock photos, footage, music and news images; preview, collect and license them.",
+	"repository": {
+		"url": "https://github.com/fredobumma/shutterstock-mcp",
+		"source": "github"
+	},
+	"version": "0.1.0",
+	"packages": [
+		{
+			"registryType": "pypi",
+			"identifier": "shutterstock-mcp",
+			"version": "0.1.0",
+			"transport": {
+				"type": "stdio"
+			},
+			"environmentVariables": [
+				{
+					"name": "SHUTTERSTOCK_API_KEY",
+					"description": "Your Shutterstock app's consumer key, for searching",
+					"isSecret": true
+				},
+				{
+					"name": "SHUTTERSTOCK_API_SECRET",
+					"description": "Your Shutterstock app's consumer secret",
+					"isSecret": true
+				},
+				{
+					"name": "SHUTTERSTOCK_API_TOKEN",
+					"description": "Or an OAuth access token, for collections, license history and licensing",
+					"isSecret": true
+				},
+				{
+					"name": "SHUTTERSTOCK_ENABLE_LICENSING",
+					"description": "Set to true to add the license_asset tool, which spends your subscription"
+				}
+			]
+		}
+	]
+}

shutterstock_mcp-0.1.0/src/shutterstock_mcp/__init__.py

@@ -0,0 +1,3 @@
+"""An MCP server for Shutterstock."""
+
+__version__ = '0.1.0'

shutterstock_mcp-0.1.0/src/shutterstock_mcp/__main__.py

@@ -0,0 +1,3 @@
+from .server import main
+
+main()

shutterstock_mcp-0.1.0/src/shutterstock_mcp/api.py

@@ -0,0 +1,265 @@
+"""A small client for the Shutterstock API, and the compact summaries the tools return."""
+
+from __future__ import annotations
+
+import base64
+import os
+from dataclasses import dataclass
+from typing import Any, Literal
+
+import httpx
+from mcp.server.mcpserver.exceptions import ToolError
+
+API_URL = 'https://api.shutterstock.com/v2'
+USER_AGENT = 'shutterstock-mcp (+https://github.com/fredobumma/shutterstock-mcp)'
+
+AssetType = Literal['image', 'video', 'music', 'editorial']
+PATHS: dict[str, str] = {'image': 'images', 'video': 'videos', 'music': 'audio', 'editorial': 'editorial/images'}
+
+
+class ShutterstockError(ToolError):
+    """An error to show the user as it is: what went wrong, and what to do about it. As a ToolError, its message
+    reaches the model; anything else that goes wrong stays a generic error, with the details in the server's log."""
+
+
+@dataclass(frozen=True)
+class Credentials:
+    token: str | None = None
+    key: str | None = None
+    secret: str | None = None
+
+    @classmethod
+    def from_env(cls, env: dict[str, str] | None = None) -> Credentials:
+        env = dict(os.environ if env is None else env)
+        credentials = cls(
+            token=env.get('SHUTTERSTOCK_API_TOKEN') or None,
+            key=env.get('SHUTTERSTOCK_API_KEY') or None,
+            secret=env.get('SHUTTERSTOCK_API_SECRET') or None,
+        )
+        if not credentials.token and not (credentials.key and credentials.secret):
+            raise ShutterstockError(
+                'set SHUTTERSTOCK_API_TOKEN, or SHUTTERSTOCK_API_KEY and SHUTTERSTOCK_API_SECRET: '
+                'create an app at https://www.shutterstock.com/account/developers/apps'
+            )
+        return credentials
+
+    @property
+    def has_token(self) -> bool:
+        return self.token is not None
+
+
+class Shutterstock:
+    def __init__(
+        self,
+        credentials: Credentials,
+        *,
+        base_url: str = API_URL,
+        transport: httpx.AsyncBaseTransport | None = None,
+    ) -> None:
+        self.credentials = credentials
+        headers = {'User-Agent': USER_AGENT, 'Accept': 'application/json'}
+        auth: httpx.Auth | None = None
+        if credentials.token:
+            headers['Authorization'] = f'Bearer {credentials.token}'
+        else:
+            auth = httpx.BasicAuth(credentials.key or '', credentials.secret or '')
+        self._http = httpx.AsyncClient(
+            base_url=base_url.rstrip('/'), headers=headers, auth=auth, transport=transport, timeout=30
+        )
+        # previews come from Shutterstock's CDN, which needs no credentials and is not sent them
+        self._cdn = httpx.AsyncClient(headers={'User-Agent': USER_AGENT}, transport=transport, timeout=30)
+
+    async def aclose(self) -> None:
+        await self._http.aclose()
+        await self._cdn.aclose()
+
+    def require_token(self, what: str, scope: str) -> None:
+        """Account features need a user's OAuth token, not just an app's key and secret."""
+        if not self.credentials.has_token:
+            raise ShutterstockError(
+                f'{what} needs an OAuth access token with the {scope} scope, in SHUTTERSTOCK_API_TOKEN; '
+                'an app key and secret only search. Get a token from your app at '
+                'https://www.shutterstock.com/account/developers/apps'
+            )
+
+    async def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: dict[str, Any] | None = None,
+        json: Any = None,
+    ) -> Any:
+        query = {k: v for k, v in (params or {}).items() if v is not None}
+        # booleans as the API spells them, and lists as repeated parameters
+        query = {k: (str(v).lower() if isinstance(v, bool) else v) for k, v in query.items()}
+        try:
+            response = await self._http.request(method, path, params=query, json=json)
+        except httpx.HTTPError as e:
+            raise ShutterstockError(f'could not reach Shutterstock: {e}') from e
+        if response.status_code == 429:
+            raise ShutterstockError(
+                'Shutterstock says too many requests; free accounts allow about 100 an hour. Try again later.'
+            )
+        if response.status_code in (401, 403):
+            raise ShutterstockError(f'Shutterstock refused the request ({response.status_code}): {_message(response)}')
+        if response.status_code == 404:
+            raise ShutterstockError(f'not found: {_message(response)}')
+        if response.status_code >= 400:
+            raise ShutterstockError(f'Shutterstock returned {response.status_code}: {_message(response)}')
+        return response.json() if response.content else {}
+
+    async def fetch_bytes(self, url: str) -> tuple[bytes, str]:
+        """A preview image, from Shutterstock's own CDN."""
+        if not url.startswith('https://'):
+            raise ShutterstockError(f'not a preview URL: {url}')
+        try:
+            response = await self._cdn.get(url, headers={'Accept': 'image/*'})
+            response.raise_for_status()
+        except httpx.HTTPError as e:
+            raise ShutterstockError(f'could not fetch the preview: {e}') from e
+        return response.content, response.headers.get('content-type', 'image/jpeg').split(';')[0]
+
+
+def _message(response: httpx.Response) -> str:
+    try:
+        data = response.json()
+    except ValueError:
+        return response.text[:300] or response.reason_phrase
+    if isinstance(data, dict):
+        parts = [str(data.get('message', ''))]
+        for error in data.get('errors', []) or []:
+            if isinstance(error, dict):
+                parts.append(str(error.get('message', '')))
+        return '; '.join(p for p in parts if p) or response.reason_phrase
+    return response.reason_phrase
+
+
+def encode_file(path: str) -> str:
+    try:
+        with open(os.path.expanduser(path), 'rb') as f:
+            data = f.read()
+    except OSError as e:
+        raise ShutterstockError(f'could not read {path}: {e.strerror}') from e
+    if len(data) > 10 * 1024 * 1024:
+        raise ShutterstockError('the image is larger than the 10 MB Shutterstock accepts')
+    return base64.b64encode(data).decode()
+
+
+# ---- summaries -------------------------------------------------------------------------------------------------
+# The API's responses are large and deeply nested. The tools hand back what a person choosing an asset needs: what it
+# is, a preview to look at, and the ids and links to act on it.
+
+
+def _asset_url(assets: dict[str, Any], *names: str) -> str | None:
+    for name in names:
+        asset = assets.get(name)
+        if isinstance(asset, dict) and asset.get('url'):
+            return str(asset['url'])
+    return None
+
+
+def _clean(data: dict[str, Any]) -> dict[str, Any]:
+    return {k: v for k, v in data.items() if v not in (None, [], '')}
+
+
+def summarize_image(item: dict[str, Any]) -> dict[str, Any]:
+    assets = item.get('assets') or {}
+    return _clean(
+        {
+            'id': item.get('id'),
+            'description': item.get('description'),
+            'type': item.get('image_type'),
+            'aspect': item.get('aspect'),
+            'preview': _asset_url(assets, 'preview_1000', 'preview', 'large_thumb'),
+            'thumbnail': _asset_url(assets, 'large_thumb', 'small_thumb'),
+            'contributor': (item.get('contributor') or {}).get('id'),
+            'editorial': item.get('is_editorial'),
+            'model_released': item.get('has_model_release'),
+            'keywords': (item.get('keywords') or [])[:15],
+            'page': item.get('url'),
+        }
+    )
+
+
+def summarize_video(item: dict[str, Any]) -> dict[str, Any]:
+    assets = item.get('assets') or {}
+    return _clean(
+        {
+            'id': item.get('id'),
+            'description': item.get('description'),
+            'duration_seconds': item.get('duration'),
+            'aspect_ratio': item.get('aspect_ratio'),
+            'preview_video': _asset_url(assets, 'preview_mp4', 'thumb_mp4'),
+            'preview_image': _asset_url(assets, 'preview_jpg', 'thumb_jpg'),
+            'sizes': [s for s in ('web', 'sd', 'hd', '_4k') if s in assets] or None,
+            'contributor': (item.get('contributor') or {}).get('id'),
+            'editorial': item.get('is_editorial'),
+            'keywords': (item.get('keywords') or [])[:15],
+            'page': item.get('url'),
+        }
+    )
+
+
+def summarize_track(item: dict[str, Any]) -> dict[str, Any]:
+    assets = item.get('assets') or {}
+    return _clean(
+        {
+            'id': item.get('id'),
+            'title': item.get('title'),
+            'artists': [a.get('name') for a in item.get('artists') or [] if isinstance(a, dict)],
+            'description': item.get('description'),
+            'duration_seconds': item.get('duration'),
+            'bpm': item.get('bpm'),
+            'genres': item.get('genres'),
+            'moods': item.get('moods'),
+            'instruments': item.get('instruments'),
+            'instrumental': item.get('is_instrumental'),
+            'preview_audio': _asset_url(assets, 'preview_mp3', 'preview_ogg'),
+            'waveform': _asset_url(assets, 'waveform'),
+            'page': item.get('url'),
+        }
+    )
+
+
+def summarize_editorial(item: dict[str, Any]) -> dict[str, Any]:
+    assets = item.get('assets') or {}
+    return _clean(
+        {
+            'id': item.get('id'),
+            'title': item.get('title'),
+            'caption': item.get('caption') or item.get('description'),
+            'date_taken': item.get('date_taken'),
+            'byline': item.get('byline'),
+            'supplier': item.get('supplier_code'),
+            'preview': _asset_url(assets, 'watermark_1500', 'watermark_450', 'preview', 'thumb_220', 'thumb_170'),
+            'thumbnail': _asset_url(assets, 'thumb_220', 'thumb_170'),
+            'aspect': item.get('aspect'),
+            'keywords': (item.get('keywords') or [])[:15],
+        }
+    )
+
+
+SUMMARIES = {
+    'image': summarize_image,
+    'video': summarize_video,
+    'music': summarize_track,
+    'editorial': summarize_editorial,
+}
+
+
+def summarize_page(data: dict[str, Any], asset_type: str) -> dict[str, Any]:
+    summarize = SUMMARIES[asset_type]
+    return _clean(
+        {
+            'total': data.get('total_count'),
+            'page': data.get('page'),
+            'per_page': data.get('per_page'),
+            'search_id': data.get('search_id'),
+            'next_cursor': data.get('next'),
+            'did_you_mean': (data.get('spellcheck_info') or {}).get('spellchecked_query')
+            if isinstance(data.get('spellcheck_info'), dict)
+            else None,
+            'results': [summarize(item) for item in data.get('data') or []],
+        }
+    )