JokeAPI Skill

获取各种类型的幽默笑话，支持分类、语言、格式过滤。

概述

使用 JokeAPI 免费获取笑话，无需注册或 API 密钥。支持多种分类、语言和响应格式。

基本用法

获取随机笑话

joke random

获取指定分类的笑话

joke random --category Programming
joke random --category Misc,Pun

获取特定类型的笑话

joke random --type single    # 单句笑话
joke random --type twopart   # 双部分笑话 (setup + delivery)

过滤不当内容

joke random --safe-mode              # 仅获取安全内容
joke random --blacklist nsfw,explicit  # 过滤特定类型内容

指定语言

joke random --lang en    # 英语笑话
joke random --lang de    # 德语笑话

获取多个笑话

joke random --amount 5

搜索包含特定关键词的笑话

joke random --contains "programmer"

API 端点

主要端点

• 基础 URL: https://v2.jokeapi.dev
• 获取笑话: GET /joke/{categories}
• 获取信息: GET /info
• 获取分类: GET /categories
• 获取语言: GET /languages

可用分类

• Any - 随机分类
• Misc - 杂项
• Programming - 编程
• Dark - 黑暗幽默
• Pun - 双关语
• Spooky - 恐怖
• Christmas - 圣诞

过滤标志 (blacklistFlags)

• nsfw - 不适宜工作场所
• religious - 宗教
• political - 政治
• racist - 种族主义
• sexist - 性别歧视
• explicit - 露骨内容

响应格式

• json (默认)
• xml
• yaml
• txt (纯文本)

示例代码

JavaScript/Node.js

const baseURL = "https://v2.jokeapi.dev";
const categories = ["Programming", "Misc"];
const params = [
  "blacklistFlags=nsfw,religious,racist",
  "type=single"
];

fetch(`${baseURL}/joke/${categories.join(",")}?${params.join("&")}`)
  .then(res => res.json())
  .then(joke => {
    if(joke.type == "single") {
      console.log(joke.joke);
    } else {
      console.log(joke.setup);
      setTimeout(() => {
        console.log(joke.delivery);
      }, 3000);
    }
  });

Python

import requests

url = "https://v2.jokeapi.dev/joke/Programming,Misc"
params = {
    "blacklistFlags": "nsfw,religious,racist",
    "type": "single",
    "format": "json"
}

response = requests.get(url, params=params)
joke = response.json()

if joke["type"] == "single":
    print(joke["joke"])
else:
    print(joke["setup"])
    # 延迟后显示 delivery
    print(joke["delivery"])

Bash

curl -s "https://v2.jokeapi.dev/joke/Programming?format=txt&type=single&blacklistFlags=nsfw,religious,racist"

速率限制

• 每分钟最多 120 次请求
• 超出限制会返回 HTTP 429 错误
• 响应头包含速率限制信息：
  • Retry-After - 多少秒后重置
  • RateLimit-Limit - 每分钟最大请求数
  • RateLimit-Remaining - 剩余请求数

错误处理

API 返回统一格式的错误响应：

{
  "error": true,
  "internalError": false,
  "code": 106,
  "message": "No matching joke found",
  "causedBy": ["No jokes were found that match your provided filter(s)"],
  "additionalInfo": "The specified category is invalid...",
  "timestamp": 1579170794412
}

HTTP 状态码

• 200 - 成功
• 201 - 提交成功
• 400 - 请求格式错误
• 403 - 被黑名单封锁
• 404 - URL 不存在
• 429 - 请求过多
• 500 - 服务器内部错误

注意事项

⚠️ JokeAPI 包含多种类型的笑话，有些可能被视为冒犯性内容。建议：

• 启用 safe-mode 参数
• 使用 blacklistFlags 过滤不当内容
• 根据使用场景选择合适的分类

相关链接

• 官方文档
• GitHub 仓库
• 状态页面
• Discord 服务器