Einprägsame Namen für Hex-Digests.

Ausprobieren

Mach einen GET auf einen beliebigen Hex-Digest unter /api/v1/hash/<hex>. Der Endpoint ist offen, deterministisch und CORS-fähig:

Antwort:

{
  "inputHash": "f3527e4ef32f9d8b59ead6b7b70a843c3da1c105",
  "hash": "canyon-jam-telescope-creek"
}

Funktionsweise

HumanHash bildet jeden hexadezimalen String in drei Schritten auf einen kurzen, aussprechbaren Namen ab:

1. Parsen der Hex-Eingabe als Byte-Array.
2. Komprimieren dieser Bytes in N gleich große Segmente (N = 4 standardmäßig) und XOR-Reduktion jedes Segments auf ein einzelnes Byte.
3. Mapping jedes resultierenden Bytes (0–255) auf einen Eintrag einer kuratierten 256-Wörter-Liste, dann mit Bindestrichen verbinden.

Die Ausgabe ist vollständig deterministisch — dieselbe Eingabe ergibt immer denselben Namen — und der Algorithmus ist zustandslos, ohne Datenbank oder Zufall. Vier Wörter aus einer 256-Wörter-Liste ergeben 256⁴ ≈ 4,3 Milliarden Kombinationen, also ungefähr einen 32-Bit-Fingerabdruck: angenehm zum menschlichen Wiedererkennen einzelner Deploys oder Builds, aber kein Ersatz für den darunterliegenden Hash, wenn Kollisionsresistenz wichtig ist.

API-Referenz

Code-Beispiele

curl

curl https://humanhash.dev/api/v1/hash/f3527e4ef32f9d8b59ead6b7b70a843c3da1c105

JavaScript (fetch)

const hex = "f3527e4ef32f9d8b59ead6b7b70a843c3da1c105";
const res = await fetch(`https://humanhash.dev/api/v1/hash/${hex}`);
const { hash } = await res.json();
console.log(hash); // "canyon-jam-telescope-creek"

Python

import requests

hex_digest = "f3527e4ef32f9d8b59ead6b7b70a843c3da1c105"
r = requests.get(f"https://humanhash.dev/api/v1/hash/{hex_digest}")
print(r.json()["hash"])  # "canyon-jam-telescope-creek"

Go

resp, _ := http.Get("https://humanhash.dev/api/v1/hash/f3527e4ef32f9d8b59ead6b7b70a843c3da1c105")
defer resp.Body.Close()
var out struct{ InputHash, Hash string }
json.NewDecoder(resp.Body).Decode(&out)
fmt.Println(out.Hash) // "canyon-jam-telescope-creek"

UUID

UUIDs gehen auch — entferne zuerst die Bindestriche:

curl https://humanhash.dev/api/v1/hash/550e8400e29b41d4a716446655440000
# => {"inputHash":"550e8400e29b41d4a716446655440000","hash":"vault-lift-onion-lilac"}

Beispiel: GitHub Actions

Ein gängiges Pattern ist, einen einprägsamen Namen aus github.sha abzuleiten und neben dem SHA zu verwenden — etwa um ein Docker-Image mit beiden zu taggen. Genau so verwenden wir HumanHash in unseren eigenen Produktions-Pipelines:

name: build

on:
  push:
    branches: ["main"]

env:
  IMAGE_NAME: "ghcr.io/your-org/your-app"

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Get human hash
        run: echo "HUMAN_HASH=$(curl -s "https://humanhash.dev/api/v1/hash/${{ github.sha }}" | jq -r '.hash')" >> "$GITHUB_ENV"

      - name: Build Docker image
        run: docker build . --tag ${{ env.IMAGE_NAME }}:${{ github.sha }} --tag ${{ env.IMAGE_NAME }}:${{ env.HUMAN_HASH }}

      - name: Log in to registry
        run: echo "${{ secrets.GITHUB_TOKEN }}" | docker login ghcr.io -u ${{ github.actor }} --password-stdin

      - name: Push image
        run: docker push --all-tags ${{ env.IMAGE_NAME }}

Jeder Push bekommt zwei Tags: den exakten SHA für Reproduzierbarkeit und einen menschenfreundlichen Namen wie swift-river-mellow-bolt der tatsächlich in Chat, Dashboards und Standups brauchbar ist. Das Binary jq ist auf dem von GitHub gehosteten ubuntu-latest-Runner vorinstalliert, keine zusätzliche Einrichtung nötig.

Anwendungsfälle

• Build- und Deploy-Namen. Taggt einen CI-Build als swift-river-mellow-bolt statt 7c4f9a2. Leichter im Standup zu erwähnen, leichter im Chat-Verlauf zu finden.
• Commit-Referenzen im Chat. Ein SHA in Slack wird ignoriert; canyon-jam-telescope-creek wird gelesen.
• Session- und Request-IDs in Logs. Beim Grep über Services hinweg oder beim lauten Aussprechen einer ID im Call schlagen Wörter Hex.
• Backup- und Snapshot-Namen. vault-bronze-falcon-river wiederherstellen ist weniger beängstigend als b8f9c1d2…
• Fingerabdruck-Vergleich. SSH- oder TLS-Fingerabdrücke visuell als vier Wörter zu vergleichen ist viel schneller als 40 Hex-Zeichen.
• Asset- / Versions-Labels. Gib Build-Artefakten, Modell-Checkpoints oder Dataset-Snapshots einen Namen, über den Menschen reden können.

Vergleich mit anderen Identifier-Formaten

HumanHash ist einzigartig als deterministische Projektion eines bestehenden Identifiers — es ersetzt deinen UUID oder Hash nicht, sondern schattet ihn mit einem lesbaren Namen. Verwende beide zusammen.

Häufig gestellte Fragen

Das 256-Wörter-Vokabular

Die Ausgaben kommen aus einer kuratierten Liste von 256 kurzen, aussprechbaren englischen Wörtern, gruppiert in acht thematische Kategorien zu je 32. Die Liste vermeidet mehrdeutige Schreibweisen, Beinahe-Homophone und Wörter, die aneinandergereiht schlecht zu lesen sind.

Über

HumanHash wird betrieben von Pilvia Oy, einem finnischen Cloud-Unternehmen. Wir nutzen es intern zum Labeln von Builds, Deploys und Snapshots und haben es geöffnet, weil der Algorithmus allgemein nützlich ist.

Das humanhash-Konzept entstand als kleine Python-Bibliothek von Zachary Voase. Diese Implementierung ist eine unabhängige TypeScript-Neufassung auf Cloudflare Workers mit einer eigenen Wortliste.