随机一言v1 API 文档

接口说明

一言API是一个本地随机一言接口，内置1.6万条本地一言数据，从本地数据文件中随机获取一条优美的句子。支持按分类获取或随机获取，适用于网站展示、签名档、博客装饰等场景。

本接口为免费接口，支持可选密钥调用。提供多种鉴权方式，方便不同场景下的集成需求。

调用地址

https://openapi.xunjinlu.fun/api/yiyan/v1.php

请求方式

• GET
• POST

鉴权方式

本接口支持以下三种鉴权方式，调用方可根据实际需求选择其中一种：

请求参数

参数说明

key

• 类型：字符串
• 必填：否
• 说明：平台 API 访问密钥。本接口为免费接口，密钥为选填项。提供密钥可享受更高的调用频率限制和优先服务。
• 示例值：sk_xxxxxxxxxxxxxxxx

c

• 类型：整数
• 必填：否
• 说明：一言分类序号。不传该参数时，系统将从全部分类中随机返回一条一言。
• 取值范围：1-12
• 示例值：4

分类取值对照表

成功响应示例

{
    "code": 200,
    "msg": "success",
    "data": {
        "id": "4671",
        "content": "我不借助别人的力量就没办法跟仰慕的人聊天吗？",
        "source": "未知",
        "category_id": 1,
        "category_name": "动画"
    },
    "api_info": {
        "developer": "尋鯨錄",
        "blog": "https://www.xunjinlu.fun",
        "api_platform": "https://api.xunjinlu.fun"
    }
}

错误响应示例

{
    "code": 0,
    "msg": "未提供调用密钥",
    "errcode": 11001
}

响应字段说明

成功响应字段

错误响应字段

业务错误码

调用示例

示例1：随机获取一言（无分类）

# 使用 GET 请求，不传递任何参数
curl -X GET "https://openapi.xunjinlu.fun/api/yiyan/v1.php"

示例2：按分类获取一言

# 使用 GET 请求，获取文学类一言（c=4）
curl -X GET "https://openapi.xunjinlu.fun/api/yiyan/v1.php?c=4"

示例3：使用 Query 参数鉴权

# 使用 GET 请求，通过 Query 参数传递密钥
curl -X GET "https://openapi.xunjinlu.fun/api/yiyan/v1.php?key=sk_xxxxxxxxxxxxxxxx&c=4"

示例4：使用 Header 鉴权

# 使用 GET 请求，通过 Header 传递密钥
curl -X GET "https://openapi.xunjinlu.fun/api/yiyan/v1.php?c=4" \
  -H "X-API-Key: sk_xxxxxxxxxxxxxxxx"

示例5：使用 Bearer Token 鉴权

# 使用 GET 请求，通过 Bearer Token 传递密钥
curl -X GET "https://openapi.xunjinlu.fun/api/yiyan/v1.php?c=4" \
  -H "Authorization: Bearer sk_xxxxxxxxxxxxxxxx"

示例6：使用 POST 请求

# 使用 POST 请求，通过表单数据传递参数
curl -X POST "https://openapi.xunjinlu.fun/api/yiyan/v1.php" \
  -H "X-API-Key: sk_xxxxxxxxxxxxxxxx" \
  -d "c=4"

PHP 调用示例

// 使用 cURL 调用随机一言接口
$ch = curl_init();

// 设置请求地址（获取文学类一言）
$url = "https://openapi.xunjinlu.fun/api/yiyan/v1.php?c=4";

curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);

// 可选：设置 Header 鉴权
$headers = [
    "X-API-Key: sk_xxxxxxxxxxxxxxxx"
];
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

// 执行请求
$response = curl_exec($ch);

// 检查是否有错误
if (curl_errno($ch)) {
    echo "请求失败: " . curl_error($ch);
} else {
    // 解析 JSON 响应
    $data = json_decode($response, true);

    if ($data["code"] == 200) {
        // 成功获取一言
        echo "一言内容: " . $data["data"]["content"] . "\n";
        echo "来源: " . $data["data"]["source"] . "\n";
        echo "分类: " . $data["data"]["category_name"] . "\n";
    } else {
        // 处理错误
        echo "错误: " . $data["msg"] . "\n";
        echo "错误码: " . $data["errcode"] . "\n";
    }
}

// 关闭 cURL 资源
curl_close($ch);

JavaScript 调用示例

// 使用 fetch API 调用随机一言接口
async function getYiyan(category = null) {
    let url = "https://openapi.xunjinlu.fun/api/yiyan/v1.php";

    // 如果指定了分类，添加查询参数
    if (category) {
        url += "?c=" + category;
    }

    try {
        const response = await fetch(url, {
            method: "GET",
            headers: {
                // 可选：设置 Header 鉴权
                "X-API-Key": "sk_xxxxxxxxxxxxxxxx"
            }
        });

        const data = await response.json();

        if (data.code === 200) {
            console.log("一言内容:", data.data.content);
            console.log("来源:", data.data.source);
            console.log("分类:", data.data.category_name);
        } else {
            console.error("错误:", data.msg);
            console.error("错误码:", data.errcode);
        }
    } catch (error) {
        console.error("请求失败:", error);
    }
}

// 调用示例：获取文学类一言
getYiyan(4);

注意事项

1. 调用频率：本接口有调用频率限制，请合理控制请求频率。如需更高频率，建议使用有效密钥调用。

2. 数据更新：一言数据为本地静态数据，定期更新。如需最新数据，请关注平台公告。

3. 错误处理：调用时请务必处理错误响应，根据 errcode 进行相应的错误处理逻辑。

4. HTTPS 建议：生产环境建议使用 HTTPS 协议调用，确保数据传输安全。

5. 缓存策略：建议在客户端实现适当的缓存机制，避免频繁请求相同数据。

常见问题

Q: 不传 key 参数可以调用吗？
A: 可以。本接口为免费接口，key 参数为选填项。但不传 key 可能会受到更严格的调用频率限制。

Q: 分类参数 c 不传会怎样？
A: 不传 c 参数时，系统将从全部分类中随机返回一条一言。

Q: 返回的 content 字段包含 HTML 标签吗？
A: 返回的 content 字段为纯文本，不包含 HTML 标签。如需在前端展示，请自行处理转义和格式化。

Q: 支持跨域调用吗？
A: 支持。接口已配置 CORS 响应头，可在浏览器端直接调用。