发布指南
把视频、图片和文档发布到一个或多个平台,跟踪结果,以及定时发布。
所有平台都通过同一个接口发布: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>里,全部字段见该接口的参考页。
各内容类型的平台支持
| VIDEO | IMAGE(最多张数) | DOCUMENT | |
|---|---|---|---|
| TikTok | ✓ | ✓(35) | — |
| YouTube | ✓ | —(返回 400) | — |
| ✓ | ✓(10) | — | |
| ✓ | ✓(10) | — | |
| Threads | ✓ | ✓(20) | — |
| X | ✓ | ✓(4) | — |
| ✓ | ✓(1) | — | |
| LinkedIn(公司主页) | ✓ | ✓(20) |
平台支持的情况下,多张图片会发成轮播。
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.jsonIdempotency-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。