Kaomojis 公共 API

快速入門（30 秒）

无需鉴权或 API key。直接把以下命令粘贴到终端。

# random kaomoji
curl "https://kaomojis.jp/api/v1/kaomojis/random?locale=en"

# search
curl "https://kaomojis.jp/api/v1/kaomojis/search?q=love&locale=en"

# paginated list of cute kaomojis
curl "https://kaomojis.jp/api/v1/kaomojis?category=cute&page=1&limit=20&locale=en"

# full category catalog
curl "https://kaomojis.jp/api/v1/categories?type=emotion&locale=en"

JavaScript / TypeScript SDK

@kaomojis/client 支持 Node.js 18+ 与现代浏览器，零依赖、完整 TS 类型。

// Available now — Node.js 18+ and modern browsers, no package required
const response = await fetch(
  'https://kaomojis.jp/api/v1/kaomojis/random?count=3&locale=en'
);
const { data } = await response.json();
console.log(data[0].text); // e.g. "(*´ω`*)"

// Typed SDK (pre-release; not yet available on npm)
// npm install @kaomojis/client

Source: sdk/javascript/ · SDK code license: MIT (the kaomoji data is covered separately — see the FAQ)

示範應用

三个可立即运行的最小示例，复制后即可使用。

端點列表

所有端点均为 GET + JSON + CORS(*)。

更新紀錄

• 2026-09-05 — 明確標示了入口的限制（單一 IP 每秒 10 次請求，另有約 20 次的短時突發額度）。該限制先前即已存在，只是沒有寫明。如有疑問請聯絡 [email protected]
• 2026-08-25 — 明確了使用條件。本站不對顏文字字串本身主張獨占權利（於本站擁有權利的範圍內以 CC0 1.0 提供）。說明文字、範例句與關鍵字須標示出處，且不得大量再散布。本條件適用於 2026-08-25 起取得的內容，不溯及此前依舊條款已取得的內容。洽詢：[email protected]
• 2026-08-25 — 不相容變更：列表端點 (/api/v1/kaomojis) 與隨機端點 (/api/v1/random、/api/v1/kaomojis/random) 回傳的項目已移除 note 與 usage 欄位。需要說明文字與範例句時，請使用單筆取得 (/api/v1/kaomojis/{id}) 或搜尋 (/api/v1/search、/api/v1/kaomojis/search)。此變更用於防止編輯內容被大量擷取。
• 2026-08-25 — 文件中標示的公平使用限制（每 IP 每分鐘 60 次）已實際生效，超過時回傳 429 與 Retry-After。

速率限制與快取

每個 IP 每分鐘 60 次請求，且每分鐘最多回傳 1,000 筆。超過任一限制會回傳 429 與 Retry-After。搜尋每次最多 25 筆。 此外在入口處，單一 IP 的持續上限為每秒 10 次請求，另可直接通過約 20 次的短時突發。超出部分會在抵達應用前回傳 429。請依上面每分鐘 60 次這一更嚴格的上限控制節奏，依序呼叫，不要並發。歡迎商用，請尊重 Cache-Control。偵測到濫用會依 IP 封鎖。 註：請求次數限制與筆數預算均以應用程式行程為單位計數。由於服務以多行程運作，回傳 429 的確切時點可能有所浮動。請以標示值為上限設計用戶端，收到 429 時請遵循 Retry-After。超出標示值的用量並非可用量的保證。

OpenAPI 3.0 規範

完整規範位於 /api/v1/openapi.json，可直接匯入 Swagger UI / Redoc / Stoplight / Postman。

常見問題