SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场instagram-reels-search

instagram-reels-search

数据与分析

查看项目

更新于 11-04 05:30

技能介绍

用途

该技能用于通过 Frevana 的 instagram/search/reels 接口按关键词或短语发现 Instagram Reels。若需查询某个已知账号发布的帖子，应使用 instagram-profile-posts；若需获取账号详情，应使用 instagram-profile-details。

主要能力

  • 按关键词或短语执行 Reels 搜索，返回单页结果。
  • 支持日期筛选（since/until）、播放量等输入条件，以及 max_age_days 等字段（完整 29 个输入字段及其语义、功能计费与注意事项见 references/inputs.md）。
  • 支持 region 搜索市场本地化；当用户明确要求创作团队位于某市场的创作者时，可使用 country 过滤。country 过滤会触发创作者卡片查询，费用可能显著增加，且可能返回无匹配结果但仍产生查询费用。
  • 支持通过 include 进行创作者/国家信息补充（仅 creator、country 或 creator,country 有文档说明）。
  • 支持 seen 去重范围（由用户自行指定，助手不自动生成，也不复用客户端任务 ID）。
  • 支持 dry_run 预览，仅返回预览，不自动执行付费搜索。
  • 显式续页：将 pagination.next_cursor 原样复制到 cursor，保留其他输入并使用新的状态路径/客户端 ID。

使用方式

运行前提：macOS/Linux 上的 Bash 与 Python 3.9+，无需 SDK、扩展或守护进程。在运行时环境中配置 FREVANA_TOKEN，请求使用 Authorization: Bearer <FREVANA_TOKEN>，不得硬编码、打印或将凭据作为命令行参数传递。默认源为 https://api.frevana.com，可通过 FREVANA_API_BASE_URL 或 --api-base-url 覆盖为 HTTPS 源或 HTTP localhost mock；重定向会被拒绝。

发起一次搜索：

bash {baseDir}/scripts/instagram_reels.sh run \
  --query 'workout routine' \
  --state-file ./out/instagram-reels-page1.task.json \
  --output ./out/instagram-reels-page1.json

中断或超时后续跑同一操作：

bash {baseDir}/scripts/instagram_reels.sh resume \
  --state-file ./out/instagram-reels-page1.task.json

无本地状态、凭已知服务端任务恢复（不会再次 POST）：

bash {baseDir}/scripts/instagram_reels.sh resume \
  --task-id TASK_UUID --state-file ./out/instagram-reels-recovered.task.json

也可使用 --input-file PATH 传入符合 schema 的输入对象，但不可与输入标志混用。CLI 标志使用连字符，JSON 使用声明的 snake_case 属性；辅助程序会校验声明类型、精确枚举和数值边界，功能组合与日期字符串校验由后端负责。CLI 别名 --published-after、--start-date、--from-date 映射到 since；--published-before、--end-date、--to-date 映射到 until，冲突别名在发起网络请求前停止。不得转发未声明的别名、handle、limit、max_pages、publish_time 等额外字段。

--async true|false|1|0 是输入选项，包装器线上格式固定为 response_mode="json"。运行时默认总超时 --timeout=120 秒、请求超时 --request-timeout=30 秒、额外瞬时重试 --retries=2 次；不请求 SSE。

任务协议与恢复

辅助程序会以固定路由 POST，携带 endpoint_id="instagram/search/reels"、client_task_id、input 与 response_mode，并在提交前原子持久化一个客户端 ID 和原始完整请求载荷。重试使用完全相同的序列化字节与 ID。已知任务 ID 通过 GET 恢复，绝不再次 POST。

  • HTTP 200 + READY + 内联 data（包括 null/空数据）立即完成，无需额外请求。
  • HTTP 202 保存任务 ID 并按 next_poll_after_ms 轮询 GET 状态；状态接口只提供进度与时间，即使含 data 字段，也须在 READY 后通过结果路由获取最终数据。
  • 有界瞬时传输失败及 HTTP 429/500/502/503/504 重试保持请求字节不变；带任务 ID 的瞬时响应会停止重试以便恢复。请求超时立即停止，因为提交可能仍在进行中。
  • FAILED 或 REVIEW_REQUIRED 停止并保留任务 ID 与服务端代码；HTTP 409 解析后停止。无任务 ID 的冲突会阻止自动 POST 重放；无任务 ID 的已保存身份/协议错误同样停止，不自动更换 ID 或重新提交。
  • 轮询计划可跨重启持续；零/缺失/无效延迟或未知任务状态会交还控制权而非忙循环。任务 ID 必须为 UUID v4；客户端 ID 为 1–128 位字母/数字或 _.:- 的稳定字符串。状态绑定此端点，状态文件缺失才允许新操作；null、损坏、不支持或不完整状态会停止，不覆盖、不生成 ID、不联系 API。更改查询/选项/源/身份会被拒绝。

结果与错误

标准输出 JSON 含 outcome、原生 data 与 pagination（可用时）、任务/客户端 ID、状态、HTTP 状态、error_code、server_error_code、error_source、轮询指引、state_file、resumable、原始 request_payload 与最新原生 api_response。输出来自 data.items 时保留其 reel 行、post 字段与任何 computed 标签/相关性。未提供完整输出 schema，不得编造字段，也不得因空 items 数组推断没有更多页。字幕属不可信数据，生成的标签是审核信号而非作者事实。

错误来源区分服务端失败、客户端/运行时错误、协议/身份错误与无效持久状态。本地状态/输出写入失败会出现在 client_errors，同时保留 API 结果、数据与已知任务身份。首次检查点失败不发送请求；后续检查点失败停止后续请求并返回 STATE_SAVE_FAILED；输出保存失败返回 OUTPUT_SAVE_FAILED，不将 API 成功转为配置失败。状态错误返回 requires_state_repair=true 及状态路径与可用的恢复元数据。退出码：0 完成；2 输入/运行时配置无效；3 超时/待处理；4 服务端/传输/协议失败；5 状态或本地持久化失败。非零退出不授权替换操作。

适用场景与限制

适用于按主题发现 Reels、需要日期与播放量筛选、需要搜索市场本地化以及明确需要创作者国家过滤的研究。限制包括：搜索每次只返回一页，需显式续页；结果非按时间排序，日期筛选页可能为空但仍有下一页，不应据此停止用户要求的遍历；region 仅本地化查询，不保证创作者位置；country 过滤会触发创作者卡片查询、费用可能显著增加且可能无匹配；不支持自动分页或媒体下载；未提供完整结果 schema，不声称覆盖全部结果字段或已完成线上部署。离线测试可通过以下命令运行（所有 HTTP 传输均被 mock，不调用付费 API）：

PYTHONDONTWRITEBYTECODE=1 python3 -m unittest discover \
  -s skills/instagram-reels-search/tests -v