开始使用
约定
所有端点共同遵守的规则:信封、状态码、时间与 id、分页、幂等、限流、请求 id 与版本。
信封与状态码
成功 { data, meta },失败 { error: { code, message, params }, meta }。新建类端点(新建内容 / 选题 / 回复 / 上传素材)成功回 201,其余 200;错误的 HTTP 状态由 error.code 决定,对照表见 错误码。
按
error.code 分支,不要匹配 message 文本 —— message 是给人和模型看的英文提示,措辞可能变。时间与 id
- 响应里的时间一律 ISO 8601 UTC(
2026-09-21T10:00:00.000Z);请求里的时间必须带时区(Z或±HH:MM),不带时区回 400。 - 数据口径按北京日历日(与站内分析页一致)。
- id 是不透明字符串,不要解析其结构;只在本工作区内有效。
- 平台枚举:
x、youtube、instagram、tiktok、facebook、threads(代发)以及douyin、xiaohongshu、wechat_mp(手动渠道,只记录不外发)。
分页
列表端点用游标分页:响应里 nextCursor 非 null 就还有下一页,把它原样作为 cursor 传回;limit 默认 20、上限 100(评论收件箱固定每页 30)。游标不透明、有时效,坏了回 400。
GET /api/v1/posts?status=published&limit=50
GET /api/v1/posts?status=published&limit=50&cursor=<nextCursor>幂等
- 写类端点接受
Idempotency-Key请求头(8–128 chars of [A-Za-z0-9_.:-]);也可以放在 body 的clientRequestId,两者都给时以头为准。 - 发布档(
action: "publish"、确认发布、发布 / 重投、回复评论)必填;其余写端点可选。 - 同一凭证 + 同一端点 + 同一键,24 小时内重发:原样回第一次的结果,
meta.replayed: true,响应头Idempotent-Replayed: true;上传素材的缓存只有 5 分钟(直传票就活那么久)。 - 同一个键配了不同的入参会被拒,防止把键当常量用;失败的调用不缓存,修正入参后可复用同一个键。
- 第一次调用还在处理时的并发重发回 409(
replay),稍后重试即可。
限流与日上限
三档按凭证计(REST 与 MCP 共用同一份额度),超出回 429 并带 Retry-After(秒)。
| 档位 | 每分钟 | 覆盖的端点 |
|---|---|---|
| 读 | 60 | 全部 GET + 发布预检 |
| 写 | 10 | 新建 / 修改(非 publish 档)、改期、送审、上传素材、新建选题 |
| 发布 | 5 | 新建 / 修改的 publish 档、确认发布、发布 / 重投、回复评论 |
- 每凭证每日外发上限默认 20 条(运营可按凭证调整),同一账号两次外发至少间隔 600 秒;排期每日上限 100 条。
- 评论回复:同一条评论 24 小时内最多 3 条我方回复,每凭证每日 500 条。
- 单条内容最多 20 个目标账号;套餐的月度排期配额见
GET /v1/workspace的quotas,耗尽回 402(plan_limit)。 - 日上限类的 429 带
params.reason(如publish_daily_cap),重试无用,等次日。
请求 id 与版本
- 可自带
X-Request-Id(≤36 个[A-Za-z0-9._:-]),会原样回显在响应头与meta.requestId;不带就由服务端生成。排障时把它发给我们。 /api/v1内只做向后兼容的追加;破坏性变更会开新的大版本并提前公告。- 机读定义:OpenAPI 3.1,由与运行时相同的 schema 生成,不会与实现漂移。