为十六进制摘要起一个易记的名字。

试一下

对任意 hex 摘要发起 GET 请求 /api/v1/hash/<hex>。端点开放、确定性、支持 CORS：

响应：

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

工作原理

HumanHash 通过三步将任意十六进制字符串映射为一个简短、可朗读的名称：

1. 解析 将 hex 输入解析为字节数组。
2. 压缩 将这些字节分成 N 个等长段（默认 N = 4），对每段做 XOR 压缩为单个字节。
3. 映射 将每个结果字节（0–255）映射到精选 256 词列表中的一个，然后用连字符连接。

输出完全确定——相同输入始终产生相同名称——算法无状态，不涉及数据库或随机性。从 256 词列表中取 4 个词，可得 256⁴ ≈ 43 亿种组合，约为 32 位指纹：足以让人识别单次部署或构建，但若需抗碰撞性，不能替代底层哈希。

API 参考

代码示例

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

UUID 也可以——先去掉连字符：

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

示例：GitHub Actions

一种常见做法是根据 github.sha 派生一个易记名称，与 SHA 并用——例如用两者同时打 Docker 镜像标签。我们在自己的生产流水线中就是这样使用 HumanHash 的：

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 }}

每次 push 都会得到两个标签：用于可复现的精确 SHA，以及一个像 swift-river-mellow-bolt 这样在聊天、看板和站会中真正可用的友好名称。 jq 命令已预装在 GitHub 托管的 ubuntu-latest runner 上，无需额外配置。

使用场景

• 构建和部署名称。 把 CI 构建标记为 swift-river-mellow-bolt 而不是 7c4f9a2，更易在站会中提及，也更易在聊天记录中查找。
• 聊天中的 commit 引用。 在 Slack 中粘贴 SHA 会被忽略；粘贴 canyon-jam-telescope-creek 才会被读到。
• 日志中的会话和请求 ID。 跨服务 grep 或在电话会议中口述 ID 时，单词远胜 hex。
• 备份和快照名称。 恢复 vault-bronze-falcon-river 比恢复 b8f9c1d2… 让人安心得多。
• 指纹比对。 用四个单词比对 SSH 或 TLS 指纹，比 40 个 hex 字符快得多。
• 资产/版本标签。 给构建产物、模型检查点或数据快照起一个可以被人讨论的名字。

与其他标识符格式对比

HumanHash 的独特之处在于它是已有标识符的确定性投影——它不替代你的 UUID 或哈希，而是用人能读的名字与之并列。两者搭配使用。

常见问题

256 词词表

输出取自一份精选的 256 个简短、可朗读英文单词列表，按主题分为八组，每组 32 个。该列表避开拼写歧义、近同音词以及串联后不易朗读的词。

关于

HumanHash 由 Pilvia Oy运营，一家芬兰云公司。我们在内部用它来标注构建、部署和快照，并因算法的通用价值将其开放。

humanhash 概念最初是 Zachary Voase 的一个小型 Python 库。本实现是运行在 Cloudflare Workers 上的独立 TypeScript 重写，并配以我们自己的词表。