探索覆盖 Instagram、TikTok、YouTube 和 Facebook 的公开社交数据 API
SocQSocQ
统一 API社交媒体 API开发指南

统一社交媒体 API：一个 API 接入 7 个平台

用一个 API Key、统一任务模型和标准化 schema 采集 TikTok、Instagram、YouTube、Facebook、X、LinkedIn 与 Reddit 公开数据。

SocQ更新于 2026年7月19日阅读约 7 分钟

给产品增加第二个社交平台，工作量通常不只是翻倍。每个平台都有不同的认证方式、资源名称、响应结构、分页、错误类型和维护节奏。七套独立集成最终可能变成七套独立系统。

SocQ Social Media API 使用一个 API Key、一套异步任务流程和标准化记录模型，提供 TikTok、Instagram、YouTube、Facebook、X、LinkedIn 与 Reddit 的公开数据。当前目录在七个平台上共有 32 个专用端点。

**快速答案：**按资源要求向 POST /v1/{platform}/{resource} 提交输入，持久化任务 ID，再轮询统一任务端点。记录共享平台、资源、身份、作者、指标、媒体和时间字段约定，同时通过明确字段与 extra 保留平台特有信息。

什么是统一社交媒体 API？

统一 API 是多个平台集成之上的抽象层。应用不需要学习七套认证和七种不兼容响应，而是接入共享契约，通过路由选择平台与资源。

“统一”不应该意味着“假装所有平台完全相同”。LinkedIn 职位不是 TikTok 视频，Subreddit 不是 Instagram 资料，YouTube transcript 在 Facebook 也没有等价物。合理的统一模型只标准化真正共同的概念，并保留来源差异。

公开数据 API 与授权账号 API

搜索“Unified Social Media API”会看到两类不同产品。

授权账号 API 通过 OAuth 连接用户账号，用于发布、排期、管理评论或消息，以及读取私有账号 insights，适合社媒管理软件。

公开数据 API 采集受支持的公开可见资源，用于研究、监控、分析或 enrichment。SocQ 属于第二类：当前端点不能发帖、发送 DM、管理广告，也不能替代官方 API 的授权账号操作。

很多产品会同时需要两类能力：写入与许可数据使用官方或连接账号 API，受支持的外部公开来源使用公开数据层。

七个平台和 32 个端点

SocQ 当前目录：

平台可用资源常见输入
TikTok资料、视频、评论、搜索、标签用户名、URL、查询、标签
Instagram帖子、评论、粉丝数、Reels、搜索URL、用户名、查询
YouTube频道、视频、频道视频、评论、Shorts、搜索、字幕URL、handle、查询
FacebookPage、帖子、评论公开 URL
X/Twitter资料、已知 Post、用户 Post、搜索用户名、URL、查询
LinkedIn个人资料、公司、帖子、职位公开实体 URL
Reddit帖子、评论、Subreddit 帖子、搜索URL、Subreddit、查询

覆盖深度比平台 Logo 更重要。应在 API 目录中确认每个资源接受的输入和返回字段。

一套认证与任务模式

当前社媒端点统一使用 Bearer 认证：

Authorization: Bearer $SOCQ_API_KEY
Content-Type: application/json

资源创建遵循可预测路由：

POST /v1/{platform}/{resource}

例如：

POST /v1/tiktok/profiles
POST /v1/instagram/reels
POST /v1/youtube/transcripts
POST /v1/facebook/comments
POST /v1/x/search
POST /v1/linkedin/jobs
POST /v1/reddit/subreddit-posts

输入仍然由资源决定：资料可能接受用户名，已知实体需要 URL，搜索端点使用查询和受支持过滤条件。统一 API 应统一运营方式，而不是把无效输入强塞进一个通用 body。

统一异步工作流

耗时采集不应一直占用 HTTP 连接。SocQ 会创建任务：

客户端
  └─ POST 平台资源
       └─ task_id
            └─ 轮询统一任务端点
                 ├─ queued
                 ├─ running
                 ├─ succeeded → 分页记录
                 └─ failed/cancelled → 标准化错误

轮询前持久化任务 ID，使用指数退避，把 queued 和 running 当作正常状态，只在成功后处理记录，并在结果还有更多页时继续。

同一状态机允许一个 Worker 编排七个平台：

def submit(platform, resource, payload):
    return post(f"/v1/{platform}/{resource}", json=payload)["data"]["task_id"]

def wait_for_task(task_id):
    while True:
        task = get(f"/v1/tasks/{task_id}")["data"]
        if task["status"] == "succeeded":
            return task
        if task["status"] in {"failed", "cancelled"}:
            raise CollectionError(task)
        backoff()

生产代码还应持久化 cursor、限制重试、分类错误，并保证下游写入幂等。

标准化记录模型

适用时，记录采用共同约定：

{
  "id": "source-id",
  "platform": "tiktok",
  "resource": "videos",
  "type": "video",
  "url": "https://source.example/item",
  "author": {
    "id": "author-id",
    "username": "creator",
    "name": "Creator"
  },
  "metrics": {
    "likes_count": 120,
    "comments_count": 8
  },
  "media": [],
  "created_at": "2026-07-18T08:00:00Z",
  "collected_at": "2026-07-19T08:00:00Z",
  "extra": {}
}

不是每种资源都有全部字段。资料可能有 name、description 和 avatar_url；帖子使用 text；视频可以有时长或音频；职位包含雇佣信息。可选字段应为 nullable，需要平台特有逻辑时按 resource 或 type 分支。

哪些部分可以统一？

认证

一个 SocQ API Key 可以认证整个目录的请求。

任务生命周期

提交、轮询、终态、分页和任务可观测性可以共用一套 Worker。

来源追踪

每条存储记录都应保留 platform、resource、来源 URL、采集时间和任务 ID。

共同实体

来源存在时，ID、URL、作者、公开指标、媒体引用、发布时间和采集时间可以使用统一约定。

错误处理

应用可以将输入错误、公开资源不可用、瞬时上游故障、限流和终态失败映射到内部统一分类。

哪些部分不应强行统一？

指标不能直接互换

TikTok play、Instagram view、YouTube view、X impression、Reddit score 和 LinkedIn reaction 的定义与可用性不同。应保留原始指标名，而不是制造一个误导性的 engagement 数字。

资源深度不同

YouTube 有 transcript 和频道，LinkedIn 有职位和公司，Reddit 有 Subreddit，TikTok 有标签。覆盖矩阵应显示差异，而不是隐藏差异。

发现语义不同

搜索排序、历史范围、本地化、结果上限和新鲜度随平台变化。相同查询的跨平台结果不是严格可比测量。

访问和可见性不同

公开可用性、删除内容、私密账号、年龄或地区限制、登录后视图都由平台决定。统一 API 不代表访问控制消失。

多平台请求示例

采集 TikTok 资料：

curl -X POST "https://api.socq.ai/v1/tiktok/profiles" \
  -H "Authorization: Bearer $SOCQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"usernames":["tiktok","natgeo"]}'

采集 Instagram Reels：

curl -X POST "https://api.socq.ai/v1/instagram/reels" \
  -H "Authorization: Bearer $SOCQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"usernames":["instagram"],"results_limit":50}'

采集 YouTube 字幕：

curl -X POST "https://api.socq.ai/v1/youtube/transcripts" \
  -H "Authorization: Bearer $SOCQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"urls":["https://www.youtube.com/watch?v=VIDEO_ID"]}'

搜索 Reddit：

curl -X POST "https://api.socq.ai/v1/reddit/search" \
  -H "Authorization: Bearer $SOCQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"developer tools","results_limit":100}'

认证和任务流程不变，只有合法资源输入不同。

TypeScript 客户端模式

使用判别请求类型，不要使用无类型通用 payload：

type RequestMap = {
  "tiktok/profiles": { usernames: string[] };
  "instagram/reels": { usernames: string[]; results_limit?: number };
  "youtube/transcripts": { urls: string[] };
  "facebook/comments": { urls: string[] };
  "x/search": { query: string; limit?: number; sort?: "latest" | "top" };
  "linkedin/jobs": { urls: string[] };
  "reddit/search": { query: string; results_limit?: number };
};

async function submit<K extends keyof RequestMap>(
  endpoint: K,
  payload: RequestMap[K],
) {
  const response = await fetch(`https://api.socq.ai/v1/${endpoint}`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.SOCQ_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify(payload),
  });

  if (!response.ok) throw new Error(`SocQ ${response.status}`);
  return response.json();
}

应从内部端点注册表生成或维护这些类型，避免文档、校验和客户端分别漂移。

数据库设计

实用的数据仓库可以使用共同 envelope 加资源表：

social_record
  platform
  resource
  source_id
  canonical_url
  author_id
  created_at
  collected_at
  source_task_id
  raw_json

social_metric_snapshot
  platform
  resource
  source_id
  collected_at
  metric_name
  metric_value

resource-specific tables
  transcript_segments
  job_details
  profile_attributes
  media_metadata

不要把所有平台字段塞进一张 200 列的表。保留标准 envelope，再用类型化资源表或通过校验的 JSON 保存来源深度。

错误标准化与重试

分开处理：

  • 永远不会成功的输入错误；
  • 不支持或不可用的公开资源；
  • 认证与账户错误；
  • 速率或 credit 限制；
  • 瞬时上游故障；
  • 供应商 bug 或 schema 校验失败。

只重试瞬时错误，使用带抖动的有界指数退避。记录尝试和任务 ID，并保证 upsert 幂等，使重试不会产生重复记录。

统一 API 与七套原生 API

决策因素统一公开数据 API平台原生 API
接入一套认证和任务模式每个平台不同
Schema标准化核心平台原生对象
维护供应商吸收许多来源变化团队跟进每个平台
外部公开数据受支持资源覆盖常受产品和权限限制
发布和账号操作SocQ 不提供必须使用官方 API
平台专用深度受目录限制获得审批时通常最强
治理一个供应商加来源义务直接平台关系

这不是全有或全无的选择。写入、自有 analytics 和许可工作流使用原生 API；访问模型合适时，受支持的公开读取使用统一公开数据 API。

常见使用场景

  • 跨网络品牌和话题监控；
  • Influencer 与创作者研究；
  • 竞争内容分析；
  • AI Agent 研究工具；
  • 社交搜索与发现；
  • 评论、帖子、视频和字幕数据集；
  • 配合适当保障的公开资料或公司 enrichment。

数据管道应围绕业务所需的最小数据设计，而不是来源可能暴露的全部字段。

哪些情况不适合？

以下情况不要使用 SocQ：

  • 需要发布、回复、发送 DM 或管理广告；
  • 需要用户授权的私有账号 insights；
  • 必须使用官方合作伙伴计划；
  • 依赖目录中不存在的单平台专有功能；
  • 法律、合同或治理要求不允许拟议采集。

正确答案可能是官方 API、连接账号供应商、授权数据集，或者不采集。

从一个平台迁移到七个平台

  1. 添加来源前先定义内部标准 envelope。
  2. 接入一个高价值资源并保留原始响应。
  3. 校验 ID、时间、指标、媒体和 null。
  4. 通过同一任务 Worker 添加第二个平台。
  5. 在校验边界保留来源专用 adapter。
  6. 用固定样本并行运行新旧管道。
  7. 比较有效唯一记录、新鲜度和成本。
  8. 逐步迁移并保留回滚路径。

只有数据语义、可观测性和失败处理真正标准化后，新增平台才会变成配置工作。

安全、隐私与负责任使用

把 API Key 保存在 secret manager，按最小权限访问数据，加密传输和存储，记录管理访问，并制定保留与删除流程。

只采集合法目的所需的受支持公开数据。不要绕过私密账号、登录屏障、受众控制或其他限制。审查平台条款、隐私义务、知识产权规则与适用法律。统一技术接口不会统一或消除法律义务。

常见问题

统一社交媒体 API 会取代官方 API 吗？

不会。SocQ 处理受支持的公开读取；发布、OAuth 用户操作、私有 insights 和平台合作伙伴产品仍需要官方 API。

七个平台返回完全相同字段吗？

不会。概念匹配时采用标准约定，资源特有字段仍然分开。

需要七个 API Key 吗？

一个 SocQ Key 覆盖 SocQ 目录；官方或其他供应商集成仍需要自己的凭据。

SocQ 可以发布社媒帖子吗？

不可以。当前端点是只读公开数据操作。

如何处理限流？

应用应遵守 SocQ 账户限制，持久化异步任务状态，轮询时退避，并且只重试瞬时错误。

适合 AI Agent 吗？

适合，但 Agent 应使用类型化工具、受限输入、任务状态持久化和结果校验；有后果的下游操作还需要人工批准。

支持哪七个平台？

TikTok、Instagram、YouTube、Facebook、X/Twitter、LinkedIn 和 Reddit。

多平台 API

使用公开的 多平台 输入测试工作流

提交公开输入，获取带有可追溯来源上下文的标准化记录。

查看 多平台 API