AGENT API · /api/v1

把发布交给智能体：Bearer Token 一条通道走完

智能体通道与网页工作台共用同一账号体系、同一配额池：在工作台「设置 → API Token」创建令牌后，用 Authorization: Bearer 头调用 /api/v1/*，即可完成选题、写稿、排版、查询、公众号草稿箱发布，以及文章提取、B站字幕、OCR 采集与 WordPress 多渠道发布。缺参数时平台不会瞎猜，会返回 needs_input 让智能体转问人。

Base URL /api/v1 认证 Bearer Token 限流 120 次/小时/Token 格式 JSON · no-store

01 · QUICKSTART

快速开始

STEP 1

创建 Token

登录工作台 → 设置 → API Token → 新建，选择所需 scopes，创建后立即复制明文。

STEP 2

带 Token 调接口

所有请求带 Authorization: Bearer 头。先用 capabilities 确认配额与可用能力。

STEP 3

发布或继续询问

参数齐备直接返回结果；缺账号 / 排版 / 凭证时返回 needs_input，问完人带参重调。

curl https://你的域名/api/v1/capabilities \
  -H "Authorization: Bearer zfr_xxxxxxxxxxxx"

返回 {"success": true, "data": {...}} 即接入成功。Token 明文只在创建成功那一次响应里出现，之后任何界面与接口都只显示掩码（前4+****+后4），请妥善保存。

02 · AUTH

认证方式

每个请求都携带 HTTP 头：Authorization: Bearer zfr_…。缺失或无效一律返回 401。

Authorization: Bearer zfr_a3f8Kd92mQ7vBn4xLp0w

创建与保管

入口：工作台 → 设置 → 「API Token · 智能体通道」卡；创建 / 列表 / 吊销都在同一处。
明文仅创建成功这一次响应返回；之后列表里只有 prefix 掩码（前4+****+后4）。
令牌随时可吊销（revoke），吊销后立即失效。
Token 归属现有工作台账号：没有第二套账号体系，用量计入同一配额池。

Scopes

Scope	含义	覆盖端点
`read`	查询类能力	capabilities / accounts / articles 列表 / article 详情
`write`	出题、生成成稿与内容采集	POST /api/v1/topics、POST /api/v1/articles、POST /api/v1/extract/wechat、POST /api/v1/extract/bilibili、POST /api/v1/ocr
`publish`	发布与凭证	POST /api/v1/publish/wechat、POST /api/v1/publish/wordpress、POST /api/v1/credentials

scope 不足的请求返回 403。建议按最小权限发放：只读报表用 read，出题与自动写稿加 write，需要发布再加 publish。

03 · CONVENTIONS

通用约定

项	约定
成功响应	`{"success": true, "data": ...}`
失败响应	`{"success": false, "error": "中文可读文案"}`
缓存	所有响应均 `no-store`
身份	Token 即工作台用户（users 表），与 cookie 会话同一身份，绝无第二套账号体系
密钥纪律	AppSecret / API Token 明文只出现在「创建成功」这一次响应里，其余任何响应只出现掩码（前4+****+后4）

04 · ENDPOINTS

接口列表

以下 12 个端点与线上实现一一对应；请求体均为 JSON。

GET /api/v1/capabilities scope: read

返回当前 Token 的能力清单：可用 scopes、写稿与选题配额（used/limit）、writing_ready（写作运行时是否就绪）以及全部端点说明（method/path/desc）。

{
  "success": true,
  "data": {
    "scopes": ["read", "write", "publish"],
    "quota": {
      "articles": { "used": 1, "limit": 3 },
      "topics":   { "used": 2, "limit": 10 }
    },
    "writing_ready": true,
    "endpoints": [
      { "method": "GET",  "path": "/api/v1/capabilities", "desc": "…" },
      { "method": "POST", "path": "/api/v1/articles",     "desc": "…" }
    ]
  }
}

GET /api/v1/accounts scope: read

返回当前用户名下全部公众号账号（与工作台 list_accounts 原样一致）。

{
  "success": true,
  "data": {
    "accounts": [
      {
        "id": "<account_id>",
        "display_name": "<公众号显示名>",
        "content_domain": "medical_science",
        "positioning": "<一句话定位>"
      }
    ]
  }
}

POST /api/v1/topics scope: write

按账号生成候选选题。与工作台 /api/studio/topics 同一内部调用：选题配额、错误文案完全一致。返回 {"topics":[{title,angle}...]}。

请求体：{ "account_id": "<account_id>", "count": 3 }（count 可选）

POST /api/v1/articles scope: write

生成一篇成稿。与工作台 /api/studio/write 同一配额链（reserve → write → commit，失败 release，失败不扣额）。

请求体：

{ "account_id": "<account_id>", "topic": "可选，指定题目", "topic_kind": "热点|科普", "style": "可选，排版样式 id" }

返回 data：成稿对象，含 path / folder / cover_file / title 等字段

提示：排版样式 id 共 5 套：classic_medical、medical_emphasis、night_cinema、paper_column、opinion_card，与工作台一致。

GET /api/v1/articles?limit= scope: read

查询最近成稿列表：{"articles": […最近 N 条…]}（与工作台 list_articles 一致，limit 可选）。

GET /api/v1/article?file=&folder= scope: read

查询单篇成稿内容。返回 {"title", "markdown", "html", "style"}；html 由 core/publish_layouts 按 style 排版生成。file/folder 走与 /api/studio/preview 相同的安全校验（防目录穿越）。

POST /api/v1/publish/wechat scope: publish

上传微信草稿箱。参数：{ file, folder?, account_id?, style?, appid?, appsecret?, persist? }。

缺 account_id / style / 凭证时，返回 needs_input（一次返回全部缺失项，见下一节）。
请求带 appid+appsecret 时，先保存凭证再继续；带 persist:true 表示长期托管。
参数齐备后走与工作台一致的 upload_article_draft 流程（需同名 .jpg 封面），成功返回 {"status":"ok","media_id","title"}。
微信 errcode 转可读文案（如 40164 会提示把服务器 IP 加入公众号 IP 白名单）。

POST /api/v1/extract/wechat scope: write

提取微信公众号文章。请求体：{ "url": "https://mp.weixin.qq.com/s/…" }；返回 {url, title, content, images}（content 为正文纯文本，图片位置以 [图片] 标记；images 为 {alt, src} 列表）。仅接受 mp.weixin.qq.com 的 https 链接，非法链接或提取失败返回 400 中文文案。

POST /api/v1/extract/bilibili scope: write

提取 B站视频字幕。请求体：{ "url": "https://www.bilibili.com/video/BV…" }（支持分享文案与分P ?p=2）。自动使用已保存的 B站 Cookies（通过 /api/v1/credentials 提交 bilibili_cookies），部分视频必须登录后才能读取字幕。返回 {bvid, cid, title, part_title, page, text, type, language, …}。

POST /api/v1/ocr scope: write

百度 OCR 识别图片文字。请求体二选一：{ "image_base64": "…" } 或 { "image_url": "https://…" }。未配置密钥返回 400 并提示通过 credentials 提交 baidu_ocr。返回 { "text": "按行拼接的识别文本", "words_result": […百度原始结果…] }。

POST /api/v1/publish/wordpress scope: publish

发布文章到 WordPress 站点（XML-RPC wp.newPost，publish 状态）。请求体：{ "title": "…", "content": "…", "category": "可选", "tags": "逗号分隔，可选" }；category 未传时使用站点默认分类。

站点未配置 → HTTP 200 + needs_input（key 为 wordpress），指引通过 /api/v1/credentials 提交 wordpress 节后重调。
成功返回 { "post_id": …, "link": "文章链接" }；站点不可达、用户名或应用密码无效返回 400。

POST /api/v1/credentials scope: publish

保存微信凭证与扩展配置，字段可任意组合一次提交：

微信凭证：{ "appid": "…", "appsecret": "…", "persist": false }（persist 可选，true 表示长期托管、不再 24 小时过期）。
WordPress 站点：{ "wordpress": { "url": "…", "username": "…", "password": "…", "category": "可选" } }（网页登录密码不能直接用，需要应用密码）。
百度 OCR：{ "baidu_ocr": { "api_key": "…", "secret_key": "…" } }。
B站 Cookies：{ "bilibili_cookies": "SESSDATA=…; bili_jct=…" }（整串浏览器 Cookie）。

{
  "success": true,
  "data": {
    "configured": true, "persist": false, "appid": "wx1a****2b3c",
    "integrations": {
      "wordpress": { "url": "https://…", "username": "…", "password": "abcd****wxyz", "category": "" },
      "bilibili_cookies": "SESS****DATA",
      "baidu_ocr": { "api_key": "abcd****wxyz", "secret_key": "abcd****wxyz" }
    }
  }
}

密钥纪律：凭证保存后，任何响应只回显掩码（前4+****+后4）：AppID、WordPress 密码、百度 OCR 密钥与 B站 Cookies 一律掩码，明文永不回显。掩码原样传回不会被当成新密钥，平台会保留已存明文。

05 · NEEDS_INPUT

needs_input 反问式发布

调 /api/v1/publish/wechat 时如果缺少 account_id、style 或微信凭证，平台不会失败，而是返回 HTTP 200 + needs_input，并在 questions 里一次列出全部缺失项。智能体把问题转述给人，拿到答案后把参数补进请求体重调即可。

{
  "success": true,
  "data": {
    "status": "needs_input",
    "questions": [
      {
        "key": "account_id",
        "question": "发到哪个公众号？",
        "options": [
          { "value": "<account_id>", "label": "<公众号显示名>" }
        ]
      },
      {
        "key": "style",
        "question": "用哪套排版？",
        "options": [
          { "value": "classic_medical",  "label": "经典医疗" },
          { "value": "medical_emphasis", "label": "医疗强调版" },
          { "value": "night_cinema",     "label": "夜谈电影感" },
          { "value": "paper_column",     "label": "纸感专栏风" },
          { "value": "opinion_card",     "label": "观点卡片风" }
        ]
      },
      {
        "key": "credentials",
        "question": "该账号还没有微信凭证（或已过期），请提供 AppID 与 AppSecret，并在重调时带上 appid/appsecret/persist 字段",
        "options": []
      }
    ]
  }
}

account_id 缺失必问；style 缺失才追加；凭证缺失且请求未带 appid/appsecret 时才追加 credentials 问题。
options 给出全部可选项（value/label），credentials 类开放问题 options 为空数组。
问完人后重调：把 account_id / style / appid / appsecret / persist 一并放进请求体，齐备即直接发布。
/api/v1/publish/wordpress 同理：站点未配置时返回 key 为 wordpress 的开放问题（options 为空数组），按问题文案提交 credentials 后重调。

设计意图：智能体不知道的事就让平台反问，绝不替人猜默认值瞎发。

06 · ERRORS

错误码

状态码	含义	处理建议
400	参数不合法（ValueError，如缺少 account_id、file/folder 非法）	按 `error` 文案修正请求体后重试
401	未认证：缺少或无效的 Bearer Token（含已吊销）	检查 `Authorization` 头；Token 被吊销就去工作台重新创建
403	scope 不足：Token 未包含该端点所需 scope	换用带对应 scope 的 Token，或在工作台新建
429	限流或配额用完：Token 超 120 次/小时，或当日写稿/选题配额用完	等待窗口恢复，或次日再用；配额见 capabilities
500	未知异常	稍后重试；持续出现请携带时间点反馈

所有错误响应统一为 {"success": false, "error": "中文可读文案"}，可直接把 error 展示给用户或智能体。

07 · QUOTA

配额说明

同一配额池：Token 调用与工作台人工操作共用同一用户配额，接口不会绕过限额。
写稿与选题分开计：articles 与 topics 各有每日配额，默认写稿 3 篇/日、选题 10 次/日（管理端可调），GET /api/v1/capabilities 实时可查。
失败不扣额：写稿走 reserve → write → commit 配额链，中途失败自动 release。
Token 限流：每 Token 120 次/小时（按滑动窗口计），超出返回 429；建议智能体按需调用，不要轮询刷接口。