popkitpopkitAPI
中EN
内容

推荐封面

按内容的素材推荐封面:有视频就从视频里抽帧挑图,否则在 2 张以上的配图里挑首图,按推荐度排好(rank 1 最推荐)并附一句理由。视频要调两次:第一次触发抽帧(status 为 queued / running,约 10–30 秒),按 retryAfterSec 再调一次拿到 ranked;图文当场返回 ranked。同一份素材幂等,重复调用不会重复计费,也不扣 AI 月配额。只看内容的通用媒体,媒体必须已存在本站。本端点不改动内容,选好后用「设为封面」应用。

POST/api/v1/posts/{postId}/cover-suggestions
posts:write写档限流Idempotency-Key 可选

鉴权与护栏

  • 请求头 Authorization: Bearer <长期凭证>,凭证在设置页「接入外部系统 → 长期凭证」签发,见 鉴权与权限。
  • 凭证需带 scope posts:write;签发者在工作区里的角色也要允许该动作。
  • 限流:写档,每分钟 10 次(按凭证计),超出回 429 并带 Retry-After。
  • 幂等:带 Idempotency-Key 就按它去重,不带也能调。

路径参数

postIdstring必填

内容 id。

请求体(application/json)

languageenum: zh · en可选

推荐理由的语言;不给 = 中文,且不改写已有推荐的理由。给了且与已有理由的语言不同,会只重写理由、名次不变。

clientRequestIdstring可选

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

调用规则

  • 每个工作区每天最多为 50 条视频抽帧,超了回 rate_limited(params.reason = cover_daily_cap,retryAfterSec 到 UTC 次日零点)。
  • 候选图 7 天后清理;过期后再调一次会重新生成。

响应

成功返回 HTTP 200,信封为 { 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/pst_01J8ZK3R7QW6M2/cover-suggestions" \
  -H "Authorization: Bearer popkit_it_••••••••" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: acme-2026-09-21-001" \
  -d '{
  "language": "zh"
}'
响应
视频:抽帧中
{
  "data": {
    "postId": "pst_01J8ZK3R7QW6M2",
    "suggestionId": "3f2b9c1e-6d0a-4e8b-9a7c-5b1d2e3f4a60",
    "status": "queued",
    "sourceKind": "video",
    "engine": null,
    "candidates": [],
    "retryAfterSec": 5,
    "next": "frames are still being extracted from the video (usually 10–30 s); call suggest_covers again with the same postId in 5s"
  },
  "meta": {
    "requestId": "6a1d0c9e-2b7f-4e3a-8c5d-1f0e9b8a7c81"
  }
}
MCP 接入文档