# SocialEcho OpenAPI - 开发者 LLM 参考

本机器可读文档面向集成 SocialEcho OpenAPI 的开发、测试、实施、自动化工程师与 AI 智能体。

- 开发者 LLM：https://www.socialecho.net/llms-developers.txt?lang=zh
- 官方开发文档：https://www.socialecho.cn/helpcenter/docs/socialecho-openapi-docs
- API Base URL：https://api.socialecho.net
- 来源核实日期：2026-07-16

## 快速开始

1. 登录 https://app.socialecho.net，创建或选择团队。
2. 在团队管理中创建 Team API Key。
3. 在请求中添加 `Authorization: Bearer se_your_team_api_key`。
4. 首先调用 `GET /v1/team`，验证认证状态和团队上下文。
5. 在查询贴文、报告、发布内容、Reddit 社区或 Pinterest 画板前，先通过 `GET /v1/account` 获取账号 ID。

## 认证与传输

- 认证方式：使用 Team API Key 的 Bearer Token。
- 认证请求头：`Authorization: Bearer se_your_team_api_key`。
- JSON 请求：`Content-Type: application/json`。
- 可选语言请求头：`X-Lang: zh_CN` 或 `X-Lang: en`。
- 限流：每个 API Key 每分钟 120 次请求。
- 不要在浏览器代码、公开仓库、日志或发送给不可信服务的提示词中暴露 Team API Key。

重要传输规则：多个 GET 接口通过 JSON 请求体接收参数，而不是查询字符串。浏览器 `fetch` 无法可靠发送 GET 请求体，请使用 cURL、服务端 HTTP 客户端或受支持的自动化连接器。

## 成功条件与错误处理

只有同时满足以下条件才视为成功：

- HTTP 状态码为 `200`。
- 响应 JSON 的 `code` 为 `200` 或 `0`。

即使 HTTP 状态为 `200`，其他业务码也应按失败处理。

- `400 Bad Request`：检查必填字段、日期、数组、MIME 类型和平台枚举值。
- `401 Unauthorized`：检查 Team API Key 和 Bearer 请求头格式。
- `429 Too Many Requests`：将频率限制在每分钟 120 次以内，并按 1、2、4 秒等节奏进行指数退避重试。
- 超时或网络失败：重试 2 至 3 次，并记录接口、请求时间、HTTP 状态、业务码和不含敏感信息的关键参数。

## 可用接口

### GET /v1/team

返回当前认证团队信息。配置密钥后应首先调用此接口。

- 请求体：`{}`（可选）
- 可选请求头：`X-Lang`

```bash
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 '{}'
```

### GET /v1/account

列出已授权账号或竞品账号。

- `page`：可选整数，页码。
- `type`：可选整数；`1` 表示已授权账号，`2` 表示竞品账号。

```bash
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}'
```

### GET /v1/article

列出团队或指定账号的贴文。

- `page`：可选整数，页码。
- `account_ids`：可选整数数组，SocialEcho 账号 ID。

```bash
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]}'
```

### GET /v1/report

返回指定日期范围内的分析数据。

- `start_date`：必填字符串，格式为 `YYYY-MM-DD`。
- `end_date`：必填字符串，格式为 `YYYY-MM-DD`。
- `time_type`：必填整数；`1` 表示时间范围内新建的贴文，`2` 表示时间范围内统计的全部历史贴文。
- `account_ids`：可选整数数组，账号 ID。
- `group`：可选字符串；空值表示汇总，可使用 `day`、`app` 或 `account` 分组。

```bash
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]}'
```

### GET /v1/upload/url

返回媒体文件上传信息。常用流程为：获取上传地址 → 上传文件 → 发布时把返回的文件 URL 写入 `attachments`。

- `content_type`：必填 MIME 类型。
- 图片类型：`image/jpeg`、`image/jpg`、`image/png`、`image/gif`、`image/webp`、`image/bmp`。
- 视频类型：`video/mp4`、`video/avi`、`video/mov`、`video/wmv`、`video/flv`、`video/webm`、`video/mkv`、`video/3gp`、`video/quicktime`。

```bash
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 '{"content_type":"image/png"}'
```

### GET /v1/reddit/communities

发布 Reddit 内容前，列出已连接账号可用的社区。

- `account_id`：必填整数，SocialEcho 账号 ID。

### GET /v1/pinterest/boards

发布 Pinterest 内容前，列出已连接账号可用的画板。

- `account_id`：必填整数，SocialEcho 账号 ID。

### POST /v1/publish/article

创建草稿、立即发布或定时发布跨平台内容。平台专用字段必须结合当前产品界面和官方 OpenAPI 文档验证。

- `account_id`：必填整数，目标账号 ID。
- `type`：必填字符串，平台专用发布类型。
- `status`：必填整数；`0` 表示草稿，`1` 表示发布。
- `scheduled_at`：可选定时时间；当 `status=1` 且省略该字段时立即发布。
- `comment`：必填字符串数组，可为空数组。
- `content`：可选贴文正文。
- `extra`：必填对象，包含标题、画板或社区 ID、链接、TikTok 草稿标识、Reddit flair 等平台专用字段。
- `attachments`：必填对象数组；每项使用已上传文件 URL，例如 `{ "url": "https://..." }`。

OpenAPI 中的常用 `type`：

- Facebook：`reels`、`post`、`stories`。
- Instagram：`reels`、`post`、`stories`。
- YouTube：`shorts`、`video`。
- X：`short_post`、`long_post`。
- LinkedIn：`post`。
- TikTok：`video`、`photo`。
- Pinterest：`post`。
- Reddit：`text`、`link`、`media`。

```bash
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
```

## 推荐集成流程

1. 通过 `GET /v1/team` 验证密钥和团队。
2. 通过 `GET /v1/account` 获取已授权账号并保存返回的 SocialEcho 账号 ID。
3. 分页接口持续增加 `page`，直到 `total` 和 `per_page` 表明已到最后一页。
4. 发布媒体前调用 `GET /v1/upload/url`，上传文件并把结果 URL 写入 `attachments`。
5. 发布 Reddit 或 Pinterest 前，先获取社区或画板。
6. 将最终请求体发送到 `POST /v1/publish/article`。
7. 通过 `GET /v1/article` 与 `GET /v1/report` 完成从发布到分析的数据闭环。

## 当前 API 范围

当前公开 OpenAPI 覆盖团队、账号、贴文、报告、上传地址、Reddit 社区、Pinterest 画板和内容发布。来源文档没有把评论、私信接口或官方 MCP 服务器列为已上线接口，因此不应假设这些接口可用。

平台专用 `extra` 字段和发布限制可能变化，请以官方文档为准：https://www.socialecho.cn/helpcenter/docs/socialecho-openapi-docs