Reference

API 接口设计与验收样例

15 个接口设计示意，覆盖账号、素材、内容、监测与回调。请求、账号与响应均为示意数据，不代表真实客户交付或已上线的 API 产品。

以下为设计示意，数字与响应为示意数据；字段与路径需按项目实现和联调。完整接口定义（OpenAPI）在需求评估后确认。

这些账号、内容和监测样例用于讨论输入输出与状态约定。其他 API 项目同样需要字段映射、权限、错误分类和结果核对；先看API 设计输入，再按联调验收流程确定测试样本。

约定：路径中的 {param} 为占位符；时间均为 ISO 8601；分页使用 page（账号 / 内容列表）或 cursor（大数据量导出）。

账号 Accounts

POST /v1/accounts/authorize/url 生成账号授权链接与二维码，二维码有效期 5 分钟。

参数	类型	必填	说明
`platform`	string	是	平台标识，见支持平台列表
`redirect_url`	string	否	扫码完成后的跳转地址，需与控制台配置的域名一致
`state`	string	否	自定义状态值，回调时原样返回，可用于防 CSRF

{
  "qr_url": "https://api.apinara.com/qr/9f3c2a.png",
  "authorize_url": "https://api.apinara.com/authorize/9f3c2a",
  "state": "uid_1024",
  "expires_in": 300
}

GET /v1/accounts 分页查询已授权账号，可按平台与状态过滤。

参数	类型	必填	说明
`platform`	string	否	按平台过滤
`status`	string	否	active / expired / revoked
`page`	integer	否	默认 1
`page_size`	integer	否	默认 20，最大 100

{
  "data": [
    {
      "id": "acc_8f21",
      "platform": "xiaohongshu",
      "nickname": "山野咖啡",
      "avatar": "https://cdn.example.com/avatar.jpg",
      "status": "active",
      "authorized_at": "2026-09-01T10:22:00+08:00",
      "expires_at": "2026-10-31T10:22:00+08:00"
    }
  ],
  "has_more": false,
  "total": 1
}

DELETE /v1/accounts/{account_id} 解除账号授权。解除后该账号的凭证立即失效，历史任务仍可查询。

{
  "id": "acc_8f21",
  "status": "revoked",
  "revoked_at": "2026-10-23T09:20:00+08:00"
}

素材 Media

图片 ≤ 20MB 可直接传；视频建议用分片上传，单片 4MB、并发 3 路。

POST /v1/media/upload 上传图片、视频或封面，返回可复用的 media_id。

参数	类型	必填	说明
`file`	binary	是	multipart/form-data 文件
`type`	string	是	image / video / cover
`expires_in`	integer	否	素材保留时长（秒），默认 7 天

{
  "media_id": "med_3c9a71",
  "url": "https://cdn.apinara.com/med_3c9a71.jpg",
  "type": "image",
  "width": 1080,
  "height": 1440,
  "size": 482113,
  "expires_at": "2026-10-30T09:12:00+08:00"
}

GET /v1/media/{media_id} 查询素材状态。视频转码完成前 status 为 processing。

{
  "media_id": "med_3c9a71",
  "status": "ready",
  "duration": 42.6,
  "cover_url": "https://cdn.apinara.com/med_3c9a71_cover.jpg"
}

内容 Content

POST /v1/content/publish 创建发布任务。支持立即发布或指定 publish_at 定时发布。

参数	类型	必填	说明
`platform`	string	是	平台标识
`account_id`	string	是	授权账号 ID
`content_type`	string	是	note / video / article / status / weitoutiao
`title`	string	否	标题，文章类平台必填
`body`	string	否	正文，支持 Markdown
`images`	string[]	否	图片 URL 或 media_id 数组
`video`	string	否	视频 URL 或 media_id
`topics`	string[]	否	话题，不带 # 号
`publish_at`	string	否	ISO 8601，最长 30 天
`extra`	object	否	平台特有字段，如 B 站 tid、知乎 question_id

{
  "id": "task_9f3c2a",
  "status": "accepted",
  "platform": "xiaohongshu",
  "account_id": "acc_8f21",
  "created_at": "2026-10-23T09:12:44+08:00",
  "publish_at": "2026-10-23T09:12:44+08:00",
  "result": null
}

GET /v1/content/{task_id} 查询任务状态、审核结果与平台内容链接。

{
  "id": "task_9f3c2a",
  "status": "success",
  "platform": "xiaohongshu",
  "platform_post_id": "66f1c0a2e4b0...",
  "platform_url": "https://www.xiaohongshu.com/explore/66f1c0a2",
  "published_at": "2026-10-23T09:13:02+08:00",
  "error": null
}

GET /v1/content 按平台、账号、状态、时间范围分页查询任务。

参数	类型	必填	说明
`platform`	string	否	平台标识
`account_id`	string	否	账号 ID
`status`	string	否	accepted / reviewing / success / failed / rejected
`from`	string	否	创建时间下界，ISO 8601
`to`	string	否	创建时间上界，ISO 8601

{
  "data": [
    { "id": "task_9f3c2a", "status": "success", "platform": "xiaohongshu" },
    { "id": "task_9f3c2b", "status": "reviewing", "platform": "douyin" }
  ],
  "has_more": true,
  "next_cursor": "c_8a71f"
}

POST /v1/content/schedule 批量创建定时发布任务，单次最多 50 条，按账号维度串行排队。

参数	类型	必填	说明
`items`	object[]	是	发布任务数组，字段同 publish
`publish_at`	string	是	统一执行时间，ISO 8601

{
  "batch_id": "batch_4d2f",
  "total": 12,
  "scheduled_at": "2026-10-24T09:00:00+08:00",
  "tasks": ["task_9f3c2a", "task_9f3c2b"]
}

DELETE /v1/content/{task_id} 取消尚未执行的任务。已进入审核或已发布的任务无法取消。

{
  "id": "task_9f3c2a",
  "status": "canceled"
}

数据 Analytics

GET /v1/analytics/posts 获取内容的曝光、阅读、点赞、收藏、评论数，数据延迟约 2 小时。

参数	类型	必填	说明
`platform`	string	是	平台标识
`account_id`	string	否	不传则返回该平台全部账号
`from`	string	是	开始日期，格式 YYYY-MM-DD
`to`	string	是	结束日期，最长跨度 90 天

{
  "data": [
    {
      "platform_post_id": "66f1c0a2",
      "title": "秋天的第一杯手冲",
      "impressions": 12840,
      "likes": 962,
      "collects": 431,
      "comments": 87,
      "published_at": "2026-10-23T09:13:02+08:00"
    }
  ]
}

GET /v1/analytics/accounts 获取账号维度的粉丝增长与内容表现汇总。

参数	类型	必填	说明
`platform`	string	是	平台标识
`account_id`	string	是	账号 ID
`period`	string	否	7d / 30d / 90d，默认 30d

{
  "account_id": "acc_8f21",
  "followers": 18420,
  "followers_delta": 326,
  "posts": 12,
  "avg_likes": 418
}

Webhook

回调采用至少一次投递，请用事件 id 做幂等；签名违规或超时都应返回 4xx 触发重试。

POST /v1/webhooks 创建回调地址，可订阅多个事件。secret 只返回一次。

参数	类型	必填	说明
`url`	string	是	HTTPS 回调地址
`events`	string[]	是	content.published / content.failed / account.expired

{
  "id": "wh_71c3",
  "url": "https://your.app/nara/webhook",
  "events": ["content.published", "content.failed"],
  "secret": "whsec_9f3c2a71..."
}

GET /v1/webhooks 列出当前应用的所有回调配置与最近一次投递结果。

{
  "data": [
    {
      "id": "wh_71c3",
      "url": "https://your.app/nara/webhook",
      "events": ["content.published"],
      "last_status": 200,
      "last_attempt_at": "2026-10-23T09:13:05+08:00"
    }
  ]
}

DELETE /v1/webhooks/{id} 删除回调配置，历史投递记录保留 30 天。

{
  "id": "wh_71c3",
  "deleted": true
}