Reddit API 指南：开发者完整教程 (2026)

Reddit API 指南：完整开发者教程 (2026)

Reddit 的 API 允许你通过编程方式访问互联网上最大的社区之一。你可以构建机器人、分析工具、内容聚合器、监控系统等。本指南涵盖了 2026 年开始使用 Reddit API 所需的一切，包括身份验证、核心端点、速率限制和代码示例。

2026 年的 Reddit API：你需要知道的事

自 2023 年 API 定价策略调整以来，Reddit 的免费 API 层级虽然受到了更多限制，但仍可用于非商业用途和小型项目。以下是目前的状况：

层级	速率限制	费用	使用场景
免费 (非商业)	100 次请求/分钟	免费	个人项目、研究、机器人
免费 (商业)	100 次请求/分钟	免费 (需申请)	低流量商业应用
企业级	自定义	联系 Reddit	高流量商业用途

所有访问均需要 OAuth2 身份验证。旧的基于 Cookie 的身份验证和未认证访问已不再支持。

第 1 步：创建 Reddit 应用

1. 前往 reddit.com/prefs/apps。
2. 滚动到底部并点击 "create another app..."。
3. 填写详细信息：

字段	值
Name	你的应用名称
Type	Script (个人使用) 或 Web app (供他人使用)
Description	应用的简短描述
About URL	你的网站或 GitHub 仓库地址
Redirect URI	http://localhost:8080 (针对 script 类型的应用)

4. 点击 Create app。
5. 记下你的 Client ID (位于应用名称下方) 和 Client Secret。

# 你的凭据
export REDDIT_CLIENT_ID="your_client_id"
export REDDIT_CLIENT_SECRET="your_client_secret"
export REDDIT_USERNAME="your_username"
export REDDIT_PASSWORD="your_password"

第 2 步：使用 OAuth2 进行身份验证

Reddit 要求所有 API 请求都使用 OAuth2。对于脚本类型的应用 (个人使用)，请使用密码授权流 (password grant flow)。

使用 cURL

# 获取 access token
curl -X POST 'https://www.reddit.com/api/v1/access_token' \
  -u "$REDDIT_CLIENT_ID:$REDDIT_CLIENT_SECRET" \
  -d "grant_type=password&username=$REDDIT_USERNAME&password=$REDDIT_PASSWORD" \
  -A "MyApp/1.0 by YourUsername"

响应：

{
  "access_token": "your_access_token",
  "token_type": "bearer",
  "expires_in": 86400,
  "scope": "*"
}

使用 Python (通过 PRAW)

PRAW (Python Reddit API Wrapper) 是 Python 的官方推荐库。它会自动处理身份验证、速率限制和分页。

pip install praw

import praw

reddit = praw.Reddit(
    client_id="your_client_id",
    client_secret="your_client_secret",
    username="your_username",
    password="your_password",
    user_agent="MyApp/1.0 by YourUsername",
)

# 验证身份
print(f"Logged in as: {reddit.user.me()}")

使用 JavaScript (通过 snoowrap)

npm install snoowrap

import Snoowrap from 'snoowrap';

const reddit = new Snoowrap({
  userAgent: 'MyApp/1.0 by YourUsername',
  clientId: process.env.REDDIT_CLIENT_ID,
  clientSecret: process.env.REDDIT_CLIENT_SECRET,
  username: process.env.REDDIT_USERNAME,
  password: process.env.REDDIT_PASSWORD,
});

重要提示：设置具有描述性的 User-Agent

Reddit 要求提供唯一的 User-Agent 字符串，且会限制或封锁通用的字符串：

# 正确示例
MyResearchBot/1.0 by u/YourUsername

# 错误示例
python:requests
Mozilla/5.0

第 3 步：核心 API 端点

所有经过身份验证的请求都发送至 https://oauth.reddit.com (而非 www.reddit.com)。

获取 Subreddit 帖子

Python (PRAW):

# 获取 r/programming 的前 10 个热门帖子
subreddit = reddit.subreddit("programming")

for post in subreddit.hot(limit=10):
    print(f"{post.score:>6} | {post.title}")
    print(f"       | {post.url}")
    print()

JavaScript (snoowrap):

const posts = await reddit.getSubreddit('programming').getHot({ limit: 10 });

posts.forEach(post => {
  console.log(`${post.score} | ${post.title}`);
  console.log(`  ${post.url}`);
});

cURL:

curl -H "Authorization: Bearer $ACCESS_TOKEN" \
     -A "MyApp/1.0 by YourUsername" \
     "https://oauth.reddit.com/r/programming/hot?limit=10"

搜索 Reddit

# 在全站范围内搜索
results = reddit.subreddit("all").search("machine learning", sort="relevance", time_filter="month", limit=20)

for post in results:
    print(f"r/{post.subreddit} | {post.title}")

获取帖子的评论

submission = reddit.submission(id="post_id_here")
submission.comments.replace_more(limit=0)  # 展平评论树

for comment in submission.comments.list():
    print(f"u/{comment.author}: {comment.body[:100]}")

发布帖子

# 发布文本帖
subreddit = reddit.subreddit("test")
subreddit.submit(
    title="My Post Title",
    selftext="This is the body of my post."
)

# 发布链接帖
subreddit.submit(
    title="Check out this article",
    url="https://example.com/article"
)

回复评论

comment = reddit.comment(id="comment_id_here")
comment.reply("Thanks for sharing! Great insight.")

获取用户信息

user = reddit.redditor("spez")

print(f"Username: {user.name}")
print(f"Karma: {user.link_karma + user.comment_karma}")
print(f"Account created: {user.created_utc}")

# 获取用户最近的发布
for post in user.submissions.new(limit=5):
    print(f"  {post.title}")

核心端点参考

端点	方法	描述
/r/{subreddit}/hot	GET	Subreddit 中的热门帖子
/r/{subreddit}/new	GET	最新帖子
/r/{subreddit}/top	GET	最高分帖子 (添加 ?t=day/week/month/year/all)
/r/{subreddit}/search	GET	在 Subreddit 内搜索
/api/submit	POST	创建新帖子
/api/comment	POST	发表评论
/api/vote	POST	顶/踩 (Upvote/downvote)
/api/subscribe	POST	订阅/取消订阅子版块
/user/{username}/about	GET	用户个人资料信息
/user/{username}/submitted	GET	用户的帖子
/user/{username}/comments	GET	用户的评论
/api/v1/me	GET	当前通过身份验证的用户
/subreddits/search	GET	搜索 Subreddit

速率限制与最佳实践

当前速率限制

资源	限制
每分钟请求数	100 (已认证)
每分钟请求数	10 (未认证，已废弃)
Token 刷新	每 24 小时
列表分页	每页最多 100 项，总计 1000 项

需监控的 Header

检查这些响应头以跟踪你的速率限制使用情况：

# 使用原生 requests 构建
import requests

response = requests.get(
    "https://oauth.reddit.com/r/programming/hot",
    headers={
        "Authorization": f"Bearer {access_token}",
        "User-Agent": "MyApp/1.0 by YourUsername",
    }
)

print(f"Remaining: {response.headers.get('x-ratelimit-remaining')}")
print(f"Reset in: {response.headers.get('x-ratelimit-reset')} seconds")
print(f"Used: {response.headers.get('x-ratelimit-used')}")

最佳实践

1. 尊重速率限制。 PRAW 会自动处理此问题。如果使用原生 HTTP，请实现指数退避 (exponential backoff) 机制。

2. 缓存响应。 Reddit 的数据并不会每秒都发生变化。建议将 Subreddit 列表缓存 60-120 秒。

3. 使用 .json 后缀进行快速测试。 你可以在大多数 Reddit URL 后追加 .json 来查看原始 JSON 数据 (这不计入 API 使用量)：

https://www.reddit.com/r/programming/hot.json

4. 正确处理分页。 使用 after 参数配合最后一项的 fullname：

# 手动分页
params = {"limit": 100, "after": None}
all_posts = []

for _ in range(10):  # 最多获取 10 页
    response = requests.get(
        "https://oauth.reddit.com/r/programming/new",
        params=params,
        headers=headers,
    )
    data = response.json()
    posts = data["data"]["children"]
    all_posts.extend(posts)

    after = data["data"]["after"]
    if not after:
        break
    params["after"] = after

构建一个简单的 Reddit 机器人

这是一个完整的机器人示例，它监控子版块的关键字并进行回复：

import praw
import time

reddit = praw.Reddit(
    client_id="your_client_id",
    client_secret="your_client_secret",
    username="your_bot_username",
    password="your_bot_password",
    user_agent="KeywordBot/1.0 by u/YourUsername",
)

subreddit = reddit.subreddit("test")
keywords = ["help", "question", "how to"]

print("Bot is running...")

# 实时流式传输新评论
for comment in subreddit.stream.comments(skip_existing=True):
    body_lower = comment.body.lower()

    if any(keyword in body_lower for keyword in keywords):
        print(f"Found keyword in comment by u/{comment.author}")
        print(f"  {comment.body[:100]}")

        # 回复评论
        try:
            comment.reply(
                "Hi! It looks like you might need help. "
                "Check out the subreddit wiki for common answers."
            )
            print("  Replied successfully!")
        except Exception as e:
            print(f"  Failed to reply: {e}")

        time.sleep(2)  # 避免触发速率限制

错误处理

常见错误及其解决方法：

状态码	含义	解决方案
401	Token 已过期或无效	刷新你的 access token
403	无权限 (被封禁、权限范围不对)	检查应用权限和账号状态
429	达到速率限制	等待并使用退避策略重试
500	Reddit 服务器错误	延迟后重试
503	Reddit 负载过高	等待 30-60 秒后重试

import time
import requests

def reddit_request(url, headers, max_retries=3):
    for attempt in range(max_retries):
        response = requests.get(url, headers=headers)

        if response.status_code == 200:
            return response.json()
        elif response.status_code == 429:
            wait = int(response.headers.get("x-ratelimit-reset", 60))
            print(f"Rate limited. Waiting {wait}s...")
            time.sleep(wait)
        elif response.status_code >= 500:
            time.sleep(2 ** attempt * 10)
        else:
            response.raise_for_status()

    raise Exception("Max retries exceeded")

总结

Reddit API 仍然是构建机器人、分析平台和社交监控工具的强大手段。Python 项目请使用 PRAW，JavaScript 项目请使用 snoowrap，并且请务必遵守速率限制和 Reddit 的 API 服务条款。

如果你正在构建能够将社交媒体数据与 AI 驱动的多媒体生成相结合的应用（例如将热门帖子制作成视觉摘要，或从 Reddit 帖中生成 AI 视频内容），请关注 Hypereal AI。Hypereal 提供高性价比的 AI 图像和视频生成 API，可轻松集成到你的数据流水线中。