Reddit API

Reddit API 允许你搜索 Reddit 帖子或获取包含嵌套评论的完整帖子详情。两个端点均返回结构化 JSON，包含子版块、作者、评分、标签、奖励和媒体字段。可用于构建讨论感知代理、品牌监控、情感分析，或需要社区来源上下文的 RAG 管道。

响应时间: 5-15 秒。 Reddit 请求比我们其他平台慢得多，因为它们使用 JavaScript 渲染和高级住宅代理来获取最新结果。请将客户端超时设置为至少 30 秒，显示骨架屏或进度指示器，并考虑使用流式传输或异步 UX 模式。

端点

端点	积分	描述
`POST /api/v1/reddit/search`	2	通过关键词、排序方式和分页游标搜索 Reddit 帖子
`POST /api/v1/reddit/post`	2	通过 Reddit 帖子 URL 获取包含嵌套评论的完整帖子

认证

Header	值	必填
`Authorization`	`Bearer YOUR_API_KEY`	是
`Content-Type`	`application/json`	是

帖子搜索

Bash

POST https://api.scavio.dev/api/v1/reddit/search

在整个 Reddit 中搜索帖子。返回帖子元数据，包括标题、URL、子版块、作者、时间戳和 NSFW 标记。支持通过游标令牌进行分页。

请求体

参数	类型	默认值	描述
`query`	`string`	--	必填。搜索关键词 (1-500 字符)。
`sort`	`string`	`relevance`	排序方式。可选值: `relevance`, `hot`, `top`, `new`, `comments`
`cursor`	`string`	--	上一次响应中 `nextCursor` 字段返回的分页令牌。

示例

curl -X POST 'https://api.scavio.dev/api/v1/reddit/search' \
  -H 'Authorization: Bearer sk_live_your_key' \
  -H 'Content-Type: application/json' \
  -d '{
    "query": "best python web frameworks 2026",
    "sort": "new"
  }'

响应示例

JSON

{
  "data": {
    "searchQuery": "best python web frameworks 2026",
    "totalResults": 14,
    "nextCursor": "eyJjYW5kaWRhdGVzX3JldH...",
    "posts": [
      {
        "position": 0,
        "id": "t3_1smb9du",
        "title": "FastAPI vs Django in 2026 -- what the teams are actually using",
        "url": "https://www.reddit.com/r/Python/comments/1smb9du/fastapi_vs_django/",
        "subreddit": "Python",
        "author": "python_dev",
        "timestamp": "2026-04-15T16:34:40.389000+0000",
        "nsfw": false
      }
    ]
  },
  "response_time": 5200,
  "credits_used": 2,
  "credits_remaining": 498
}

分页

要获取下一页，请将上一次响应中的 nextCursor 值作为下一个请求的 cursor 参数传递。当 nextCursor 为 null 时，表示没有更多结果。

帖子详情

Bash

POST https://api.scavio.dev/api/v1/reddit/post

通过 URL 获取完整的 Reddit 帖子，包括帖子正文、元数据和完整的嵌套评论树。评论包含 depth 字段，可用于重建评论层级结构。

请求体

参数	类型	默认值	描述
`url`	`string`	--	必填。完整的 Reddit 帖子 URL (例如 `https://www.reddit.com/r/Python/comments/1smb9du/fastapi_vs_django/`)。

示例

curl -X POST 'https://api.scavio.dev/api/v1/reddit/post' \
  -H 'Authorization: Bearer sk_live_your_key' \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://www.reddit.com/r/Python/comments/1smb9du/fastapi_vs_django/"
  }'

响应示例

JSON

{
  "data": {
    "post": {
      "id": "t3_1smb9du",
      "title": "FastAPI vs Django in 2026 -- what the teams are actually using",
      "body": "After a year of running both in production...",
      "url": "https://www.reddit.com/r/Python/comments/1smb9du/fastapi_vs_django/",
      "contentUrl": "https://www.reddit.com/r/Python/comments/1smb9du/fastapi_vs_django/",
      "subreddit": "Python",
      "author": "python_dev",
      "score": 842,
      "upvoteRatio": 0.97,
      "numComments": 214,
      "timestamp": "2026-04-15T16:34:40.389000+0000",
      "flair": "Discussion",
      "nsfw": false,
      "awards": []
    },
    "comments": [
      {
        "id": "t1_lxs9a0k",
        "author": "senior_py",
        "body": "We moved to FastAPI for the API surface and kept Django for admin...",
        "score": 312,
        "depth": 0,
        "timestamp": "2026-04-15T17:02:11.000000+0000",
        "parentId": "t3_1smb9du"
      },
      {
        "id": "t1_lxsa1b2",
        "author": "django_dev",
        "body": "Django ORM is still unmatched for anything with relational depth.",
        "score": 178,
        "depth": 1,
        "timestamp": "2026-04-15T17:15:42.000000+0000",
        "parentId": "t1_lxs9a0k"
      }
    ]
  },
  "response_time": 8900,
  "credits_used": 2,
  "credits_remaining": 496
}

重建评论树

评论以遍历顺序的扁平数组返回。使用 depth 字段 (从 0 开始) 进行视觉缩进，或通过每条评论的 parentId 重建完整的树结构。顶级回复的 parentId 等于帖子 id (例如 t3_…)；嵌套回复的 parentId 等于另一条评论的 id (例如 t1_…)。

url 与 contentUrl

url 是帖子的 Reddit 规范永久链接。 contentUrl 是 Reddit 在帖子正文中渲染的 URL -- 对于链接帖子，这将是外部文章；对于自发/文本帖子，它与 url 相同；对于图片/视频帖子，它是 i.redd.it 或 v.redd.it 上的媒体 URL。

响应格式

两个端点返回一致的响应包装结构:

字段	类型	描述
`data`	`object \| null`	响应数据载荷。如果上游请求失败则为 `null`。搜索返回 `{searchQuery, totalResults, nextCursor, posts}`；帖子详情返回 `{post, comments}`。
`response_time`	`number`	服务端响应时间 (毫秒)
`credits_used`	`number`	消耗的积分数量 (Reddit 端点始终为 2)
`credits_remaining`	`number`	当前计费周期内的剩余积分

错误响应

状态码	描述
`400`	无效的请求体 -- 缺少 `query` / `url`、无效的游标或不支持的排序值
`401`	未授权 -- 缺少或无效的 API 密钥
`429`	超出当前套餐的速率或用量限制
`502`	上游错误 -- 请在短暂延迟后重试
`503`	上游不可用 -- 请稍后重试
`504`	上游超时 -- Reddit 请求可能需要 5-15 秒；请设置更长的客户端超时后重试

参见错误参考获取完整的错误代码说明和重试最佳实践。

Reddit API

端点

端点	积分	描述
`POST /api/v1/reddit/search`	2	通过关键词、排序方式和分页游标搜索 Reddit 帖子
`POST /api/v1/reddit/post`	2	通过 Reddit 帖子 URL 获取包含嵌套评论的完整帖子

认证

Header	值	必填
`Authorization`	`Bearer YOUR_API_KEY`	是
`Content-Type`	`application/json`	是

帖子搜索

Bash

POST https://api.scavio.dev/api/v1/reddit/search

在整个 Reddit 中搜索帖子。返回帖子元数据，包括标题、URL、子版块、作者、时间戳和 NSFW 标记。支持通过游标令牌进行分页。

请求体

参数	类型	默认值	描述
`query`	`string`	--	必填。搜索关键词 (1-500 字符)。
`sort`	`string`	`relevance`	排序方式。可选值: `relevance`, `hot`, `top`, `new`, `comments`
`cursor`	`string`	--	上一次响应中 `nextCursor` 字段返回的分页令牌。

示例

curl -X POST 'https://api.scavio.dev/api/v1/reddit/search' \
  -H 'Authorization: Bearer sk_live_your_key' \
  -H 'Content-Type: application/json' \
  -d '{
    "query": "best python web frameworks 2026",
    "sort": "new"
  }'

响应示例

JSON

{
  "data": {
    "searchQuery": "best python web frameworks 2026",
    "totalResults": 14,
    "nextCursor": "eyJjYW5kaWRhdGVzX3JldH...",
    "posts": [
      {
        "position": 0,
        "id": "t3_1smb9du",
        "title": "FastAPI vs Django in 2026 -- what the teams are actually using",
        "url": "https://www.reddit.com/r/Python/comments/1smb9du/fastapi_vs_django/",
        "subreddit": "Python",
        "author": "python_dev",
        "timestamp": "2026-04-15T16:34:40.389000+0000",
        "nsfw": false
      }
    ]
  },
  "response_time": 5200,
  "credits_used": 2,
  "credits_remaining": 498
}

分页

要获取下一页，请将上一次响应中的 nextCursor 值作为下一个请求的 cursor 参数传递。当 nextCursor 为 null 时，表示没有更多结果。

帖子详情

Bash

POST https://api.scavio.dev/api/v1/reddit/post

通过 URL 获取完整的 Reddit 帖子，包括帖子正文、元数据和完整的嵌套评论树。评论包含 depth 字段，可用于重建评论层级结构。

请求体

参数	类型	默认值	描述
`url`	`string`	--	必填。完整的 Reddit 帖子 URL (例如 `https://www.reddit.com/r/Python/comments/1smb9du/fastapi_vs_django/`)。

示例

curl -X POST 'https://api.scavio.dev/api/v1/reddit/post' \
  -H 'Authorization: Bearer sk_live_your_key' \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://www.reddit.com/r/Python/comments/1smb9du/fastapi_vs_django/"
  }'

响应示例

JSON

{
  "data": {
    "post": {
      "id": "t3_1smb9du",
      "title": "FastAPI vs Django in 2026 -- what the teams are actually using",
      "body": "After a year of running both in production...",
      "url": "https://www.reddit.com/r/Python/comments/1smb9du/fastapi_vs_django/",
      "contentUrl": "https://www.reddit.com/r/Python/comments/1smb9du/fastapi_vs_django/",
      "subreddit": "Python",
      "author": "python_dev",
      "score": 842,
      "upvoteRatio": 0.97,
      "numComments": 214,
      "timestamp": "2026-04-15T16:34:40.389000+0000",
      "flair": "Discussion",
      "nsfw": false,
      "awards": []
    },
    "comments": [
      {
        "id": "t1_lxs9a0k",
        "author": "senior_py",
        "body": "We moved to FastAPI for the API surface and kept Django for admin...",
        "score": 312,
        "depth": 0,
        "timestamp": "2026-04-15T17:02:11.000000+0000",
        "parentId": "t3_1smb9du"
      },
      {
        "id": "t1_lxsa1b2",
        "author": "django_dev",
        "body": "Django ORM is still unmatched for anything with relational depth.",
        "score": 178,
        "depth": 1,
        "timestamp": "2026-04-15T17:15:42.000000+0000",
        "parentId": "t1_lxs9a0k"
      }
    ]
  },
  "response_time": 8900,
  "credits_used": 2,
  "credits_remaining": 496
}

重建评论树

url 与 contentUrl

响应格式

两个端点返回一致的响应包装结构:

字段	类型	描述
`data`	`object \| null`	响应数据载荷。如果上游请求失败则为 `null`。搜索返回 `{searchQuery, totalResults, nextCursor, posts}`；帖子详情返回 `{post, comments}`。
`response_time`	`number`	服务端响应时间 (毫秒)
`credits_used`	`number`	消耗的积分数量 (Reddit 端点始终为 2)
`credits_remaining`	`number`	当前计费周期内的剩余积分

错误响应

状态码	描述
`400`	无效的请求体 -- 缺少 `query` / `url`、无效的游标或不支持的排序值
`401`	未授权 -- 缺少或无效的 API 密钥
`429`	超出当前套餐的速率或用量限制
`502`	上游错误 -- 请在短暂延迟后重试
`503`	上游不可用 -- 请稍后重试
`504`	上游超时 -- Reddit 请求可能需要 5-15 秒；请设置更长的客户端超时后重试

参见错误参考获取完整的错误代码说明和重试最佳实践。

Reddit API

端点

认证

帖子搜索

请求体

示例

响应示例

分页

帖子详情

请求体

示例

响应示例

重建评论树

url 与 contentUrl

响应格式

错误响应

相关文档

Reddit API

端点

认证

帖子搜索

请求体

示例

响应示例

分页

帖子详情

请求体

示例

响应示例

重建评论树

url 与 contentUrl

响应格式

错误响应

相关文档