跳到正文
LumiPath API

发布指南

把视频、图片和文档发布到一个或多个平台,跟踪结果,以及定时发布。

所有平台都通过同一个接口发布:POST /api/v1/social-posts。一次请求可以同时发到多个平台,每个平台也可以发多个账号。

1. 先把素材传到 LumiPath

用 POST /api/v1/videos/upload 上传每个文件,然后把返回的 url 填进 mediaUrls。 平台从 LumiPath 的存储拉取素材,其中好几个(TikTok、X、Pinterest 和 LinkedIn 的视频,以及 LinkedIn 文档)会拒绝其他域名的地址。

素材上传限制
视频计入套餐的每日上传额度,超出返回 403 upload_limit_reached。
图片每张 8 MB。
文档(PDF)100 MB。

2. 组装请求

{
  "platforms": ["TIKTOK", "YOUTUBE"],
  "contentType": "VIDEO",
  "text": "文案 / 描述",
  "mediaUrls": ["https://videos.lumipath.cn/…/video.mp4"],
  "tiktokConnectionIds": ["<connectionId>"],
  "youtubeConnectionIds": ["<connectionId>"],
  "youtubeConfigs": [{ "connectionId": "<connectionId>", "title": "我的视频", "visibility": "unlisted" }]
}
  • platforms:可选 TIKTOK、YOUTUBE、INSTAGRAM、THREADS、X、PINTEREST、LINKEDIN、FACEBOOK。
  • 列出的每个平台,都要传对应的 <platform>ConnectionIds(例如 tiktokConnectionIds)。 大多数平台也可以改传 <platform>AccountNames,Pinterest 只接受 id。
  • contentType:VIDEO、IMAGE 或 DOCUMENT。
  • mediaUrls:1 到 35 个地址,VIDEO 只取第一个。
  • 按账号的选项放在 <platform>Configs 里(TikTok 的可见范围和互动设置、YouTube 的标题和可见性、Pinterest 的描述)。 各平台的高级设置放在 advanceConfig.<platform> 里,全部字段见该接口的参考页。

各内容类型的平台支持

VIDEOIMAGE(最多张数)DOCUMENT
TikTok✓✓(35)—
YouTube✓—(返回 400)—
Instagram✓✓(10)—
Facebook✓✓(10)—
Threads✓✓(20)—
X✓✓(4)—
Pinterest✓✓(1)—
LinkedIn(公司主页)✓✓(20)✓ PDF

平台支持的情况下,多张图片会发成轮播。

TikTok 可见范围

tiktokConfigs[].privacyLevel 必须是该创作者账号允许的值之一。不传时,LumiPath 使用该账号允许的第一个值。 传了账号不允许的值,这个账号会发布失败,错误信息里会列出允许的值。

LinkedIn PDF 文档

contentType: "DOCUMENT" 只用于 LinkedIn:platforms 必须恰好是 ["LINKEDIN"],mediaUrls 恰好一个 PDF(≤ 100 MB、≤ 300 页), 并且必须提供 advanceConfig.linkedin.documentTitle。

3. 发送请求,并带上幂等键

curl -X POST https://app.lumipath.cn/api/v1/social-posts \
  -H "Authorization: Bearer $LUMI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: campaign-42-video-1" \
  -d @post.json

Idempotency-Key 不是必填,但强烈建议带上。用相同的 Key 和相同的请求体再发一次,会返回第一次的响应(带 Idempotent-Replayed: true 头),不会重复发帖。

情况响应
Key 不是 1–200 个 [A-Za-z0-9:_.-] 字符400 INVALID_IDEMPOTENCY_KEY
相同 Key 的第一次请求还在执行409 IDEMPOTENCY_IN_PROGRESS,请先查询状态,不要盲目重发
相同 Key、不同请求体422 IDEMPOTENCY_KEY_REUSED

4. 读取即时结果

{
  "success": true,
  "results": {
    "TIKTOK": [{ "connectionId": "…", "status": "processing", "jobId": "6660a1…" }],
    "YOUTUBE": [{ "connectionId": "…", "status": "failed", "jobId": "6660a2…", "error": "YouTube token not found" }]
  }
}

results 是按平台分组的对象,每个平台下每个账号一条。每条都有 jobId。一次请求可能部分成功,请逐条检查。

条目 status含义
success已发布。
processing已受理,正在后台上传。视频通常都是这个状态。
failed没有发布,error 说明原因;errorCode: "ACCOUNT_UNHEALTHY" 表示账号被平台限制(见账号连接)。

5. 轮询最终结果

curl -X POST https://app.lumipath.cn/api/v1/social-posts/status \
  -H "Authorization: Bearer $LUMI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "jobIds": ["6660a1…", "6660a2…"] }'
{
  "results": {
    "TIKTOK": [
      { "jobId": "6660a1…", "connectionId": "…", "status": "success", "postId": "…", "postUrl": "https://…" }
    ]
  }
}
  • 每次最多 100 个 jobIds。不存在或不属于你的 id 返回 status: "not_found"。
  • 建议每 10–30 秒查一次,大视频可能要几分钟。
  • failed 的条目可能带 errorCode:PUBLISH_TIMEOUT 或 PUBLISH_STALLED。
  • stage 表示后台任务进行到哪一步:preparing → uploading → creating。 如果任务在 creating 阶段失败,帖子可能已经在平台上发出来了,重新发布前请先确认。

这个状态查询接口还没有出现在自动生成的接口参考里,以这里写的请求和响应为准。

定时发布

加上 scheduleAt 就是定时发布:

{ "...": "其余字段同上", "scheduleAt": "2026-12-01T09:00:00+08:00" }
  • ISO 8601 格式,必须带时区(Z 或 +08:00),时间在 1 分钟到 365 天之后。
  • 整个请求会立即校验,响应为 { "success": true, "scheduled": true, "scheduleJobId": "…", "scheduledAt": "…" }。
  • POST /api/v1/social-posts/schedule/status 传 { "scheduleJobIds": […] }(传 {} 则返回所有待执行的), 每条的 status 是 scheduled、firing、fired、failed 或 not_found。到 fired 后, publishJobIds 给出可以用 /social-posts/status 轮询的任务 id。
  • POST /api/v1/social-posts/schedule/cancel 传 { "scheduleJobId": "…" } 取消;已经在执行时返回 409,id 不存在返回 404。

本页目录