把内容 Agent 接进你的系统

快速开始

curl -X POST https://sarasvati.cn/api/v1/publish \
  -H "Authorization: Bearer svt_你的Key" \
  -H "Content-Type: application/json" \
  -d '{"brandId":3,"channels":["zhihu","toutiao"],"generate":true,"topic":"智慧公路的三个常见误区"}'

curl -H "Authorization: Bearer svt_你的Key" \
  https://sarasvati.cn/api/v1/manuscripts/128

AI Agent 接入

妙音的接口为 AI Agent 设计：首选托管 MCP Server（tools 化接入，无需手写 HTTP，见下一节）；REST 侧一份 openapi.json 就是完整的机器可读契约，llms.txt 是给 LLM 的能力索引。REST 接法：

读取 https://sarasvati.cn/openapi.json 了解妙音 OpenAPI，
然后用我的 API Key（Authorization: Bearer svt_xxx）
调用接口完成：<你的任务>

托管 MCP Server（推荐）

妙音托管了一个 MCP（Model Context Protocol）Server：第三方 AI Agent 以 tools 方式直接调用平台能力，无需手写 HTTP。 Endpoint：https://sarasvati.cn/mcp（POST，Streamable HTTP，无会话状态），认证与 OpenAPI 同一个 Key：Authorization: Bearer svt_xxx。 该 MCP Server 已上架魔搭 ModelScope、扣子（Coze）、百度千帆的 MCP 市场——在对应平台搜索「妙音」即可一键安装；手动配置方式如下。

claude mcp add --transport http sarasvati \
  https://sarasvati.cn/mcp \
  -H "Authorization: Bearer svt_xxx"

{
  "mcpServers": {
    "sarasvati": {
      "url": "https://sarasvati.cn/mcp",
      "headers": {
        "Authorization": "Bearer svt_xxx"
      }
    }
  }
}

工具清单（13 个）

只读工具（9）：数据范围与 OpenAPI 一致，严格按 Key 所属账号隔离。

写工具（4）：

端到端任务模板（submit_task_pack 示例）

对竞品「通用连接器」的差异：我们给的是完整内容 Agent 任务模板，而不是一个孤立的 publish 接口。 下面这段是 Claude / Cursor 里对挂好 MCP 的助手说的话，一条指令即可拿到整个闭环地图：

调用 sarasvati 的 submit_task_pack：
rawText = "给「妙音」品牌每周产出 1 篇面向中小企业主的内容 Agent 科普图文"
然后按返回的 workflow 逐步推进：
1. 我去控制台确认需求后，妙音 Agent 自动选题/生产/质检；
2. 提醒我手机审批；
3. 我通过后，对妙音频道和我的官网跑 preview_publish → confirm_publish；
4. 调 get_metrics 留下基线数据。

单元消耗只在内容生成/改写环节发生（按渠道计费的规则见上方「通用约定」）；确认需求前不扣费不执行，全过程可追溯。

发布两步规则与风控

• 先预览再确认：发布必须 preview_publish → confirm_publish 两步走；confirmCode 绑定账号、稿件与平台清单，30 分钟有效，过期需重新预览。
• 仅限 API 直发渠道：公众号（wechat）、妙音频道（sarasvati）、我的官网（official_site）。小红书/知乎/头条等为模拟发布通道（cookie 托管），有风控风险，请登录控制台人工审批发布。
• 认证档门槛：confirm_publish 要求账号已认证（基础版及以上且在有效期内）；试用账号可用全部只读工具与 submit_directive。
• 每日限额：同一账号 confirm_publish 每天最多成功 10 次。
• 不产生额外扣费：发布本身不扣单元，扣费只发生在内容生成/改写/配图环节。
• 与 REST 的分工：MCP 两步确认、每日限 10 次、仅限 3 个 API 直发渠道，适合 AI Agent 人机协作；系统间自动化建议直接用 POST /api/v1/publish——一次调用、按渠道计费（每日 20 次免费）、限流 30 次/分钟。
• 错误处理：业务错误通过工具结果的 isError: true 返回中文说明；响应头 x-units-remaining 随时回传当前单元余额。

5 分钟跑通全链路（复制粘贴即可）

这几个数字都来自本页文档，可逐一验证：13 个 MCP 工具 · 一次 submit_directive 让妙音 Agent 后台完成选题/生产/质检 · 两步 preview_publish → confirm_publish 完成发布与多渠道适配 ·get_metrics 回采查看/点赞/回复/分享。把下面这段话原样发给挂好 MCP 的 Claude / Cursor，就能跑完「提需求 → 生产 → 发布 → 看数据」闭环：

1. 调用 sarasvati 的 get_account 确认接入成功，并告诉我单元余额和认证档。
2. 调用 list_brands 列出我的品牌，选第一个启用的品牌。
3. 提交一条内容需求指令（submit_directive）：
   「结合我品牌的行业与调性，写一篇面向客户的科普图文，突出我们的专业能力」
4. 提示我：指令已进入控制台待确认，确认后妙音 Agent 会自动完成
   选题 → AI 生产 → 质检 → 生成多渠道适配稿件。
5. 稿件生成后：调用 list_manuscripts 找到最新稿件，跑 preview_publish
   预检 API 直发渠道，把预检结果和各平台适配情况汇报给我，等我确认。
6. 我确认后调用 confirm_publish 完成发布，再调 get_metrics 留下本次基线数据。

以上每一步都是真实的工具调用，没有任何演示模拟。第 4 步的生产由妙音 Agent 在平台内完成（约几分钟），你会在控制台和手机上收到审批提醒——人只拍板，Agent 干活。

通用约定

Base URL 与认证

响应格式

成功统一返回 { "ok": true, "data": … }；列表接口额外带分页字段；失败统一返回 { "ok": false, "error": "错误说明" } 并配对应 HTTP 状态码。

分页

列表接口统一支持 page（从 1 开始）与 limit（默认 20，最大 100）两个 query 参数。

错误码

POST/api/v1/publish

发布即服务：一次调用完成「内容生成/平台适配 → 审核质检 → 多渠道入队发布」，支持图文（article，默认）与视频（video）两种内容形态。每日前 20 个渠道发布免费（图视共享额度），超出按图文 0.5 / 视频 1.5 单元/渠道计费（详见计费与额度）。支持 Idempotency-Key 幂等重试。

内容形态与模式

请求体（JSON）

响应字段

示例 · 自带内容

curl -X POST https://sarasvati.cn/api/v1/publish \
  -H "Authorization: Bearer svt_你的Key" \
  -H "Content-Type: application/json" \
  -d '{"brandId":3,"channels":["zhihu","toutiao","wechat"],"title":"智慧公路的三个常见误区","content":"## 误区一……","images":["https://example.com/cover.png"]}'

示例 · 代为生成

curl -X POST https://sarasvati.cn/api/v1/publish \
  -H "Authorization: Bearer svt_你的Key" \
  -H "Content-Type: application/json" \
  -d '{"brandId":3,"channels":["zhihu","toutiao"],"generate":true,"topic":"智慧公路的三个常见误区","requirement":"1500 字左右，举 2 个真实项目例子"}'

示例 · 视频（自带成片 / 代为生成）

# 自带成片：发好看视频 + AcFun + 抖音
curl -X POST https://sarasvati.cn/api/v1/publish \
  -H "Authorization: Bearer svt_你的Key" \
  -H "Content-Type: application/json" \
  -d '{"brandId":3,"channels":["haokan","acfun","douyin"],"contentType":"video","videoUrl":"https://example.com/intro.mp4","title":"3 分钟看懂智慧公路","content":"视频简介/文案（选填）"}'

# 代为生成：AI 出分镜脚本并合成（异步，立即返回 manuscriptId）
curl -X POST https://sarasvati.cn/api/v1/publish \
  -H "Authorization: Bearer svt_你的Key" \
  -H "Content-Type: application/json" \
  -d '{"brandId":3,"channels":["douyin","bilibili"],"contentType":"video","generate":true,"topic":"智慧公路的三个常见误区"}'

示例 · 幂等重试

curl -X POST https://sarasvati.cn/api/v1/publish \
  -H "Authorization: Bearer svt_你的Key" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-20261017-001" \
  -d '{"brandId":3,"channels":["zhihu","toutiao"],"generate":true,"topic":"智慧公路的三个常见误区"}'
# 超时/断网后用同一 Key 原样重发：命中返回首次响应（带 idempotentReplay: true），不重复扣费

{
  "ok": true,
  "data": {
    "manuscriptId": 128,
    "taskIds": [901, 902],
    "perPlatform": {
      "zhihu": { "taskId": 901, "status": "queued" },
      "toutiao": { "taskId": 902, "status": "queued" }
    },
    "chargedUnits": 0,
    "freeQuotaUsed": 2,
    "freeQuotaRemaining": 18,
    "unitsRemaining": 2000,
    "status": "queued"
  }
}

GET/api/v1/me

验证 Key 并返回账号概要：名称、认证档位、到期时间、单元余额与各项单元单价。

响应字段

示例

curl -H "Authorization: Bearer svt_你的Key" \
  https://sarasvati.cn/api/v1/me

GET/api/v1/topics

选题清单：Agent 根据你的信源与品牌综合研判后产出的选题，按创建时间倒序。

请求参数

响应字段（data 数组项）

示例

curl -H "Authorization: Bearer svt_你的Key" \
  "https://sarasvati.cn/api/v1/topics?status=proposed&limit=10"

{
  "ok": true,
  "data": [
    {
      "id": 128,
      "title": "国庆假期高速出行预测与避堵指南",
      "status": "proposed",
      "score": 86,
      "source": "tavily-hot",
      "brand": { "id": 3, "name": "路信通" },
      "manuscriptId": null,
      "createdAt": "2026-09-25T09:12:00.000Z",
      "updatedAt": "2026-09-25T09:12:00.000Z"
    }
  ],
  "page": 1, "limit": 10, "total": 1, "hasNext": false
}

GET/api/v1/manuscripts

稿件列表：一篇稿件含多个平台适配版本，每个版本的发布状态、作品链接、失败原因都独立返回。

请求参数

响应字段（data 数组项）

platforms 数组项

示例

curl -H "Authorization: Bearer svt_你的Key" \
  "https://sarasvati.cn/api/v1/manuscripts?status=published&limit=5"

GET/api/v1/manuscripts/{id}

稿件详情：字段与列表一致，额外返回摘要与各平台版本的完整正文。稿件不存在或不属于当前账号时返回 404。

额外返回字段

示例

curl -H "Authorization: Bearer svt_你的Key" \
  https://sarasvati.cn/api/v1/manuscripts/57

GET/api/v1/effects

效果回采数据：已发布作品的查看、点赞、回复、分享。同一作品会被定期多次回采，每次回采一条记录——按时间排起来就是增长曲线。

请求参数

响应字段（data 数组项）

示例

curl -H "Authorization: Bearer svt_你的Key" \
  "https://sarasvati.cn/api/v1/effects?days=30&limit=50"

{
  "ok": true,
  "data": [
    {
      "manuscriptId": 57,
      "manuscriptTitle": "智慧公路的三个误区",
      "brand": { "id": 3, "name": "路信通" },
      "platform": "zhihu",
      "publishedUrl": "https://zhuanlan.zhihu.com/p/…",
      "views": 1286, "likes": 45, "comments": 7, "shares": 3,
      "fetchedAt": "2026-09-26T02:00:00.000Z",
      "error": null
    }
  ],
  "page": 1, "limit": 50, "total": 1, "hasNext": false, "days": 30
}

POST/api/v1/directives

提交内容需求指令。指令创建为「待确认」状态——本接口不扣单元，你在控制台「指令」页确认后，才按与手动创建完全相同的流程解析、计费、执行。

请求体（JSON）

响应字段

示例

curl -X POST -H "Authorization: Bearer svt_你的Key" \
  -H "Content-Type: application/json" \
  -d '{"rawText":"本周给路信通出 3 篇行业热点图文，发知乎和公众号","brandId":3}' \
  https://sarasvati.cn/api/v1/directives

{
  "ok": true,
  "data": {
    "directiveId": 42,
    "status": "pending_confirm",
    "confirmUrl": "https://sarasvati.cn/console/directives"
  }
}

POST/api/v1/leads

线索推入：已有自己的表单/CRM（金数据、问卷星、麦客、自有官网表单 webhook）时，把线索直接推进妙音线索库——与官网嵌入表单同口径校验、24h 去重、实时通知，控制台「销售线索」页统一跟进。不扣单元。

请求体（JSON）

响应字段

示例

curl -X POST -H "Authorization: Bearer svt_你的Key" \
  -H "Content-Type: application/json" \
  -d '{"name":"王先生","contact":"13800138000","note":"想了解飞轮套餐","brandId":3}' \
  https://sarasvati.cn/api/v1/leads

{
  "ok": true,
  "data": { "duplicate": false },
  "message": "线索已录入，控制台「销售线索」页可跟进"
}

Webhook 回调

不想轮询？在控制台「OpenAPI」页的「Webhook 回调」卡片里配置你自己的接收地址（可配多个，各自勾选订阅事件）， 事件发生时妙音会主动 POST 推送到你的服务。每个端点创建时生成独立的签名 Secret（只完整显示一次，请立即保存）。 回调地址仅支持 http/https 公网地址（内网地址会被拒绝）。

事件清单

投递格式

POST JSON 到你的回调地址；id 每条投递唯一，你的服务可据此去重（重试会复用同一 id 对应的新报文，同一事件以 data 内容为准）。

POST /webhooks/sarasvati HTTP/1.1
Content-Type: application/json
X-Sarasvati-Event: manuscript.published
X-Sarasvati-Signature: sha256=9f86d08…

{
  "id": "evt_3f9a1c…",
  "event": "manuscript.published",
  "createdAt": "2026-10-17T08:00:00.000Z",
  "data": {
    "manuscriptId": 128,
    "title": "智慧公路的三个常见误区",
    "platform": "zhihu",
    "publishedUrl": "https://zhuanlan.zhihu.com/p/…",
    "publishedAt": "2026-10-17T08:00:00.000Z"
  }
}

验签示例（Node.js）

import crypto from 'node:crypto'

function verifySarasvatiWebhook(secret, rawBody, signature) {
  const expected = 'sha256=' + crypto.createHmac('sha256', secret).update(rawBody, 'utf8').digest('hex')
  const a = Buffer.from(expected), b = Buffer.from(String(signature || ''))
  return a.length === b.length && crypto.timingSafeEqual(a, b)
}

// 在你的 HTTP 服务里（注意用原始请求体字符串，不要重新序列化 JSON）：
// const ok = verifySarasvatiWebhook(SECRET, rawBody, req.headers['x-sarasvati-signature'])
// if (!ok) return res.status(401).end()

重试策略与约定

• 成功判定：你的服务返回 2xx 即视为送达；其他状态码、连接失败、超时（10 秒）都会进入重试。
• 重试：失败后自动重试 3 次，间隔 1 分钟 / 5 分钟 / 15 分钟（指数退避）；仍失败则标记终态，不再投递。
• 超时：单次投递 10 秒超时——你的接收端应尽快返回 2xx，耗时处理请异步化。
• 投递日志：控制台「OpenAPI」页可查看每个端点最近投递的成功率与最近 20 条投递记录（状态 / 次数 / 错误原因）。

计费与额度

发布 API 的计费规则很简单：每日免费额度先用，超出按渠道计费，失败全退。

单元充值阶梯与消耗单价全表见 定价页；每笔扣费/退费在控制台「计费」页逐条可查。

典型场景

安全与配额

• Key 只存哈希：服务端只保存 Key 的 SHA-256，完整 Key 无法被找回——生成时务必立即保存，丢失请重置。
• 数据隔离：每个 Key 只能访问所属账号的数据；跨账号资源一律返回 404，不暴露存在性。
• 停用即失效：账号停用（如到期未续费）后 Key 同步失效，恢复后无需重新生成。
• 吊销与重置：怀疑泄露时在控制台「OpenAPI」页点「吊销」立即失效；「重置」生成新 Key 同时作废旧 Key。
• 写操作保护：提交指令创建后为「待确认」，控制台确认前不扣费不执行；发布接口只对成功入队的渠道计费，失败自动退还，杜绝程序异常刷量。
• 频率限制：发布接口同一 Key 30 次/分钟（超出 429）；查询类接口建议轮询不低于 1 分钟一次，列表单页最大 100 条，请用分页遍历。

常见问题

开发者支持

接入中遇到任何问题，有三条通道——优先提工单，响应最快：

路线图

• 视频发布失败渠道一键重发；数字人口播成片
• 细粒度 Key 权限：只读 / 读写分离，多 Key 管理

有接口需求？在控制台「工单」里提，被采纳有单元奖励。