iscc-web is a microservice for generating International Standard Content Codes
(ISCC) for media files. A public instance of this service is available at
https://web.iscc.io
Full documentation is published at https://web.iscc.codes and release history is tracked in the changelog.
Run the service with Docker (images are published to ghcr.io
with main and semver tags):
docker run -p 8000:8000 ghcr.io/iscc/iscc-web:mainEach tag also has an opt-in -gpu variant (e.g. :main-gpu) on a CUDA base that runs the
experimental semantic codes on an NVIDIA GPU. Most deployments want the smaller default image;
see the deployment guide for GPU requirements.
REST API
The microservice provides a REST API for generating ISCCs. The endpoints support file
upload/download, metadata extraction/embedding and ISCC processing.
Files uploaded for processing are automatically deleted after a configurable timeout.
Interactive API documentation is available at /docs. GET /health
(at the site root) is a readiness probe for monitors and the Docker HEALTHCHECK: it reports
whether the semantic-code ONNX models are loaded, which execution provider (GPU or CPU) they run
on, and the image version and revision.
Experimental features (not part of ISO 24138, algorithms may change before their v1.0 release):
POST /api/v1/iscc?semantic=truegenerates an experimental Semantic-Code ISCC-UNIT for text (iscc-sct) and image (iscc-sci) content that becomes part of the composite ISCC-CODE - 5 units (Meta, Semantic, Content, Data, Instance) instead of 4. The resulting ISCC-CODE is not a standard ISO 24138 identifier. Off by default.POST /api/v1/isccincludes granular simprint features in thefeaturesfield by default (text content; withsemantic=truealso semantic simprints). Simprints are 256-bit fingerprints with UTF-8 byte based offsets and sizes. Opt out per request with?granular=false.POST /api/v1/simprintgenerates granular simprints from plain text - byte-identical to iscc-search's local simprint generation, so search services can delegate text processing to this service.
Demo Frontend
The service also hosts a Vue.js based demo frontend that generates ISCCs
for media files and pasted text, decodes existing ISCC-CODEs unit by unit, embeds metadata, and
compares two ISCCs bit by bit.
The service is configured through ISCC_WEB_* environment variables and overridable ISCC
processing defaults (ISCC_SDK_*, ISCC_SCT_*, ISCC_SCI_*). See the
configuration guide for the complete reference.
A Docker Compose deployment behind a reverse proxy that terminates TLS is documented in the deployment guide.
Both the backend and frontend servers need to run in parallel.
Having uv installed do:
git clone https://github.com/iscc/iscc-web.git
cd iscc-web
uv sync
uv run iscc-webOpen the demo frontend at http://localhost:8000 and the API documentation at http://localhost:8000/docs.
Before committing any changes run code formatting and tests with:
uv run poe allInstall the Node.js version listed in .tool-versions, for example with asdf. Packages are managed by pnpm.
Run pnpm install to install the frontend dependencies.
Run pnpm run dev to run the development server.
Run pnpm run test to run the frontend test suite (vitest).
The documentation site at https://web.iscc.codes is built with
Zensical and the ISCC theme
(zensical-iscc) from the docs/ directory. Serve it
locally with uv run poe docs-serve, build it with uv run poe docs-build and check it with
uv run poe docs-check. See the
contribution guide for details.

