popkitpopkitAPI
中EN
内容

新建内容

新建一条内容,action 决定落点。draft = 存草稿(预检只提示不拦);schedule = 定时发布(走月配额与硬预检);publish = 立即对外发布(硬预检 + 频控;需要两步确认的凭证会先落草稿并回一枚 confirmToken,再调 confirm 才真正外发)。发布是异步的:返回 status=publishing 后用内容详情轮询各账号结果。

POST/api/v1/posts
posts:writeschedule:writepublish:execute写 / 发布档限流Idempotency-Key 可选,publish 档必填

鉴权与护栏

  • 请求头 Authorization: Bearer <长期凭证>,凭证在设置页「接入外部系统 → 长期凭证」签发,见 鉴权与权限。
  • 凭证需带 scope posts:write / schedule:write / publish:execute(任一即可调用;具体能用哪一档由凭证的发布落点白名单决定);签发者在工作区里的角色也要允许该动作。
  • 限流:写档每分钟 10 次;action: "publish" 时按发布档计,每分钟 5 次(均按凭证计)。
  • 幂等:draft / schedule 档可选,action: "publish" 时必须带 Idempotency-Key。

请求体(application/json)

actionenum: draft · schedule · publish必填

落点档位:draft 存草稿;schedule 定时发布(需 scheduledAt);publish 立即对外发布。

contentstring必填

主文案;每个目标渠道都在 variants 里给了自己的文案时可留空字符串。

platformsstring[] (enum: x · youtube · instagram · tiktok · facebook · threads · douyin · xiaohongshu · wechat_mp)必填

目标平台;draft 档可为空数组。

titlestring可选

标题(YouTube 必填)。

targetAccountIdsstring[]可选

目标账号 id(来自 GET /v1/accounts)。不给 = 发给 platforms 下全部可用账号(过期 / 缺发布权的自动跳过),单次上限 20 个。给了就只发这些号,且必须都属于 platforms 里的平台。

scheduledAtdatetime (ISO 8601, with timezone)可选

schedule 档必填,必须带时区(Z 或 ±HH:MM)且至少比现在晚 60 秒;draft 档给了只作日历上的计划日期。

mediaobject[] { kind, dataUrl, platform?, durationSec? }可选

kind 为 image / cover / video;dataUrl 必须是本站对象存储 URL(先用 POST /v1/media 换取),图片 / 封面也可用 image data URL;platform 表示只给某平台用的覆写媒体。

variantsobject[] { platform, content?, title? }可选

逐平台文案覆写;只传与主文案不同的。

tiktokOptionsobject可选

TikTok Direct Post 合规选项:privacyLevel(发 TikTok 时必须由人选定)、allowComment、allowDuet、allowStitch、commercial、yourBrand、brandedContent、coverTimestampMs。

youtubeOptionsobject { categoryId?, madeForKids?, playlistId? }可选

YouTube 分类、「面向儿童」标记,以及发布成功后把视频加入的播放列表 id(须属于目标频道;稍后观看等系统列表不可用;加入失败不影响发布)。

threadsOptionsobject { replyControl?, topicTag?, linkAttachment?, replyApprovals? }可选

Threads 发布选项:replyControl 谁可以回复(everyone / followers_only / accounts_you_follow / mentioned_only / parent_post_author_only,缺省所有人);topicTag 话题标签(1–50 字,不能含 . 与 &);linkAttachment 链接卡片(http(s) 链接,只对纯文字帖生效,计入每帖 5 个链接的上限);replyApprovals 回复审批(true = 别人的回复要作者批准才公开,缺省关)。

clientRequestIdstring可选

幂等键(8–128 chars of [A-Za-z0-9_.:-]);推荐放在 Idempotency-Key 请求头,头与 body 都给时以头为准。publish 档必填。

调用规则

  • publish 档必须带 Idempotency-Key;draft / schedule 档有键就用。
  • 重试时带同一个键不会重复创建,响应会带 meta.replayed: true。
  • 发 TikTok 时 privacyLevel 必须由人选定;发 YouTube 时 title 必填。

响应

成功返回 HTTP 201,信封为 { data, meta };右侧(窄屏在本页末尾)给出了各状态码的示例。所有错误都是 { error: { code, message, params }, meta },按机器码处理而不是按 message 匹配,码表见 错误码。

状态码可能的错误码
400invalid_input
401unauthenticated
402plan_limit
403forbidden / workspace_not_found
404not_found
409no_account / needs_reauth / replay
429rate_limited
500internal
502platform_error
503external_writes_off

示例

请求
curl -X POST "https://popkit.loxily.com/api/v1/posts" \
  -H "Authorization: Bearer popkit_it_••••••••" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: acme-2026-09-21-001" \
  -d '{
  "action": "schedule",
  "content": "新功能上线:一次创作,发布到所有平台 🚀",
  "platforms": [
    "x",
    "instagram"
  ],
  "scheduledAt": "2026-09-21T18:00:00+08:00",
  "media": [
    {
      "kind": "image",
      "dataUrl": "https://storage.googleapis.com/…/cover.jpg"
    }
  ],
  "variants": [
    {
      "platform": "x",
      "content": "新功能上线 🚀 一次创作,发布到所有平台 → popkit.loxily.com"
    }
  ]
}'
响应
排期成功
{
  "data": {
    "postId": "pst_01J8ZK3R7QW6M2",
    "status": "scheduled",
    "scheduledAt": "2026-09-21T10:00:00.000Z",
    "deepLink": "https://popkit.loxily.com/calendar?post=pst_01J8ZK3R7QW6M2"
  },
  "meta": {
    "requestId": "3f9c1e2a-7d4b-4c1e-9a6f-0b2d8e5c7a11"
  }
}
MCP 接入文档