stormy-cookbook

<p align="center"> <img src="assets/hero.svg" alt="Stormy AI 社交数据手册 — 一个REST API和一个MCP服务器，适用于Instagram、YouTube、TikTok、X、LinkedIn和Reddit" width="100%"> </p> # Stormy Cookbook —— TikTok、YouTube、Instagram、LinkedIn、X 和 Reddit API 适用于 AI 代理的配方 开源、可复制的 **Stormy 社交数据 API** 和 **Stormy MCP 服务器** （模型上下文协议，可流式传输的HTTP）的配方。 一个 HTTP 契约 — `search`、`profile`、`emails`、`jobs` — 跨六个社交网络。无需代理池，无需六个供应商的SDK，无需维护爬虫。 将您的代理指向 `https://stormy.ai/mcp`，或直接使用 `curl` 调用 REST 基地址 `https://stormy.ai/api/v1`。 [](LICENSE) [](https://github.com/OneInterface/stormy-cookbook/actions/workflows/link-check.yml) [](https://modelcontextprotocol.io) [](#what-you-can-do-on-each-network) [](https://stormy.ai/docs) **跳转到：** [配方](#recipes) · [MCP 快速入门](#quickstart-a-connect-the-mcp-server) · [REST 快速入门](#quickstart-b-call-the-rest-api-directly) · [端点](#the-whole-api-on-one-screen) · [定价](#pricing) · [错误](#errors-and-retries) · [FAQ](#faq) --- ## 为什么存在 每个“获取社交数据”的项目都以相同的方式开始：六个不同的API、六种身份验证方案、六个速率限制、六个响应形状，以及一个容易在星期二就崩溃的爬虫。然后，您在上面安装一个LLM，并发现没有一个是为代理而设计的——没有成本信号，没有幂等性，没有持久作业，没有机器可读的功能列表。 Stormy 就是这一层，已经构建完成。本手册是关于如何使用它。 <p align="center"> <img src="assets/architecture.svg" alt="请求流程：您的代理通过MCP或REST调用Stormy；Stormy处理身份验证、缓存优先路由、持久作业、共享提供程序速率限制和每个调用的计量，然后从六个社交网络读取公共数据" width="100%"> </p> --- ## 快速入门 A：连接 MCP 服务器 Stormy **MCP 服务器** 在 `https://stormy.ai/mcp` 处使用可流式传输的HTTP进行通信，并使用HTTP bearer令牌进行身份验证。 在 [stormy.ai/account](https://stormy.ai/account) 获取密钥并导出： ```bash export STORMY_API_KEY="stm_live_..." # 永远不要提交这个 ``` ### Claude 代码 ```bash claude mcp add --transport http stormy https://stormy.ai/mcp \ --header "Authorization: Bearer $STORMY_API_KEY" ``` ### Codex CLI (`~/.codex/config.toml`) ```toml [mcp_servers.stormy] url = "https://stormy.ai/mcp" bearer_token_env_var = "STORMY_API_KEY" ``` ### Cursor / Windsurf / 任意 `mcp.json` 客户端 ```json { "mcpServers": { "stormy": { "url": "https://stormy.ai/mcp", "headers": { "Authorization": "Bearer ${STORMY_API_KEY}" } } } } ``` ### ChatGPT 自定义连接器 ```text 名称： Stormy 社交数据 MCP URL： https://stormy.ai/mcp 身份验证： OAuth ``` ### 您获得的十种 MCP 工具 | 工具 | 功能 | | --- | --- | | `search_people(platform, query, limit=10, fresh=false)` | 根据自然语言查询搜索一个网络 | | `lookup_profile(target, platform=null, fresh=false, include_posts=false)` | 将 URL / `@handle` / 通道 ID 解析为规范化配置文件 | | `find_emails(platform, targets)` | Instagram、TikTok 或 YouTube 配置文件的验证联系邮箱 | | `estimate_price(quantity=100, include_email=false)` | 费率卡 + 最大估计值，不消耗费用 | | `account_status()` | 计划、剩余预付费用、充值网址 | | `describe_social_data()` | 机器可读的平台 / 字段 / 定价 / 工作流合约 | | `start_social_job(operation, arguments, idempotency_key, ...)` | 持久地排队新鲜、批量或电子邮件工作 | | `get_social_job(job_id)` | 状态、进度、`poll_after_seconds`、结果、完整时间线 | | `list_social_jobs(status=null, limit=20)` | 恢复以前的工作而不是重新提交 | | `cancel_social_job(job_id)` | 取消排队 / 调度 / 限流 / 重试的工作 | 然后直接提问： > 查找 25 个 TikTok 创建者，发布关于家用意式咖啡的内容，拉取他们的关注者数量，并告诉我花费了多少钱。 --- ## 快速入门 B：直接调用 REST API 基准 URL： **`https://stormy.ai/api/v1`** （也可在 `https://api.stormy.ai/api/v1` 访问）。 身份验证：`Authorization: Bearer <key>` **或** `X-API-Key: <key>`。 永远不要在 URL、JSON 正文、提示或 MCP 工具参数中放置密钥。 ### curl ```bash curl -X POST 'https://stormy.ai/api/v1/search' \ -H "Authorization: Bearer $STORMY_API_KEY" \ -H 'Content-Type: application/json' \ -H 'Idempotency-Key: espresso-tiktok-2026-07' \ -d '{ "platform": "tiktok", "query": "家用意式咖啡和咖啡设备创作者", "limit": 25, "fresh": true }' ``` ### Python ```python import os import requests response = requests.post( "https://stormy.ai/api/v1/search", headers={ "Authorization": f"Bearer {os.environ['STORMY_API_KEY']}", "Idempotency-Key": "espresso-tiktok-2026-07", }, json={ "platform": "tiktok", "query": "家用意式咖啡和咖啡设备创作者", "limit": 25, "fresh": True, }, timeout=90, ) response.raise_for_status() payload = response.json() for creator in payload["results"]: print(creator["handle"], creator["follower_count"]) print("cost:", payload["usage"]["cost_usd"], "USD") ``` ### TypeScript ```ts const response = await fetch("https://stormy.ai/api/v1/search", { method: "POST", headers: { Authorization: `Bearer ${process.env.STORMY_API_KEY}`, "Content-Type": "application/json", "Idempotency-Key": "espresso-tiktok-2026-07", }, body: JSON.stringify({ platform: "tiktok", query: "家用意式咖啡和咖啡设备创作者", limit: 25, fresh: true, }), }); if (!response.ok) throw new Error(await response.text()); const { results, usage } = await response.json(); console.log(results.length, "creators for", usage.cost_usd, "USD"); ``` ### 返回内容 ```json { "ok": true, "platform": "tiktok", "query": "家用意式咖啡和咖啡设备创作者", "fresh": true, "results": [ { "id": "6812...", "handle": "@homebarista", "nickname": "家庭吧台", "url": "https://tiktok.com/@homebarista", "signature": "家用意式咖啡，无需讲究。", "verified": false, "follower_count": 184000, "following_count": 312, "likes_count": 4210000, "video_count": 612 } ], "usage": { "operation": "fresh_discovery", "metered_results": 25, "billed_results": 25, "cost_usd": "2.00", "credits": 200, "plan": "paid", "remaining_usage_usd": "23.00" } } ``` 每个成功的响应都包含一个 `usage` 收据。您仅需为**结果**付费，而不是请求。 --- ## 每个网络可以执行的操作 <p align="center"> <img src="assets/capability-matrix.svg" alt="功能矩阵：Stormy 端点在每个网络上的支持情况，以及四种使用费率" width="100%"> </p> | 网络 | `POST /search` | `POST /profile` | `include_posts` | `POST /emails` | 公共字段 | | --- | --- | --- | --- | --- | --- | | **TikTok API** | 创作者按领域 | `@handle` 或 URL | 视频、浏览量、分享量、保存量、音乐、标签 | ✅ 验证邮箱 | 27 | | **YouTube API** | 按主题的频道 | 句柄或频道 ID | 视频、转录、字幕 | ✅ 验证邮箱 | 25 | | **Instagram API** | 创作者按领域 | 用户名或 URL | 帖子、字幕、互动、位置 | ✅ 验证邮箱 | 23 | | **X (Twitter) API** | 账户和帖子 | `@handle` 或 URL | 帖子、浏览量、书签、对话 ID | — | 26 | | **LinkedIn API** | 人和公司 | 配置文件 URL | 帖子、反应分解、节奏 | — | 31 | | **Reddit API** | 按主题的帖子 | 作者积分和年龄 | 分数、投票比例、评论数 | — | 17 | 字段列表在 `GET /api/v1/capabilities` → `fields_by_platform` 中是权威的。 将每个特定于平台的字段视为 **可空** — 当公共且来源提供时，您会收到。 <details> <summary><b>每个网络的字段列表</b>（点击展开）</summary> **TikTok** — profile: `id`, `sec_uid`, `handle`, `nickname`, `url`, `signature`, `avatar_url`, `verified`, `follower_count`, `following_count`, `likes_count`, `video_count` · posts: `video_id`, `url`, `description`, `create_time`, `duration`, `views`, `likes`, `comments`, `shares`, `saves`, `image_url`, `is_pinned`, `music`, `hashtags`, `caption_url` **YouTube** — profile: `channel_id`, `handle`, `name`, `url`, `subscribers`, `description`, `videos_count`, `total_views`, `profile_image_url`, `banner_image_url`, `country`, `keywords`, `links` · posts: `video_id`, `url`, `title`, `description`, `published_at`, `duration`, `views`, `likes`, `comments`, `thumbnail_url`, `transcript`, `caption_url` **Instagram** — profile: `username`, `full_name`, `biography`, `profile_pic_url`, `follower_count`, `following_count`, `posts_count`, `avg_engagement_rate`, `biolinks`, `country`, `is_verified`, `is_business_account`, `business_category_name` · posts: `media_id`, `post_url`, `caption`, `taken_at`, `like_count`, `comment_count`, `image_url`, `location`, `location_data`, `comments` **X (Twitter) — profile: `id`, `handle`, `name`, `url`, `description`, `profile_image_url`, `verified`, `location`, `website`, `followers`, `following`, `posts_count`, `joined_at` · posts: `id`, `url`, `text`, `created_at`, `language`, `likes`, `replies`, `reposts`, `quotes`, `views`, `bookmarks`, `conversation_id`, `author` **LinkedIn — profile: `id`, `name`, `linkedin_url`, `headline`, `country`, `country_iso_2`, `followers`, `total_posts`, `posts_last_6_months`, `posting_frequency`, `avg_likes`, `avg_comments`, `avg_reposts`, `avg_total_interactions`, `top_post_text`, `top_post_interactions`, `last_post_date`, `ai_summary`, `is_suitable_for_promotion`, `relevant_posts` · posts: `post_url`, `text`, `headline`, `posted_datetime`, `total_interactions`, `num_likes`, `num_comments`, `num_reposts`, `num_reactions_breakdown`, `poster_name`, `poster_linkedin_url` **Reddit — profile: `author`, `author_url`, `karma`, `account_created_at` · posts: `id`, `url`, `permalink`, `subreddit`, `author`, `title`, `text`, `created_at`, `score`, `upvote_ratio`, `comments_count`, `is_self`, `over_18` </details> --- ## 配方 每个配方都是单个可运行的 Markdown 文件，包含真实代码和真实成本估算。完整索引与难度和定价： **[recipes/README.md](recipes/README.md)**. | # | 配方 | 网络 | 您获得的内容 | | --- | --- | --- | --- | | 01 | [按领域查找影响者](recipes/01-find-influencers-by-niche.md) | TikTok, YouTube, Instagram | 带有关注者数量和互动的排名短列表 | | 02 | [构建带有验证邮箱的联系人列表](recipes/02-build-an-outreach-list-with-verified-emails.md) | TikTok, YouTube, Instagram | 搜索 → 过滤 → `/emails` → CSV, 只需支付实际结果 | | 03 | [从句柄丰富 CRM](recipes/03-enrich-a-crm-from-handles.md) | 所有六个 | 句柄输入, 规范化配置文件行输出 | | 04 | [竞争者内容分析](recipes/04-competitor-content-analysis.md) | TikTok, YouTube, Instagram | 对手帖子实际效果为何 | | 05 | [监控创作者随时间变化](recipes/05-monitor-a-creator-over-time.md) | 任意 | 每天快照作业和增长增量 | | 06 | [跨平台受众研究](recipes/06-cross-platform-audience-research.md) | 所有六个 | 一个查询扩展到六个网络, 合并 | | 07 | [Reddit 主题聆听](recipes/07-reddit-topic-listening.md) | Reddit, X | 哪些帖子在一个您关心的主题上正在移动 | | 08 | [用于大批量集合的持久作业](recipes/08-durable-jobs-for-large-collections.md) | 所有六个 | 超过 1,000 个结果, 而无需保持 HTTP 连接 | | 09 | [从 MCP 代理使用 Stormy](recipes/09-agent-workflows-with-mcp.md) | 所有六个 | 提示 + 工具策略适用于 Claude Code, Cursor, Codex | | 10 | [处理错误, 速率限制和计费](recipes/10-errors-rate-limits-and-billing.md) | — | 402 / 429 / 503 处理, 无头充值, 幂等性 | --- ## 整个 API 在一个屏幕上 ### 付费调用 | 方法 | 路径 | 正文 | 备注 | | --- | --- | --- | --- | | `POST` | `/search` | `platform`, `query`, `limit` (1–100, 默认 10), `fresh` (默认 `false`) | 缓存优先。`fresh=true` 调用实时提供者 | | `POST` | `/profile` | `target`, `platform?`, `fresh`, `include_posts` | 返回 `data`, 而不是 `results`。当 `target` 是 URL 时, `platform` 是可选的 | | `POST` | `/emails` | `platform` (`instagram` \| `tiktok` \| `youtube`), `targets` (1–25) | 唯一返回联系人数据的端点 | | `POST` | `/jobs` | `operation`, `arguments`, `delay_seconds` (0–604800), `priority` (−10…10), `max_attempts` (1–10) | `202 Accepted`。`operation` ∈ `search_people`, `lookup_profile`, `find_emails` | | `GET` | `/jobs/{job_id}` | `?include_events=true` | 状态, 进度和事件时间线 | | `GET` | `/jobs` | `?status=running&limit=20` | 列出最近的作业 | | `DELETE` | `/jobs/{job_id}` | — | 取消非终端工作 | ### 免费调用 | 方法 | 路径 | 备注 | | --- | --- | --- | | `GET` | `/pricing?quantity=100&include_email=true` | 权威费率卡 + 最大估计值 | | `GET` | `/capabilities` | 平台, 平台字段, 端点, 作业状态, 代理策略 | | `GET` | `/account` | 计划, `usage_balance`, 作用域, 充值网址 | | `POST` | `/account/top-up` | `amount_usd`, `note?` → 即时 Stripe `checkout_url` | | `GET` | `POST` | `DELETE` | `/keys`, `/keys/{id}` | 列出, 创建和撤销 API 密钥 | 旧别名 `/social/search`, `/social/profile` 和 `/social/emails` 仍然有效; 新客户端应使用短路径。 发送 **`Idempotency-Key`** 头部在任何付费调用中。同一个键重试永远不会重复工作或收费。 ### 机器可读合约 | 资源 | URL | | --- | --- | | 功能 JSON | <https://stormy.ai/api/v1/capabilities> | | OpenAPI | <https://stormy.ai/openapi.json> | | `llms.txt` | <https://stormy.ai/llms.txt> | | 人类文档 | <https://stormy.ai/docs> | --- ## 定价 一分钱是一个信用点。 **您仅需为成功的结果付费** — 验证邮箱查找如果找不到任何内容则费用为 `$0.00`。 | 操作 | 价格 | 何时适用 | | --- | --- | --- | | 缓存结果 | **$0.01** | `/search` 或 `/profile` 中的 `fresh=false` | | 新鲜档案 | **$0.05** | `/profile` 且 `fresh=true` | | 新鲜发现 | **$0.08** | `/search` 且 `fresh=true` 返回的每个匹配人员 | | 验证邮箱 | **$0.15** | `/emails` 找到的每个实际邮箱 | - **免费预览:** 每天 50 个缓存结果, 滚动 30 天内。 无新鲜数据, 无邮箱。 - **付费:** $50/月, 包括 $25 (2,500 个积分) 的用量。 超出部分按上述费率计量。 示例工作 (直接来自 `GET /pricing`): | 工作量 | 费用 | | --- | --- | | 100 缓存档案 | $1.00 | | 100 新鲜档案 | $5.00 | | 100 个新鲜匹配人员 | $8.00 | | 100 个验证邮箱 | $15.00 | | 100 个新鲜人员 **+** 他们的验证邮箱 | $23.00 | 在花费之前请提问 — `estimate_price` / `GET /pricing` 是免费的: ```bash curl 'https://stormy.ai/api/v1/pricing?quantity=250&include_email=true' ``` --- ## 错误和重试 | 状态 | 代码 | 操作 | | --- | --- | --- | | `400` | `invalid_request` | 修正正文. 不支持的平台, 空查询, `limit` 超出 1–100, 超过 25 个电子邮件目标 | | `401` | `invalid_token` | 密钥丢失, 过期, 被撤销或错误 | | `402` | `upgrade_required` | 返回给用户的 `upgrade_url` | | `402` | `insufficient_balance` | `POST /account/top-up` 配合 `error.recommended_topup_usd`, 返回 `checkout_url`, 轮询 `GET /account` | | `404` | `job_not_found` | 作业丢失或由另一个帐户拥有 | | `429` | `rate_limit` | 等待 `Retry-After` 秒。 **不要** 立即重试 | | `429` | 提供者冷却 | 共享上游池正在冷却 — 切换到持久作业 | | `503` | `provider_not_configured` | 我们部署的问题, 不是您的请求。 稍后重试 | 持久作业永远不会因速率限制而失败: 它们会移动到 `throttled` **而不消耗尝试次数**, 并在冷却后恢复。 作业状态为 `queued`, `scheduled`, `running`, `throttled`, `retrying`, `succeeded`, `failed`, `cancelled`。 仅在 `poll_after_seconds` 后轮询, 并在 `terminal` 为 `true` 时停止。 完整的处理示例如 [配方 10](recipes/10-errors-rate-limits-and-billing.md). --- ## 隐私和范围 - Stormy 只返回 **公共社交数据**。 - `search` 和 `profile` 响应递归剥离 `email`, `business_email`, `contact_email`, `phone` 和 `phone_number` 在 API 边界处。 此功能在服务器端强制执行, 而不是按约定。 - `POST /emails` 是唯一获取联系人数据的路径, 它是选择加入的, 仅限于 Instagram / TikTok / YouTube, 并且仅在找到有效邮箱时计费。 - 代理应仅在用户明确要求联系人详细信息时调用它。 --- ## 常见问题 <details> <summary><b>是否有TikTok API可以从AI代理调用？</b></summary> 是的，可以使用 `POST /api/v1/search` 并设置 `"platform": "tiktok"`，或者使用 `search_people` MCP 工具。你可以通过此方式进行创作者搜索、@handle → 个人资料解析、视频浏览量/点赞数/分享数/保存数/音乐/标签等，并支持验证邮箱增强。参见[示例01](recipes/01-find-influencers-by-niche.md)。 </details> <details> <summary><b>是否可以无需爬虫获取LinkedIn个人资料和帖子数据？</b></summary> 是的。在 `/search` 和 `/profile` 中使用 `platform: "linkedin"` 可以返回标题、粉丝数、发帖频率、平均点赞数/评论数/转发数、最高帖子以及AI总结；`include_posts` 还可以添加帖子并附带完整的互动数据。但LinkedIn不支持`/emails`。 </details> <details> <summary><b>是否有Reddit API用于主题监听？</b></summary> 是的。使用 `platform: "reddit"` 可以搜索子版块的帖子，并返回 `score`、`upvote_ratio`、`comments_count`、`permalink` 和作者积分等信息。参见[示例07](recipes/07-reddit-topic-listening.md)。 </details> <details> <summary><b>哪些平台支持影响者邮箱查找？</b></summary> Instagram、TikTok 和 YouTube。每个请求最多可查询 1-25 个目标。实际找到的每个邮箱收取 `$0.15`；未找到的不收费。X、LinkedIn 和 Reddit 仅支持搜索和个人资料查询。 </details> <details> <summary><b>是否需要六个API密钥？</b></summary> 不需要。一个 `STORMY_API_KEY` 即可涵盖 Instagram、YouTube、TikTok、X、LinkedIn 和 Reddit，支持 REST 和 MCP 接口，统一计费和结算。 </details> <details> <summary><b>MCP和REST有什么区别？</b></summary> 在功能上无区别，它们是同一服务的两种接口形式，享有相同的权限、计费标准和结算方式。MCP适用于运行时自动发现工具的代理，而REST适用于自定义代码开发。你可以混合使用它们；通过REST启动的任务在MCP中可见，反之亦然。 </details> <details> <summary><b>如何避免请求超时时重复扣费？</b></summary> 在请求中发送一个稳定的 `Idempotency-Key` 头部（REST）或 `idempotency_key` 参数（MCP任务），并确保该值基于用户的意图生成。重复使用相同的密钥将返回原始结果并仅收取一次费用。 </details> --- ## 贡献 欢迎提交新的示例、修复和语言支持。阅读 [CONTRIBUTING.md](CONTRIBUTING.md) 了解更多详情：每个文件一个示例、所有代码片段必须可运行、无自定义参数、严禁提交密钥。 ## 许可 [MIT](LICENSE)。您可以自由将这些示例应用到生产环境中。 --- <p align="center"> _{由 <a href="https://stormy.ai">Stormy</a> 构建 · <a href="https://stormy.ai/docs">文档</a> · <a href="https://stormy.ai/api/v1/capabilities">功能</a> · <a href="mailto:founders@stormy.ai">联系我们</a>} </p>