# 返回格式

不管哪个平台，SocialToAI 的每个调用都返回同一种结构：外层说明调了什么、结果如何、扣了多少，里面是一个对象列表。对象有 28 种，每种在所有平台上字段相同。平台给不了的字段是 null，不会缺失。

- 页面：https://socialtoai.com/zh/docs/api/response/
- 最近更新：2026-10-17

## 外层结构

`schema_version` 是 `v1`。客户端应当忽略不认识的字段和代码。

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `request_id` | string | 这次调用的编号，报告问题时带上它。 |
| `schema_version` | "v1" | 固定是 "v1"。 |
| `fetched_at` | string | 从平台取到数据的时间，ISO 8601（UTC）。 |
| `action` | string | 执行的动作。 |
| `op` | string | 执行的平台独有接口，只在 call 时出现。（可能不出现） |
| `platform` | string | 这份结果来自哪个平台。 |
| `target` | string | 这份结果对应哪个目标，照你写的原样给出；请求里给了多个目标时才有。（可能不出现） |
| `status` | "ok" \| "empty" \| "error" \| "not_supported" \| "timeout" \| "skipped" | ok、empty、error、not_supported、timeout 或 skipped。 |
| `reason` | string | 这份结果为什么被跳过；status 为 skipped 时才有。（可能不出现） |
| `unavailable` | string[] | 这个平台给不了的字段路径，这些字段在每一条里都是 null。 |
| `page.has_more` | boolean | 后面还有下一页时为 true。（可能不出现） |
| `page.cursor` | string | 原样填进 cursor 取下一页；最后一页没有它。（可能不出现） |
| `page.cursor_expires_at` | string | cursor 的失效时间，ISO 8601（UTC）。（可能不出现） |
| `warnings` | array | 不影响成功、但值得知道的提示。 |
| `applied_params` | object | 实际生效的参数。 |
| `includes` | object | 用 include 要的附加部分，按名字列出：各有自己的 status 和 cost_credits，取到的字段已经填进每一条。（可能不出现） |
| `cost_credits` | integer | 这份结果扣了多少积分；失败时为 0。 |
| `billing.cost_credits` | integer | 整个请求扣了多少积分。 |
| `billing.balance_credits` | integer | 扣完之后的余额。 |
| `billing.today_spend_credits` | integer | 今天（UTC）已经花掉的积分。 |
| `billing.daily_limit_credits` | integer \| null | 每日上限；没设时为 null。 |
| `billing.daily_remaining_credits` | integer \| null | 每日上限还剩多少；没设时为 null。 |
| `billing.display` | string | 一句可以直接复述给你的话。 |
| `replayed` | boolean | 同一个幂等键重放已有结果时为 true，本次不扣。 |
| `replayed_cost_credits` | integer | 第一次返回时扣了多少积分；replayed 为 true 时才有。（可能不出现） |
| `empty_reason` | "no_match" \| "filtered" | 为什么是空的：no_match（没有匹配），或 filtered（被你设的条件筛掉）。status 为 empty 时才有。（可能不出现） |

## 状态

| status | 扣费 | 含义 |
| --- | --- | --- |
| `ok` | 扣 | 调用成功，结果在 `items` 里。 |
| `empty` | 扣 | 调用成功，但没有结果。搜索正常执行、只是没搜到，照常扣费。 |
| `error` | 不扣 | 调用失败。`error` 说明原因，`fix` 说明怎么办。 |
| `not_supported` | 不扣 | 这个平台没有这个动作。 |
| `timeout` | 不扣 | 结果不确定。我们不会自动重试。 |
| `skipped` | 不扣 | 这一部分没有执行。 |

## 对象

每个对象用 `type` 说明自己是什么。时间是 ISO 8601（UTC）。评论的作者一律匿名：评论带一个匿名标记，在同一次返回里保持一致。

### `content` (帖子、视频、笔记或文章)

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `platform` | string | 这一条来自哪个平台。 |
| `id` | string \| null | 平台自己的编号。 |
| `ref` | string \| null | 可以原样填回请求里、指向这一条的值。 |
| `approx` | array | 这一条里哪些数字是约数或下限；都精确时为空。 |
| `type` | "content" | 对象类型。 |
| `url` | string \| null | 能直接打开的链接。 |
| `format` | "video" \| "image" \| "text" \| "article" \| null | video、image、text 或 article。 |
| `title` | string \| null | 标题。 |
| `text` | string \| null | 正文或文案。 |
| `published_at` | string \| null | 发布时间，ISO 8601（UTC）。 |
| `author.id` | string \| null | 作者的账号编号。 |
| `author.username` | string \| null | 作者的账号名。 |
| `author.name` | string \| null | 作者的显示名。 |
| `author.verified` | boolean \| null | 作者是否认证。 |
| `author.followers` | integer \| null | 作者的粉丝数。 |
| `metrics.likes` | integer \| null | 点赞数。 |
| `metrics.comments` | integer \| null | 评论数。 |
| `metrics.shares` | integer \| null | 分享数。 |
| `metrics.collects` | integer \| null | 收藏数。 |
| `metrics.views` | integer \| null | 播放或阅读数。 |
| `metrics.reposts` | integer \| null | 转发数。 |
| `images` | string[] \| null | 图片地址。 |
| `hashtags` | string[] \| null | 话题标签，不带 #。 |
| `is_pinned` | boolean \| null | 是否被作者置顶。 |

### `account` (账号)

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `platform` | string | 这一条来自哪个平台。 |
| `id` | string \| null | 平台自己的编号。 |
| `ref` | string \| null | 可以原样填回请求里、指向这一条的值。 |
| `approx` | array | 这一条里哪些数字是约数或下限；都精确时为空。 |
| `type` | "account" | 对象类型。 |
| `username` | string \| null | 账号名。 |
| `name` | string \| null | 显示名。 |
| `url` | string \| null | 主页链接。 |
| `bio` | string \| null | 简介。 |
| `verified` | boolean \| null | 是否认证。 |
| `followers` | integer \| null | 粉丝数。 |
| `following` | integer \| null | 关注数。 |
| `posts_count` | integer \| null | 发布的内容数。 |

### `comment` (评论)

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `platform` | string | 这一条来自哪个平台。 |
| `id` | string \| null | 平台自己的编号。 |
| `ref` | string \| null | 可以原样填回请求里、指向这一条的值。 |
| `approx` | array | 这一条里哪些数字是约数或下限；都精确时为空。 |
| `type` | "comment" | 对象类型。 |
| `url` | string \| null | 评论的链接，平台有才给。 |
| `text` | string \| null | 评论原文。 |
| `published_at` | string \| null | 发布时间，ISO 8601（UTC）。 |
| `author.label` | string | 匿名标记，在同一次返回里保持一致；写的人不具名。 |
| `metrics.likes` | integer \| null | 点赞数。 |
| `reply_count` | integer \| null | 回复数。 |
| `content_id` | string \| null | 评论所在内容的编号。 |
| `parent_id` | string \| null | 它直接回复的那条评论；一级评论为 null。 |
| `root_id` | string \| null | 所在回复串的一级评论。 |

### `entry:trend`

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `platform` | string | 这一条来自哪个平台。 |
| `id` | string \| null | 平台自己的编号。 |
| `ref` | string \| null | 可以原样填回请求里、指向这一条的值。 |
| `approx` | array | 这一条里哪些数字是约数或下限；都精确时为空。 |
| `type` | "entry" | 对象类型。 |
| `entry_type` | "trend" | 条目的种类。 |
| `title` | string \| null | 条目的标题或名称。 |
| `url` | string \| null | 能打开它的链接；平台的列表不带链接时为 null。 |
| `rank` | integer \| null | 榜上的名次，从 1 起。 |
| `heat` | integer \| null | 平台给的热度值。 |
| `fields` | object | 热榜条目没有额外字段。 |

### `entry:transcript`

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `platform` | string | 这一条来自哪个平台。 |
| `id` | string \| null | 平台自己的编号。 |
| `ref` | string \| null | 可以原样填回请求里、指向这一条的值。 |
| `approx` | array | 这一条里哪些数字是约数或下限；都精确时为空。 |
| `type` | "entry" | 对象类型。 |
| `entry_type` | "transcript" | 条目的种类。 |
| `title` | string \| null | 条目的标题或名称。 |
| `url` | string \| null | 能打开它的链接；平台的列表不带链接时为 null。 |
| `rank` | integer \| null | 榜上的名次，从 1 起。 |
| `heat` | integer \| null | 平台给的热度值。 |
| `fields.lang` | string \| null | 逐字稿的语言。 |
| `fields.text` | string \| null | 全文。 |
| `fields.segments` | array \| null | 带时间的分段：start、end、text。 |

### `entry:creator_rates`

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `platform` | string | 这一条来自哪个平台。 |
| `id` | string \| null | 平台自己的编号。 |
| `ref` | string \| null | 可以原样填回请求里、指向这一条的值。 |
| `approx` | array | 这一条里哪些数字是约数或下限；都精确时为空。 |
| `type` | "entry" | 对象类型。 |
| `entry_type` | "creator_rates" | 条目的种类。 |
| `title` | string \| null | 条目的标题或名称。 |
| `url` | string \| null | 能打开它的链接；平台的列表不带链接时为 null。 |
| `rank` | integer \| null | 榜上的名次，从 1 起。 |
| `heat` | integer \| null | 平台给的热度值。 |
| `fields.currency` | string \| null | 金额的币种。 |
| `fields.rates` | array \| null | 达人的报价：名称、金额、结算方式、是否开放。 |

### `entry:community`

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `platform` | string | 这一条来自哪个平台。 |
| `id` | string \| null | 平台自己的编号。 |
| `ref` | string \| null | 可以原样填回请求里、指向这一条的值。 |
| `approx` | array | 这一条里哪些数字是约数或下限；都精确时为空。 |
| `type` | "entry" | 对象类型。 |
| `entry_type` | "community" | 条目的种类。 |
| `title` | string \| null | 条目的标题或名称。 |
| `url` | string \| null | 能打开它的链接；平台的列表不带链接时为 null。 |
| `rank` | integer \| null | 榜上的名次，从 1 起。 |
| `heat` | integer \| null | 平台给的热度值。 |
| `fields.description` | string \| null | 社区简介。 |
| `fields.nsfw` | boolean \| null | 是否标为成人内容。 |
| `fields.created_at` | string \| null | 创建时间，ISO 8601（UTC）。 |
| `fields.members` | integer \| null | 成员数。 |

### `entry:product`

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `platform` | string | 这一条来自哪个平台。 |
| `id` | string \| null | 平台自己的编号。 |
| `ref` | string \| null | 可以原样填回请求里、指向这一条的值。 |
| `approx` | array | 这一条里哪些数字是约数或下限；都精确时为空。 |
| `type` | "entry" | 对象类型。 |
| `entry_type` | "product" | 条目的种类。 |
| `title` | string \| null | 条目的标题或名称。 |
| `url` | string \| null | 能打开它的链接；平台的列表不带链接时为 null。 |
| `rank` | integer \| null | 榜上的名次，从 1 起。 |
| `heat` | integer \| null | 平台给的热度值。 |
| `fields.description` | string \| null | 商品描述。 |
| `fields.price` | string \| null | 现价，十进制字符串，币种见 fields.currency。 |
| `fields.original_price` | string \| null | 折前价。 |
| `fields.currency` | string \| null | 价格的币种。 |
| `fields.images` | string[] \| null | 图片地址。 |
| `fields.rating` | number \| null | 评分。 |
| `fields.sold` | integer \| null | 销量。 |
| `fields.reviews_count` | integer \| null | 评价数。 |
| `fields.shop.id` | string \| null | 店铺编号。 |
| `fields.shop.name` | string \| null | 店铺名称。 |

### `entry:review`

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `platform` | string | 这一条来自哪个平台。 |
| `id` | string \| null | 平台自己的编号。 |
| `ref` | string \| null | 可以原样填回请求里、指向这一条的值。 |
| `approx` | array | 这一条里哪些数字是约数或下限；都精确时为空。 |
| `type` | "entry" | 对象类型。 |
| `entry_type` | "review" | 条目的种类。 |
| `title` | string \| null | 条目的标题或名称。 |
| `url` | string \| null | 能打开它的链接；平台的列表不带链接时为 null。 |
| `rank` | integer \| null | 榜上的名次，从 1 起。 |
| `heat` | integer \| null | 平台给的热度值。 |
| `fields.product_id` | string \| null | 评价所属的商品。 |
| `fields.text` | string \| null | 评价原文。 |
| `fields.rating` | number \| null | 给出的评分。 |
| `fields.published_at` | string \| null | 发布时间，ISO 8601（UTC）。 |
| `fields.author.label` | string | 匿名标记，在同一次返回里保持一致；写的人不具名。 |
| `fields.images` | string[] \| null | 图片地址。 |
| `fields.variant` | string \| null | 购买的规格。 |

### `entry:keyword_history`

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `platform` | string | 这一条来自哪个平台。 |
| `id` | string \| null | 平台自己的编号。 |
| `ref` | string \| null | 可以原样填回请求里、指向这一条的值。 |
| `approx` | array | 这一条里哪些数字是约数或下限；都精确时为空。 |
| `type` | "entry" | 对象类型。 |
| `entry_type` | "keyword_history" | 条目的种类。 |
| `title` | string \| null | 条目的标题或名称。 |
| `url` | string \| null | 能打开它的链接；平台的列表不带链接时为 null。 |
| `rank` | integer \| null | 榜上的名次，从 1 起。 |
| `heat` | integer \| null | 平台给的热度值。 |
| `fields.points` | array \| null | 逐日数据，每天一项，按日期从早到晚：date、search_index、composite_index、notes、impressions、views、engagements。 |

### `entry:keyword_related`

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `platform` | string | 这一条来自哪个平台。 |
| `id` | string \| null | 平台自己的编号。 |
| `ref` | string \| null | 可以原样填回请求里、指向这一条的值。 |
| `approx` | array | 这一条里哪些数字是约数或下限；都精确时为空。 |
| `type` | "entry" | 对象类型。 |
| `entry_type` | "keyword_related" | 条目的种类。 |
| `title` | string \| null | 条目的标题或名称。 |
| `url` | string \| null | 能打开它的链接；平台的列表不带链接时为 null。 |
| `rank` | integer \| null | 榜上的名次，从 1 起。 |
| `heat` | integer \| null | 平台给的热度值。 |
| `fields.related_to` | string \| null | 你查的那个关键词。 |
| `fields.relation` | "query" \| "posts" \| "prior" \| "after" \| null | 关联方式：query 是和你查的词一起被搜，posts 是在内容里一起出现，prior 是人们搜它之前搜的词，after 是之后搜的词。 |
| `fields.relevance` | number \| null | 和你查的词的相关度，0 到 1。 |
| `fields.search_index` | integer \| null | 这个关联词的搜索指数：平台算出的指数，不是搜索次数；平台没给这个词的数值时为 null。 |
| `fields.composite_index` | integer \| null | 这个关联词的综合指数：平台按相关内容的热度算出的指数，不是次数。 |

### `entry:keyword_audience`

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `platform` | string | 这一条来自哪个平台。 |
| `id` | string \| null | 平台自己的编号。 |
| `ref` | string \| null | 可以原样填回请求里、指向这一条的值。 |
| `approx` | array | 这一条里哪些数字是约数或下限；都精确时为空。 |
| `type` | "entry" | 对象类型。 |
| `entry_type` | "keyword_audience" | 条目的种类。 |
| `title` | string \| null | 条目的标题或名称。 |
| `url` | string \| null | 能打开它的链接；平台的列表不带链接时为 null。 |
| `rank` | integer \| null | 榜上的名次，从 1 起。 |
| `heat` | integer \| null | 平台给的热度值。 |
| `fields.age` | array \| null | 按年龄段分：label、share、tgi。tgi 表示这个人群的偏好程度，100 为平均水平。 |
| `fields.gender` | array \| null | 按性别分：label、share、tgi。 |
| `fields.province` | array \| null | 按省份分：label、share、tgi。 |
| `fields.city` | array \| null | 按城市分，只列占比最高的一批，各项加起来不到 1：label、share、tgi。 |
| `fields.city_tier` | array \| null | 按城市等级分：label、share、tgi。 |
| `fields.interest` | array \| null | 按兴趣分。一个人可以有多个兴趣，各项加起来不等于 1：label、share、tgi。 |

### `entry:brand_history`

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `platform` | string | 这一条来自哪个平台。 |
| `id` | string \| null | 平台自己的编号。 |
| `ref` | string \| null | 可以原样填回请求里、指向这一条的值。 |
| `approx` | array | 这一条里哪些数字是约数或下限；都精确时为空。 |
| `type` | "entry" | 对象类型。 |
| `entry_type` | "brand_history" | 条目的种类。 |
| `title` | string \| null | 条目的标题或名称。 |
| `url` | string \| null | 能打开它的链接；平台的列表不带链接时为 null。 |
| `rank` | integer \| null | 榜上的名次，从 1 起。 |
| `heat` | integer \| null | 平台给的热度值。 |
| `fields.category` | string \| null | 平台给这个品牌归的行业，用平台的原话。 |
| `fields.points` | array \| null | 逐日指数，每天一项，按日期从早到晚：date、search_index、content_index、spread_index。 |

### `entry:brand_metrics`

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `platform` | string | 这一条来自哪个平台。 |
| `id` | string \| null | 平台自己的编号。 |
| `ref` | string \| null | 可以原样填回请求里、指向这一条的值。 |
| `approx` | array | 这一条里哪些数字是约数或下限；都精确时为空。 |
| `type` | "entry" | 对象类型。 |
| `entry_type` | "brand_metrics" | 条目的种类。 |
| `title` | string \| null | 条目的标题或名称。 |
| `url` | string \| null | 能打开它的链接；平台的列表不带链接时为 null。 |
| `rank` | integer \| null | 榜上的名次，从 1 起。 |
| `heat` | integer \| null | 平台给的热度值。 |
| `fields.category` | string \| null | 平台给这个品牌归的行业，用平台的原话。 |
| `fields.search_index` | integer \| null | 这段时间搜索指数的日均值。 |
| `fields.content_index` | integer \| null | 这段时间内容指数的日均值。 |
| `fields.spread_index` | integer \| null | 这段时间传播指数的日均值。 |
| `fields.benchmarks` | array \| null | 同行业的参照值：行业全部品牌的均值，和头部品牌的均值。每项有 scope、search_index、content_index、spread_index。 |

### `entry:account_history`

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `platform` | string | 这一条来自哪个平台。 |
| `id` | string \| null | 平台自己的编号。 |
| `ref` | string \| null | 可以原样填回请求里、指向这一条的值。 |
| `approx` | array | 这一条里哪些数字是约数或下限；都精确时为空。 |
| `type` | "entry" | 对象类型。 |
| `entry_type` | "account_history" | 条目的种类。 |
| `title` | string \| null | 条目的标题或名称。 |
| `url` | string \| null | 能打开它的链接；平台的列表不带链接时为 null。 |
| `rank` | integer \| null | 榜上的名次，从 1 起。 |
| `heat` | integer \| null | 平台给的热度值。 |
| `fields.days` | integer \| null | 统计的是最近多少天。 |
| `fields.gained.followers` | integer \| null | 净增粉丝数，掉粉时为负。 |
| `fields.gained.likes` | integer \| null | 新增点赞数。 |
| `fields.gained.comments` | integer \| null | 新增评论数。 |
| `fields.gained.shares` | integer \| null | 新增分享数。 |
| `fields.gained.posts` | integer \| null | 新发布的内容数。 |
| `fields.change.followers` | number \| null | 净增粉丝数相比上一个周期的变化比例。 |
| `fields.change.likes` | number \| null | 新增点赞数相比上一个周期的变化比例。 |
| `fields.change.comments` | number \| null | 新增评论数相比上一个周期的变化比例。 |
| `fields.change.shares` | number \| null | 新增分享数相比上一个周期的变化比例。 |
| `fields.change.posts` | number \| null | 新发布的内容数相比上一个周期的变化比例。 |
| `fields.totals.followers` | integer \| null | 现在的粉丝数。 |
| `fields.totals.likes` | integer \| null | 累计获赞数。 |
| `fields.totals.posts` | integer \| null | 累计作品数。 |

### `entry:index_creator_metrics`

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `platform` | string | 这一条来自哪个平台。 |
| `id` | string \| null | 平台自己的编号。 |
| `ref` | string \| null | 可以原样填回请求里、指向这一条的值。 |
| `approx` | array | 这一条里哪些数字是约数或下限；都精确时为空。 |
| `type` | "entry" | 对象类型。 |
| `entry_type` | "index_creator_metrics" | 条目的种类。 |
| `title` | string \| null | 条目的标题或名称。 |
| `url` | string \| null | 能打开它的链接；平台的列表不带链接时为 null。 |
| `rank` | integer \| null | 榜上的名次，从 1 起。 |
| `heat` | integer \| null | 平台给的热度值。 |
| `fields.average_7d.likes` | number \| null | 最近一周平均每天新增的点赞数。 |
| `fields.average_7d.followers` | number \| null | 最近一周平均每天新增的粉丝数。 |
| `fields.average_7d.shares` | number \| null | 最近一周平均每天新增的分享数。 |
| `fields.average_7d.comments` | number \| null | 最近一周平均每天新增的评论数。 |
| `fields.average_30d.likes` | number \| null | 最近一个月平均每天新增的点赞数。 |
| `fields.average_30d.followers` | number \| null | 最近一个月平均每天新增的粉丝数。 |
| `fields.average_30d.shares` | number \| null | 最近一个月平均每天新增的分享数。 |
| `fields.average_30d.comments` | number \| null | 最近一个月平均每天新增的评论数。 |
| `fields.change_7d.likes` | number \| null | 最近一周日均新增点赞数相比上一周的变化比例。 |
| `fields.change_7d.followers` | number \| null | 最近一周日均新增粉丝数相比上一周的变化比例。 |
| `fields.change_7d.shares` | number \| null | 最近一周日均新增分享数相比上一周的变化比例。 |
| `fields.change_7d.comments` | number \| null | 最近一周日均新增评论数相比上一周的变化比例。 |
| `fields.change_30d.likes` | number \| null | 最近一个月日均新增点赞数相比上一个月的变化比例。 |
| `fields.change_30d.followers` | number \| null | 最近一个月日均新增粉丝数相比上一个月的变化比例。 |
| `fields.change_30d.shares` | number \| null | 最近一个月日均新增分享数相比上一个月的变化比例。 |
| `fields.change_30d.comments` | number \| null | 最近一个月日均新增评论数相比上一个月的变化比例。 |

### `entry:creator`

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `platform` | string | 这一条来自哪个平台。 |
| `id` | string \| null | 平台自己的编号。 |
| `ref` | string \| null | 可以原样填回请求里、指向这一条的值。 |
| `approx` | array | 这一条里哪些数字是约数或下限；都精确时为空。 |
| `type` | "entry" | 对象类型。 |
| `entry_type` | "creator" | 条目的种类。 |
| `title` | string \| null | 条目的标题或名称。 |
| `url` | string \| null | 能打开它的链接；平台的列表不带链接时为 null。 |
| `rank` | integer \| null | 榜上的名次，从 1 起。 |
| `heat` | integer \| null | 平台给的热度值。 |
| `fields.account_id` | string \| null | 这位达人的平台账号编号，可以传给同平台的账号类调用。 |
| `fields.username` | string \| null | 账号名。 |
| `fields.location` | string \| null | 所在地，用平台的原话。 |
| `fields.categories` | string[] \| null | 内容类目（一级），用平台的原话。 |
| `fields.subcategories` | string[] \| null | 内容类目（二级），用平台的原话。 |
| `fields.followers` | integer \| null | 粉丝数。 |

### `entry:audience`

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `platform` | string | 这一条来自哪个平台。 |
| `id` | string \| null | 平台自己的编号。 |
| `ref` | string \| null | 可以原样填回请求里、指向这一条的值。 |
| `approx` | array | 这一条里哪些数字是约数或下限；都精确时为空。 |
| `type` | "entry" | 对象类型。 |
| `entry_type` | "audience" | 条目的种类。 |
| `title` | string \| null | 条目的标题或名称。 |
| `url` | string \| null | 能打开它的链接；平台的列表不带链接时为 null。 |
| `rank` | integer \| null | 榜上的名次，从 1 起。 |
| `heat` | integer \| null | 平台给的热度值。 |
| `fields.measured_at` | string \| null | 画像数据对应的日期，以北京时间当天零点表示。 |
| `fields.gender` | array \| null | 按性别分：name、share、count。 |
| `fields.age` | array \| null | 按年龄段分：name、share、count。 |
| `fields.province` | array \| null | 按省份分：name、share、count。 |
| `fields.city` | array \| null | 按城市分，只列粉丝最多的几个：name、share、count。 |
| `fields.interest` | array \| null | 按兴趣分：name、share、count。 |
| `fields.device` | array \| null | 按手机品牌分：name、share、count。 |
| `fields.city_tier` | array \| null | 按城市等级分：name、share、count。 |
| `fields.crowd` | array \| null | 按平台划分的消费人群分：name、share、count。 |
| `fields.purchase_category` | array \| null | 按购买的品类分：name、share、count。 |
| `fields.purchase_amount` | array \| null | 按每单消费金额分：name、share、count。 |

### `entry:xingtu_creator_metrics`

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `platform` | string | 这一条来自哪个平台。 |
| `id` | string \| null | 平台自己的编号。 |
| `ref` | string \| null | 可以原样填回请求里、指向这一条的值。 |
| `approx` | array | 这一条里哪些数字是约数或下限；都精确时为空。 |
| `type` | "entry" | 对象类型。 |
| `entry_type` | "xingtu_creator_metrics" | 条目的种类。 |
| `title` | string \| null | 条目的标题或名称。 |
| `url` | string \| null | 能打开它的链接；平台的列表不带链接时为 null。 |
| `rank` | integer \| null | 榜上的名次，从 1 起。 |
| `heat` | integer \| null | 平台给的热度值。 |
| `fields.videos` | integer \| null | 统计周期内的视频数。 |
| `fields.median_views` | integer \| null | 单条视频播放数的中位数。 |
| `fields.average_likes` | integer \| null | 单条视频的平均点赞数。 |
| `fields.average_comments` | integer \| null | 单条视频的平均评论数。 |
| `fields.average_shares` | integer \| null | 单条视频的平均分享数。 |
| `fields.engagement_rate` | number \| null | 互动率，0 到 1。 |
| `fields.engagement_rate_percentile` | number \| null | 互动率超过同类达人的比例，0 到 1。 |
| `fields.completion_rate` | number \| null | 完播率，0 到 1。 |
| `fields.completion_rate_percentile` | number \| null | 完播率超过同类达人的比例，0 到 1。 |
| `fields.currency` | string \| null | 下面四项成本的货币。 |
| `fields.cpm_21_60s` | string \| null | 21 到 60 秒视频的预期千次播放成本。 |
| `fields.cpm_over_60s` | string \| null | 60 秒以上视频的预期千次播放成本。 |
| `fields.cpe_21_60s` | string \| null | 21 到 60 秒视频的预期单次互动成本。 |
| `fields.cpe_over_60s` | string \| null | 60 秒以上视频的预期单次互动成本。 |

### `entry:xingtu_creator_post`

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `platform` | string | 这一条来自哪个平台。 |
| `id` | string \| null | 平台自己的编号。 |
| `ref` | string \| null | 可以原样填回请求里、指向这一条的值。 |
| `approx` | array | 这一条里哪些数字是约数或下限；都精确时为空。 |
| `type` | "entry" | 对象类型。 |
| `entry_type` | "xingtu_creator_post" | 条目的种类。 |
| `title` | string \| null | 条目的标题或名称。 |
| `url` | string \| null | 能打开它的链接；平台的列表不带链接时为 null。 |
| `rank` | integer \| null | 榜上的名次，从 1 起。 |
| `heat` | integer \| null | 平台给的热度值。 |
| `fields.published_at` | string \| null | 发布时间。 |
| `fields.duration` | number \| null | 视频时长，秒。 |
| `fields.views` | integer \| null | 播放数。 |
| `fields.likes` | integer \| null | 点赞数。 |
| `fields.comments` | integer \| null | 评论数。 |
| `fields.completion_rate` | number \| null | 完播率，0 到 1。 |
| `fields.engagement_rate` | number \| null | 互动率，0 到 1。 |

### `entry:xingtu_creator_keywords`

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `platform` | string | 这一条来自哪个平台。 |
| `id` | string \| null | 平台自己的编号。 |
| `ref` | string \| null | 可以原样填回请求里、指向这一条的值。 |
| `approx` | array | 这一条里哪些数字是约数或下限；都精确时为空。 |
| `type` | "entry" | 对象类型。 |
| `entry_type` | "xingtu_creator_keywords" | 条目的种类。 |
| `title` | string \| null | 条目的标题或名称。 |
| `url` | string \| null | 能打开它的链接；平台的列表不带链接时为 null。 |
| `rank` | integer \| null | 榜上的名次，从 1 起。 |
| `heat` | integer \| null | 平台给的热度值。 |
| `fields.keywords` | array \| null | 高频词，每个词一项：keyword、mentions。 |

### `entry:xingtu_creator_scores`

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `platform` | string | 这一条来自哪个平台。 |
| `id` | string \| null | 平台自己的编号。 |
| `ref` | string \| null | 可以原样填回请求里、指向这一条的值。 |
| `approx` | array | 这一条里哪些数字是约数或下限；都精确时为空。 |
| `type` | "entry" | 对象类型。 |
| `entry_type` | "xingtu_creator_scores" | 条目的种类。 |
| `title` | string \| null | 条目的标题或名称。 |
| `url` | string \| null | 能打开它的链接；平台的列表不带链接时为 null。 |
| `rank` | integer \| null | 榜上的名次，从 1 起。 |
| `heat` | integer \| null | 平台给的热度值。 |
| `fields.overall.score` | number \| null | 星图指数（综合）得分，0 到 100。 |
| `fields.overall.average` | number \| null | 同类达人星图指数（综合）的平均分。 |
| `fields.overall.rank` | integer \| null | 星图指数（综合）的名次，1 为最高。 |
| `fields.overall.rank_share` | number \| null | 这个名次处在前百分之多少，0 到 1：0.05 表示前 5%。 |
| `fields.reach.score` | number \| null | 传播指数得分，0 到 100。 |
| `fields.reach.average` | number \| null | 同类达人传播指数的平均分。 |
| `fields.reach.rank` | integer \| null | 传播指数的名次，1 为最高。 |
| `fields.reach.rank_share` | number \| null | 这个名次处在前百分之多少，0 到 1：0.05 表示前 5%。 |
| `fields.seeding.score` | number \| null | 种草指数得分，0 到 100。 |
| `fields.seeding.average` | number \| null | 同类达人种草指数的平均分。 |
| `fields.seeding.rank` | integer \| null | 种草指数的名次，1 为最高。 |
| `fields.seeding.rank_share` | number \| null | 这个名次处在前百分之多少，0 到 1：0.05 表示前 5%。 |
| `fields.conversion.score` | number \| null | 转化指数得分，0 到 100。 |
| `fields.conversion.average` | number \| null | 同类达人转化指数的平均分。 |
| `fields.conversion.rank` | integer \| null | 转化指数的名次，1 为最高。 |
| `fields.conversion.rank_share` | number \| null | 这个名次处在前百分之多少，0 到 1：0.05 表示前 5%。 |
| `fields.cooperation.score` | number \| null | 合作指数得分，0 到 100。 |
| `fields.cooperation.average` | number \| null | 同类达人合作指数的平均分。 |
| `fields.cooperation.rank` | integer \| null | 合作指数的名次，1 为最高。 |
| `fields.cooperation.rank_share` | number \| null | 这个名次处在前百分之多少，0 到 1：0.05 表示前 5%。 |
| `fields.value_for_money.score` | number \| null | 性价比指数得分，0 到 100。 |
| `fields.value_for_money.average` | number \| null | 同类达人性价比指数的平均分。 |
| `fields.value_for_money.rank` | integer \| null | 性价比指数的名次，1 为最高。 |
| `fields.value_for_money.rank_share` | number \| null | 这个名次处在前百分之多少，0 到 1：0.05 表示前 5%。 |

### `entry:xingtu_creator_content_mix`

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `platform` | string | 这一条来自哪个平台。 |
| `id` | string \| null | 平台自己的编号。 |
| `ref` | string \| null | 可以原样填回请求里、指向这一条的值。 |
| `approx` | array | 这一条里哪些数字是约数或下限；都精确时为空。 |
| `type` | "entry" | 对象类型。 |
| `entry_type` | "xingtu_creator_content_mix" | 条目的种类。 |
| `title` | string \| null | 条目的标题或名称。 |
| `url` | string \| null | 能打开它的链接；平台的列表不带链接时为 null。 |
| `rank` | integer \| null | 榜上的名次，从 1 起。 |
| `heat` | integer \| null | 平台给的热度值。 |
| `fields.categories` | array \| null | 内容分类，每类一项：name、share、videos。 |

### `entry:xingtu_campaign`

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `platform` | string | 这一条来自哪个平台。 |
| `id` | string \| null | 平台自己的编号。 |
| `ref` | string \| null | 可以原样填回请求里、指向这一条的值。 |
| `approx` | array | 这一条里哪些数字是约数或下限；都精确时为空。 |
| `type` | "entry" | 对象类型。 |
| `entry_type` | "xingtu_campaign" | 条目的种类。 |
| `title` | string \| null | 条目的标题或名称。 |
| `url` | string \| null | 能打开它的链接；平台的列表不带链接时为 null。 |
| `rank` | integer \| null | 榜上的名次，从 1 起。 |
| `heat` | integer \| null | 平台给的热度值。 |
| `fields.description` | string \| null | 活动介绍。 |
| `fields.category` | "platform_event" \| "ecommerce" \| "seasonal" \| "creative" \| "industry" \| null | 活动类型：平台大事件、电商节点、情绪节点、创意营销或行业活动。 |
| `fields.stage` | "preparing" \| "open" \| "live" \| "ended" \| null | 活动进行到哪一步：筹备中、招商中、已上线或已结束。 |
| `fields.signup_starts_at` | string \| null | 招商开始时间。 |
| `fields.signup_ends_at` | string \| null | 招商结束时间。 |
| `fields.starts_at` | string \| null | 活动开始时间。 |
| `fields.ends_at` | string \| null | 活动结束时间。 |
| `fields.image_url` | string \| null | 活动主图。 |

### `entry:ad`

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `platform` | string | 这一条来自哪个平台。 |
| `id` | string \| null | 平台自己的编号。 |
| `ref` | string \| null | 可以原样填回请求里、指向这一条的值。 |
| `approx` | array | 这一条里哪些数字是约数或下限；都精确时为空。 |
| `type` | "entry" | 对象类型。 |
| `entry_type` | "ad" | 条目的种类。 |
| `title` | string \| null | 条目的标题或名称。 |
| `url` | string \| null | 能打开它的链接；平台的列表不带链接时为 null。 |
| `rank` | integer \| null | 榜上的名次，从 1 起。 |
| `heat` | integer \| null | 平台给的热度值。 |
| `fields.format` | "video" \| "image" \| "carousel" \| "text" \| "other" \| null | 广告形态：文字、图片或视频；other 是平台自有的其他形式。 |
| `fields.text` | string \| null | 广告文案。 |
| `fields.landing_url` | string \| null | 点击广告后打开的地址。 |
| `fields.advertiser.id` | string \| null | 广告主编号。 |
| `fields.advertiser.name` | string \| null | 广告主名称。 |
| `fields.advertiser.url` | string \| null | 广告主在平台上的主页。 |
| `fields.images` | string[] \| null | 图片素材的地址。 |
| `fields.first_shown_at` | string \| null | 广告首次展示的时间。 |
| `fields.last_shown_at` | string \| null | 广告最近一次展示的时间；还在投放的广告，是平台最近一次看到它的时间。 |

### `entry:advertiser`

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `platform` | string | 这一条来自哪个平台。 |
| `id` | string \| null | 平台自己的编号。 |
| `ref` | string \| null | 可以原样填回请求里、指向这一条的值。 |
| `approx` | array | 这一条里哪些数字是约数或下限；都精确时为空。 |
| `type` | "entry" | 对象类型。 |
| `entry_type` | "advertiser" | 条目的种类。 |
| `title` | string \| null | 条目的标题或名称。 |
| `url` | string \| null | 能打开它的链接；平台的列表不带链接时为 null。 |
| `rank` | integer \| null | 榜上的名次，从 1 起。 |
| `heat` | integer \| null | 平台给的热度值。 |
| `fields.region` | string \| null | 广告主登记的国家或地区代码。 |

### `entry:channels_collection`

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `platform` | string | 这一条来自哪个平台。 |
| `id` | string \| null | 平台自己的编号。 |
| `ref` | string \| null | 可以原样填回请求里、指向这一条的值。 |
| `approx` | array | 这一条里哪些数字是约数或下限；都精确时为空。 |
| `type` | "entry" | 对象类型。 |
| `entry_type` | "channels_collection" | 条目的种类。 |
| `title` | string \| null | 条目的标题或名称。 |
| `url` | string \| null | 能打开它的链接；平台的列表不带链接时为 null。 |
| `rank` | integer \| null | 榜上的名次，从 1 起。 |
| `heat` | integer \| null | 平台给的热度值。 |
| `fields.description` | string \| null | 合集的简介；没有时为 null。 |
| `fields.cover_url` | string \| null | 合集封面图地址。 |
| `fields.updated_at` | string \| null | 合集最近一次更新的时间。 |
| `fields.videos` | integer \| null | 合集里的视频数。 |

### `entry:topic`

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `platform` | string | 这一条来自哪个平台。 |
| `id` | string \| null | 平台自己的编号。 |
| `ref` | string \| null | 可以原样填回请求里、指向这一条的值。 |
| `approx` | array | 这一条里哪些数字是约数或下限；都精确时为空。 |
| `type` | "entry" | 对象类型。 |
| `entry_type` | "topic" | 条目的种类。 |
| `title` | string \| null | 条目的标题或名称。 |
| `url` | string \| null | 能打开它的链接；平台的列表不带链接时为 null。 |
| `rank` | integer \| null | 榜上的名次，从 1 起。 |
| `heat` | integer \| null | 平台给的热度值。 |
| `fields.description` | string \| null | 话题的简介；没有时为 null。 |
| `fields.views` | integer \| null | 话题的浏览数。 |
| `fields.posts` | integer \| null | 话题下的内容数。 |

## 错误结构

整个请求失败时，返回的是这个结构而不是外层结构，HTTP 状态码按错误代码定。200 返回里某个结果失败时，带的是同样的 `error` 对象。

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `request_id` | string | 这次调用的编号，报告问题时带上它。 |
| `schema_version` | "v1" | 固定是 "v1"。 |
| `error.code` | string | 错误代码，对应错误表里的一行。 |
| `error.message` | string | 出了什么问题，中英文各一句。 |
| `error.retryable` | boolean | 原样再发一次有没有可能成功。 |
| `error.reason` | string | 同一个代码有多种情况时，说明是哪一种。（可能不出现） |
| `error.quote_credits` | integer | 被拒绝的这次请求本来要花多少积分。（可能不出现） |
| `error.resets_at` | string | 每日上限重新开始计的时间，ISO 8601（UTC）。（可能不出现） |
| `error.retry_at` | string | free_failure_limit 时给出：从什么时候起可以再发调用，ISO 8601（UTC）。（可能不出现） |
| `error.fix.param` | string | 需要改的参数。（可能不出现） |
| `error.fix.allowed` | array | 这个参数允许的取值。（可能不出现） |
| `error.fix.example_call` | object | 一个可以照抄的正确调用，里面不会回显 Key。（可能不出现） |
| `error.fix.action_url` | string | 去哪里处理：控制台、账单页或状态页。（可能不出现） |
| `error.fix.note` | string | 一句话说明该怎么做。（可能不出现） |
| `billing.cost_credits` | integer | 固定为 0：失败的请求不扣费。（可能不出现） |
| `billing.balance_credits` | integer | 你的余额；认得出 Key 时才有。（可能不出现） |
| `billing.today_spend_credits` | integer | 今天（UTC）已经花掉的积分。（可能不出现） |
| `billing.daily_limit_credits` | integer \| null | 每日上限；没设时为 null。（可能不出现） |
| `billing.daily_remaining_credits` | integer \| null | 每日上限还剩多少；没设时为 null。（可能不出现） |
| `billing.display` | string | 一句可以直接复述给你的话。（可能不出现） |

[错误](https://socialtoai.com/zh/docs/api/errors.md) 页列出了全部代码。

## 结果还没出来的时候

一次调用没法在请求里答完时，返回的是 HTTP 202 和一个句柄，而不是这个外层结构；之后凭句柄来读它。见[结果与句柄](https://socialtoai.com/zh/docs/api/results.md)。