核心概念

贯穿 Skills、MCP 操作、公开数据 API、数据结构和分页的术语词汇。

有几个词会在 UnifAPI 中随处出现。把它们学一遍，文档其余部分读起来就会更快。

Skill

智能体可以借助 UnifAPI MCP 运行的、面向特定任务的工作流。一个 Skill 从期望的输出出发，例如一份 KOL 报价简报或一份创作者候选名单，然后让智能体在需要证据时发现并调用公开数据操作。

Skills 是面向智能体用户的推荐起点。API 参考是它们背后的数据层。

Provider（提供方）

某个 API 从中暴露数据的公开平台——例如 TikTok、Twitter/X、LinkedIn、YouTube、Reddit 或 Instagram。每个提供方都有一个顶层路径前缀。

https://api.unifapi.com/tiktok/...

Operation（操作）

提供方内部的单个可调用公开数据端点——例如 GET /tiktok/videos/{id}。每个操作在 API 参考中都有自己的页面，MCP 通过 list_operations 和 get_operation 暴露操作发现机制。

规范数据结构

每个返回同类资源（一个 Video、一个 User、一个 Comment）的操作都使用相同的规范数据结构。因此 GET /tiktok/videos/{id} 和 GET /tiktok/users/{id}/videos 都返回字段名和类型完全一致的 Video 对象。

这些规范的数据结构存放在 OpenAPI 规范的 components.schemas 中，包括：Video、Author、Music、MusicDetail、Comment、User、Hashtag、LiveRoom。

标识符

ID 是 不透明字符串。它们看起来像长数字，但请将其当作字符串处理以保留精度（有些大于 2^53）。

TikTok 用户 id（sec_uid）是一个很长的 base64 令牌，例如 MS4wLjABAAAA...。
TikTok 视频、音乐和话题标签的 id 是看起来像数字的字符串。TikTok 用户端点在支持的情况下接受公开 handle、数字用户 id 或 sec_uid。

使用 /tiktok/users/resolve?username=jennmelon 将用户名解析为稳定的用户 id。使用 /tiktok/videos/resolve?url=... 将分享 URL 解析为视频。

公开响应信封

成功的响应使用相同的顶层信封：

{
  "request_id": "req_...",
  "data": {
    /* resource or list payload */
  },
  "pagination": {
    "cursor": "1711494099000",
    "has_more": true
  },
  "billing": {
    "credits_charged": 10,
    "records_charged": 10,
    "balance_remaining": 90,
    "truncated_due_to_balance": false
  }
}

request_id — 用于支持和追踪的 UnifAPI 请求 id。
data — 业务负载。
pagination — 当列表操作可以继续时出现。
billing — 本次调用所扣的 credits 和记录数。

分页

pagination.has_more — 当至少还存在一页时为 true。
pagination.cursor — 不透明字符串，作为 ?cursor= 传回以获取下一页。当 has_more 为 false 时为 null。

limit 查询参数上限为 50。

游标是有意设计为不透明的：有些来源使用整数偏移量，有些使用时间戳，有些使用页令牌。UnifAPI 隐藏了这些差异。不要尝试解析 pagination.cursor。

错误信封

所有错误共享同一个嵌套信封：

{
  "error": {
    "type": "...",
    "message": "...",
    "request_id": "...",
    "issues": [
      /* validation only */
    ]
  }
}

error.type 是一个封闭词汇表（validation_error、not_found、unauthorized ...）。参见错误。

Workspace（工作区）

计费和访问的边界。OAuth MCP 会话、API key、用量和发票都存在于工作区层级。从仪表盘邀请团队成员——他们共享同一批 key 和用量计数器。

公开数据边界

UnifAPI 提供公开数据。OAuth 授权的是 UnifAPI MCP 访问和工作区 credits；它不授权访问私有来源账户。如果工作流需要用户的私有 SaaS 数据，请将 UnifAPI 与连接器平台搭配使用，而不要把 UnifAPI 当作那个 OAuth 集成层。

本页内容