火兔矩阵 HTTP Skill

全部接口：POST /controller//，Content-Type: application/json，请求体 JSON 直接作为方法参数。

前置条件

• 火兔矩阵客户端已启动，账号已登录（partitionId 非空、offline=false）
• 素材用绝对路径；图文最多 9 张
• 端口占用会顺延，实际端口看应用日志
• 发布是长任务（20~90s），HTTP 客户端 timeout ≥ 180s

平台对照

云端标记发布状态时的平台码：小红书 xhs、抖音 dy、快手 ks、视频号 sph、淘宝光合 tb、小绿书 xls、百家号 bjh、今日头条 jinritoutiao。

1. 列账号

POST /controller/account/loadAccounts     Body: {}

返回 { list: [{ id, name, platform, partitionId, offline, avatar, group }, ...], groups: [...] }。

可用账号筛选：platform === 'xxx' && !offline && partitionId。

2. 发布一条内容

POST /controller/publish/publishContent

Body：

{
  "accountId": "xhs_xxx",
  "content": {
    "publishType": "image",
    "title": "标题",
    "text": "正文 #话题1 #话题2",
    "images": ["E:/path/1.jpg", "E:/path/2.jpg"],
    "hideWindow": false
  }
}

返回 { success, error?, accountName }。

平台补充：

• 小绿书不支持视频；传 video 会返回失败。传定时时间会自动改为立即发布。
• 百家号支持图文/视频和定时，定时范围是当前时间 +1 小时到 +7 天。
• 今日头条支持微头条图文/视频；微头条图文不支持网页定时，会自动改为立即发布，视频发布支持定时。

3. 云端发布（拉未发作品直接发）

从火兔工具箱远端拉 is_release=0 的作品发布，发完自动标记已发。无需 UI 建任务。

POST /controller/publish/publishCloudWorks

Body：

{
  "accountId": "xhs_xxx",
  "count": 1,
  "keyword": "",
  "convertToVideo": false,
  "musicFolderPath": "",
  "imageDuration": 3,
  "transition": "random",
  "hideWindow": false
}

前置：用户已登录火兔工具箱（本地 auth.json 有 token），否则返回 未登录火兔工具箱。

返回：

{
  "success": true, "accountId": "xhs_xxx",
  "total": 2, "ok": 2, "failed": 0,
  "results": [{ "workId": 101, "title": "...", "status": "submitted", "accountName": "..." }]
}

自然语言映射：

> 语义是"发几条就几条，发完即标记已发"。重复调会继续发更多未发作品，不会重复。

4. 养号

给账号做自动浏览 / 点赞 / 收藏，仅支持小红书 / 抖音 / 快手。全局单任务——一次只能跑一组养号。

4.1 启动

POST /controller/marketing/startNurture

Body：

{
  "accounts": [
    { "id": "xhs_xxx", "name": "昵称", "platform": "小红书", "partitionId": "xxx" }
  ],
  "config": {
    "targetCountMin": 10,
    "targetCountMax": 20,
    "likeRate": 0.6,
    "bookmarkRate": 0.3,
    "dwellMinMs": 3000,
    "dwellMaxMs": 8000,
    "gapMinMs": 2000,
    "gapMaxMs": 5000,
    "showWindow": true
  }
}

accounts：直接传 loadAccounts 返回的账号对象（必含 partitionId 和 platform）。不支持的平台（视频号/淘宝光合/小绿书/百家号/今日头条）会被后端自动丢弃。

config 字段：

返回 { success, error?, status }。常见错误：

• 已有养号任务在运行，请先停止 — 先调 stopNurture
• 未选择任何账号 / 所选账号均不支持养号 — 过滤 / 平台不支持

4.2 查询状态

POST /controller/marketing/getStatus    Body: {}

返回 { success, status }，status 形如：

{
  "running": true,
  "accountsTotal": 3, "accountsDone": 1,
  "currentAccountName": "昵称", "currentPlatform": "xhs",
  "startedAt": 1716000000000,
  "config": { /* ... */ },
  "lastSummary": { "browsed": 12, "liked": 7, "bookmarked": 3, "failed": 0 }
}

currentPlatform 是简写：xhs / dy / ks。

4.3 停止

POST /controller/marketing/stopNurture  Body: {}

设置停止标记，当前账号跑完后退出（不会立即杀进程）。返回 { success, status }。

4.4 自然语言映射

5. AI 生成文案

POST /controller/publish/aiGenerateText
Body: { "prompt": "根据标题\"xxx\"生成小红书风格正文" }

返回 { success, text }。依赖用户在"参数设置"配过 AI Key。

典型流程

发一条图文：loadAccounts 找目标账号 id → 构造 content → publishContent。

批量发：loadAccounts 过滤 → 循环 publishContent，每次间隔 5~15s，避免同时开多个浏览器。

养号：loadAccounts 过滤支持平台 + 在线 → startNurture → 按需 getStatus 轮询或 stopNurture。

错误速查

示例 curl

# 列账号
curl -sX POST http://127.0.0.1:7071/controller/account/loadAccounts \
  -H 'Content-Type: application/json' -d '{}'

# 发图到小红书
curl -sX POST http://127.0.0.1:7071/controller/publish/publishContent \
  -H 'Content-Type: application/json' --max-time 300 \
  -d '{"accountId":"xhs_xxx","content":{"publishType":"image","title":"t","text":"正文 #话题","images":["E:/a.jpg"]}}'

# 发一条云端作品
curl -sX POST http://127.0.0.1:7071/controller/publish/publishCloudWorks \
  -H 'Content-Type: application/json' --max-time 600 \
  -d '{"accountId":"xhs_xxx","count":1}'

# 启动养号
curl -sX POST http://127.0.0.1:7071/controller/marketing/startNurture \
  -H 'Content-Type: application/json' \
  -d '{"accounts":[{"id":"xhs_x","name":"n","platform":"小红书","partitionId":"p"}],"config":{}}'

# 看养号进度
curl -sX POST http://127.0.0.1:7071/controller/marketing/getStatus \
  -H 'Content-Type: application/json' -d '{}'

注意

• 不要并发同一账号调 publishContent，会抢同一浏览器实例
• 不要并发启动养号任务，全局只跑一个
• host 固定 127.0.0.1，无鉴权，跨机需自己加反代+鉴权，不要改 0.0.0.0
• 实时日志 emit 到主窗口，HTTP 只能拿到最终结果