一言API - API文档

API 简介

API Overview

一言接口随机返回一条句子，来源涵盖动画、漫画、游戏、文学、诗词等多个分类。支持按分类筛选、长度过滤，并可选择 JSON 或纯文本格式返回。无需认证，直接调用即可。

The Hitokoto API returns a random sentence from various categories including anime, manga, games, literature, and poetry. Supports category filtering, length filtering, and JSON or plain-text response formats. No authentication required.

基础地址

Base URL

https://api.furry.ist/hitokoto

支持的 HTTP 方法

Supported HTTP Methods

支持 GET、HEAD、OPTIONS。其他方法将返回：

Supports GET, HEAD, OPTIONS. Other methods return:

{"error":"Method Not Allowed","code":405}

查询参数

Query Parameters

参数名Parameter	类型Type	说明Description	示例Example
c	字符串（可多值）String (multi-value)	分类 key，可传多个（见下方分类表）。不传或全部无效时从全部分类随机。Category key, can be passed multiple times (see category table below). Omitted or all-invalid values result in a random pick from all categories.	c=a&c=b
encode	字符串String	`json`（默认）返回完整 JSON 对象；`text` 仅返回纯文本句子内容。`json` (default) returns the full JSON object; `text` returns only the plain-text sentence.	encode=text
min_length	整数Integer	句子最短字符数（含）。与 `max_length` 至少一个有效时启用过滤，最多随机尝试 10 次，10 次未满足则随机兜底。Minimum sentence length (inclusive). Filtering is enabled when at least one of `min_length` / `max_length` is a valid positive integer. Falls back to a random result after 10 attempts.	min_length=8
max_length	整数Integer	句子最长字符数（含）。过滤行为同 `min_length`。Maximum sentence length (inclusive). Same filtering behavior as `min_length`.	max_length=20

分类说明

keykey	分类名Category
a	动画Anime
b	漫画Manga / Comics
c	游戏Games
d	文学Literature
e	原创Original
f	来自网络From the Internet
g	其他Other
h	影视Film & TV
i	诗词Poetry
j	网易云NetEase Cloud Music
k	哲学Philosophy
l	抖机灵Witty Sayings

响应字段（JSON 模式）

Response Fields (JSON Mode)

字段名Field	类型Type	说明Description
id	Number	句子 IDSentence ID
uuid	String	句子唯一标识符（UUID）Unique identifier (UUID)
hitokoto	String	句子正文Sentence content
type	String	分类名称（中文）Category name (Chinese), e.g. "原创"
type_desc	String	分类说明"Category description"
from	String	来源作品Source work
from_who	String \| null	出处作者或角色，可为 nullAuthor or character, may be null
creator	String	句子录入者Submitter
creator_uid	Number	录入者 UIDSubmitter UID
reviewer	Number	审核者 IDReviewer ID
commit_from	String	提交来源，如 "web"Submission source, e.g. "web"
created_at	String	录入时间（Unix 时间戳字符串）Submission time (Unix timestamp string)
length	Number	句子字符数Character count of the sentence

错误响应

Error Responses

场景Scenario	返回内容Response
非允许的 HTTP 方法Disallowed HTTP method	`{"error":"Method Not Allowed","code":405}`
数据源拉取或解析失败Data source fetch or parse failure	`{"error":"Internal error","code":502}`

注意：所有响应的 HTTP 状态码均为 200，错误码仅体现在响应 JSON 的 code 字段中。

Note: All responses use HTTP status 200. Error codes are only reflected in the code field of the JSON body.

使用示例

Usage Examples

1. 默认随机一言（JSON）

1. Random Sentence (JSON)

https://api.furry.ist/hitokoto

返回示例：

Response example:

{
  "id": 1121,
  "uuid": "ffbf8cf7-bbd0-4496-9fff-1974cb22c73f",
  "hitokoto": "夫君子之行，静以修身，俭以养德，非淡泊无以明志，非宁静无以致远",
  "type": "原创",
  "from": "诫子书",
  "from_who": "诸葛亮",
  "creator": "505622287",
  "creator_uid": 0,
  "reviewer": 0,
  "commit_from": "web",
  "created_at": "1482047360",
  "length": 31,
  "type_desc": "Original - 原创"
}

2. 指定分类（动画）

2. Filter by Category (Anime)

https://api.furry.ist/hitokoto?c=a

3. 多分类筛选

3. Multiple Categories

https://api.furry.ist/hitokoto?c=a&c=b

4. 纯文本返回

4. Plain Text Response

https://api.furry.ist/hitokoto?encode=text

直接返回句子内容（text/plain），无 JSON 包装，适合嵌入页面展示。

Returns the sentence as text/plain with no JSON wrapper — ideal for embedding directly into pages.

5. 限制句子长度

5. Filter by Length

https://api.furry.ist/hitokoto?c=i&min_length=8&max_length=20

在诗词分类中随机返回一条长度为 8～20 字的句子。最多尝试 10 次，超出后随机兜底。

Returns a random sentence from the poetry category with 8–20 characters. Falls back to a random result after 10 attempts.

6. 组合参数

6. Combined Parameters

https://api.furry.ist/hitokoto?c=a&c=b&encode=json

一言 API Hitokoto API