菜单

SocialEcho OpenAPI 文档

1. 文档适用对象

本文档面向需要对接 SocialEcho 外部 API 的研发、测试、实施与自动化工程师。目标是让你在最短时间内完成可用对接。

2. 快速接入（3 分钟）

  1. 登录 https://app.socialecho.net 并创建团队。

  2. 在「团队管理」中创建 Team API Key。

  3. 使用 Bearer 鉴权调用 API（Authorization: Bearer se_xxx）。

  4. 先调用 GET /v1/team 验证鉴权与团队上下文，再调用其他业务接口。

  5. 成功判定见下文「环境与鉴权」中的推荐口径。

3. 环境与鉴权

字段

说明

Base URL

https://api.socialecho.net

鉴权方式

Bearer Token（Team API Key）

请求头

Authorization: Bearer se_your_team_api_key

可选请求头

X-Lang: zh_CN 或 en

频率限制

单个 API Key 最多 120 次请求/分钟

3.1 传输形态说明（与线上一版文档的差异）

当前导出的 OpenAPI 约定：多数接口为 GET，业务参数放在 Content-Type: application/json 的请求体中（而不是 QueryString）。
若你使用浏览器 fetch 发 GET + body，部分环境会限制；推荐使用 curl、服务端 HTTP 客户端或本仓库提供的 CLI / n8n 节点。

3.2 推荐成功判定口径

  1. HTTP 状态码 = 200

  2. 响应 JSON 中 **code = 200 或 0**（以服务端实际返回为准；旧文档仅写 200，现已兼容 0）

  3. 其他情况均按失败处理并走重试/告警

4. 通用错误处理策略

情况

说明

400 Bad Request

参数缺失、参数格式错误（请优先检查日期格式与枚举字段）

401 Unauthorized

API Key 无效、过期或未正确放在 Authorization 头中

429 Too Many Requests

触发限流；建议增加节流与指数退避（1s/2s/4s）

超时/网络异常

建议重试 2～3 次，保留请求参数快照用于排查

5. 接口清单

以下示例 Base URL 均为 https://api.socialecho.net；将 se_your_team_api_key 替换为你的 Team API Key。

通用 curl 说明：对 GET 且带 JSON body 的接口，使用 --data-raw '<json>'（或 --data-binary）。请勿省略 Content-Type: application/json。

5.1 获取当前 API Key 可访问的团队信息（GET /v1/team）

建议先调用该接口，确认团队上下文后再拉取业务数据。

参数名

位置

必填

类型

说明

X-Lang

header

否

string

zh_CN 或 en，默认 zh_CN

（body）

body

否

object

空对象 {}

请求示例（cURL）

curl --request GET 'https://api.socialecho.net/v1/team' \
  --header 'Authorization: Bearer se_your_team_api_key' \
  --header 'Content-Type: application/json' \
  --header 'X-Lang: zh_CN' \
  --data-raw '{}'

响应示例

{
  "code": 200,
  "message": "success",
  "data": {
    "id": 1024,
    "code": "TEAM_ABC123",
    "title": "SocialEcho QA Team",
    "timezone": "Asia/Shanghai"
  }
}

5.2 获取社媒账号列表（GET /v1/account）

参数名

位置

必填

类型

说明

X-Lang

header

否

string

返回语言

page

body

否

integer

页码；不传则可能返回全量（以服务端为准）

type

body

否

integer

1 = 授权账号，2 = 竞品账号

请求示例（cURL）

curl --request GET 'https://api.socialecho.net/v1/account' \
  --header 'Authorization: Bearer se_your_team_api_key' \
  --header 'Content-Type: application/json' \
  --header 'X-Lang: zh_CN' \
  --data-raw '{"page":1,"type":1}'

响应示例

{
  "code": 200,
  "message": "success",
  "data": {
    "page": 1,
    "per_page": 10,
    "total": 2,
    "list": [
      {
        "id": 163751,
        "title": "esprit.vert.medic",
        "app": "Instagram",
        "type": 1,
        "status": "normal",
        "account": "@esprit.vert.medic",
        "authorization_at": "2026-03-30 09:34:44"
      }
    ]
  }
}

5.3 获取贴文列表（GET /v1/article）

参数名

位置

必填

类型

说明

X-Lang

header

否

string

返回语言

page

body

否

integer

页码

account_ids

body

否

integer[]

账号 ID 数组

请求示例（cURL）

curl --request GET 'https://api.socialecho.net/v1/article' \
  --header 'Authorization: Bearer se_your_team_api_key' \
  --header 'Content-Type: application/json' \
  --header 'X-Lang: zh_CN' \
  --data-raw '{"page":1,"account_ids":[163956,163955,28]}'

响应示例

{
  "code": 200,
  "message": "success",
  "data": {
    "page": 1,
    "per_page": 10,
    "total": 1,
    "list": [
      {
        "id": 987654,
        "uuid": "tE-9LwdHfNk",
        "app": "YouTube",
        "account_id": 163751,
        "content": "Example article content",
        "created_at": "2026-03-24 10:05:01",
        "url": "https://www.youtube.com/watch?v=tE-9LwdHfNk",
        "reports": {
          "exposure": 1021,
          "like": 40,
          "comment": 14,
          "share": 0
        }
      }
    ]
  }
}

5.4 获取报表数据（GET /v1/report）

参数名

位置

必填

类型

说明

X-Lang

header

否

string

返回语言

start_date

body

是

string

YYYY-MM-DD

end_date

body

是

string

YYYY-MM-DD

time_type

body

是

integer

1 = 日期内新增贴文，2 = 历史全部贴文

account_ids

body

否

integer[]

账号 ID 数组

group

body

否

string

不传=总量；day / app / account 为分组维度

请求示例（cURL）

curl --request GET 'https://api.socialecho.net/v1/report' \
  --header 'Authorization: Bearer se_your_team_api_key' \
  --header 'Content-Type: application/json' \
  --header 'X-Lang: zh_CN' \
  --data-raw '{"start_date":"2026-01-01","end_date":"2026-03-24","time_type":1,"group":"day","account_ids":[163956,163955,28]}'

响应示例（汇总）

{
  "code": 200,
  "message": "success",
  "data": {
    "scope": {
      "start_date": "2026-01-01",
      "end_date": "2026-03-24",
      "time_type": 1,
      "group": ""
    },
    "totals": {
      "exposure": 120345,
      "like": 4512,
      "comment": 893,
      "share": 326
    }
  }
}

5.5 获取 OSS 上传地址（GET /v1/upload/url）

用于获取文件上传到 OSS 所需的 URL（具体字段以服务端返回为准）。一般流程：先取上传 URL → 上传文件 → 将返回的文件 URL 用于发布接口的 attachments。

参数名

位置

必填

类型

说明

X-Lang

header

否

string

返回语言

（body）

body

否

object

空对象 {}

请求示例（cURL）

curl --request GET 'https://api.socialecho.net/v1/upload/url' \
  --header 'Authorization: Bearer se_your_team_api_key' \
  --header 'Content-Type: application/json' \
  --header 'X-Lang: zh_CN' \
  --data-raw '{}'

5.6 获取 Reddit 社区列表（GET /v1/reddit/communities）

发布 Reddit 内容前，可用于选择社区上下文。

参数名

位置

必填

类型

说明

X-Lang

header

否

string

返回语言

account_id

body

是

integer

社媒账号 ID

请求示例（cURL）

curl --request GET 'https://api.socialecho.net/v1/reddit/communities' \
  --header 'Authorization: Bearer se_your_team_api_key' \
  --header 'Content-Type: application/json' \
  --header 'X-Lang: zh_CN' \
  --data-raw '{"account_id":163751}'

5.7 获取 Pinterest 图版列表（GET /v1/pinterest/boards）

发布 Pinterest 内容前，可用于选择图版（board）。

参数名

位置

必填

类型

说明

X-Lang

header

否

string

返回语言

account_id

body

是

integer

社媒账号 ID

请求示例（cURL）

curl --request GET 'https://api.socialecho.net/v1/pinterest/boards' \
  --header 'Authorization: Bearer se_your_team_api_key' \
  --header 'Content-Type: application/json' \
  --header 'X-Lang: zh_CN' \
  --data-raw '{"account_id":163751}'

5.8 发布贴文（POST /v1/publish/article）

跨平台发布。type、extra、attachments 等字段与平台强相关，请以控制台与联调结果为准。下列为 OpenAPI 中的核心字段说明摘要。

参数名

位置

必填

类型

说明

X-Lang

header

否

string

返回语言

account_id

body

是

integer

发布所用社媒账号

type

body

是

string

发布类型（按平台取值，如 Facebook post、YouTube video 等）

status

body

是

integer

0 = 草稿，1 = 发布

scheduled_at

body

否

string

定时时间；status=1 时可填，不填则立即发布

comment

body

是

string[]

评论数组（可为空数组）

content

body

否

string

正文内容

extra

body

是

object

扩展字段：标题、图版/社区 ID、链接、TikTok 草稿、Reddit flair 等（各平台不同）

attachments

body

是

object[]

附件列表，每项需包含已上传文件 URL：{ "url": "https://..." }

type 取值示例：
Facebook：reels / post / stories；YouTube：shorts / video；Instagram：reels / post / stories；X：short_post / long_post；LinkedIn：post；TikTok：video / photo；Pinterest：post；Reddit：text / link / media。

请求示例（cURL，请使用实际 JSON 文件）

curl --request POST 'https://api.socialecho.net/v1/publish/article' \
  --header 'Authorization: Bearer se_your_team_api_key' \
  --header 'Content-Type: application/json' \
  --header 'X-Lang: zh_CN' \
  --data @publish-payload.json

 

publish-payload.example.json：
{
  "account_id": 163751,
  "type": "post",
  "status": 0,
  "scheduled_at": "",
  "comment": [],
  "content": "示例内容",
  "extra": {
    "title": "示例标题",
    "category_id": "",
    "link": "",
    "draft": false,
    "flair": {
      "uuid": "replace-with-reddit-flair-uuid",
      "title": "replace-with-reddit-flair-title"
    }
  },
  "attachments": [
    {
      "url": "https://example.com/uploaded-file.jpg"
    }
  ]
}

 

 publish-payload.json 需按目标平台补齐 extra（例如 Pinterest 的 category_id、Reddit 的 flair 等）。仓库内技能包附带示例可参考 publish-payload.example.json。

6. 对接建议

  1. 先获取账号列表，再将 account_id 传给贴文、报表、Reddit、Pinterest 等接口，避免传空范围。

  2. 涉及分页接口时，统一循环 page 并在 total/per_page 达到末页后停止。

  3. 在工作流平台（n8n、Zapier、Dify）中，将失败分支区分为鉴权失败与限流失败。

  4. 建议记录请求时间、接口名、HTTP 状态码、业务 code 与关键请求参数，便于线上排障。

  5. 发布类接口建议先走 GET /v1/upload/url 完成素材上传，再组装 attachments。

7. 常见问题（FAQ）

Q1：返回 HTTP 200，但业务失败怎么办？
A：以 JSON 中 code 是否为 200 或 0 为准，不要只看 HTTP 状态码。

Q2：account_ids 在 JSON body 里怎么传？
A：使用 整数数组（例如 [163956,163955,28]）。若你在旧集成里使用 CSV 查询参数，请改为与 OpenAPI 一致的 body 形态。

Q3：如何避免触发 429？
A：控制单 key 不超过 120 req/min，并配置节流与指数退避。

本地文档生成说明：结构与帮助中心原文对齐，接口定义与 默认模块.openapi.json（v1.1.0）一致。若与线上一致性校验冲突，以服务端与最新导出 OpenAPI 为准。

上一个
API说明
下一个
各平台发布内容格式限制
最近修改: 2026-04-21Powered by