Rednote Home Recommendations
首页推荐请求无需主页、笔记 URL 或搜索词，即可获取一页公开 Rednote 推荐内容。每个可用结果会整理为标准帖子记录，包含来源身份、正文、作者、媒体、可见互动、发布时间和采集时间。
主要特性
- 无种子推荐请求提交空请求体或经过验证的 homefeed_recommend 类别，即可请求当前推荐页，无需虚构用户或查询条件。
- 明确的单页上限results_limit 接受 1 到 40 的整数；省略时使用 20，公开来源实际返回数量可能更少。
- 与 provider 解耦的帖子结构通过共享 post schema 读取可用的笔记身份、正文、作者、媒体、时间和可见指标，不依赖第三方字段名。
- 异步存储结果提交一次任务并跟踪状态，在单次 provider 响应完成标准化后，分页读取 SocQ 已存储记录。
参数
| 参数 | 必填 | 描述 |
|---|---|---|
category | 可选 | 可选的非空字符串。省略时 provider mapping 会注入 homefeed_recommend；这是此处唯一记录的 backend 默认类别，不把其他字符串描述为已验证类别。 |
media_type | 可选 | 可选枚举：all、image 或 video。当前 mapping 仅在 image 时启用 provider 图片标记；all 与 video 都映射为 false，因此 video 不保证只返回视频。 |
results_limit | 可选 | 可选的 1 到 40 正整数，默认值为 20；它会设置 provider 单页请求数量，并在明确提交时限制存储行数。 |
如何使用
只选择 backend 已验证的可选值，提交异步请求，然后读取已存储的标准结果。
- 使用 backend 默认值开始，或明确设置 category、media_type 和 results_limit。
- 将 JSON 请求体 POST 到 /v1/rednote/home-recommendations，并保存提交响应中的 data.task_id。
- 轮询 /v1/tasks/{task_id}，直到任务成功或报告失败。
- 读取 data.results.items；只有 has_more 表示存在更多 SocQ 已存储记录时才继续使用 next_cursor。
curl -X POST "https://api.socq.ai/v1/rednote/home-recommendations" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"category":"homefeed_recommend","media_type":"all","results_limit":20}'
# 轮询 GET /v1/tasks/{task_id}
# 读取 data.results.items；next_cursor 只用于已存储结果分页最佳使用场景
- 推荐页快照： 采集一页有明确上限的公开首页推荐，并用 collected_at 将每条记录关联到本次观察。
- 编辑发现队列： 将标准化正文、作者和媒体引用送入人工审阅、分类或选题流程。
- 可见内容审计： 在多次独立提交的推荐任务之间，比较可用媒体组合和公开互动字段。
使用建议
- 希望完全使用 provider 默认值时可以提交 {}；公开请求校验器不要求任何字段。
- 除非已经独立验证其他 provider 类别，否则保留 homefeed_recommend；runtime 接受非空字符串，但没有发布 category 枚举。
- 谨慎使用 media_type=video，因为它当前与 all 映射为同一个 provider 标记；只有 image 会改变该标记。
- results_limit 应在 1 到 40 之间，也不要假设公开来源一定返回请求的条数。
- 不要发送 provider cursor：上游执行器只请求一次，并从同一响应的 items、notes 或 feeds 中读取结果。
- 任务成功后，next_cursor 只用于继续读取 SocQ 已存储结果，不会再请求一页 Rednote 推荐。
- 每个任务按固定 1.00 SocQ 积分规划预算，费用不随 limit 或实际结果数量变化。