封阳智稿 API 文档

认证、来源与安全

v1 业务 API 使用 Authorization: Bearer <API_KEY>。API Key 只能访问被授予的公众号，必须具有对应的 drafts:read 或 drafts:write 权限。

管理台使用 HttpOnly、SameSite=Strict Cookie。带 Cookie 的非 GET 管理请求必须带 X-CSRF-Token，令牌来自 GET /api/session 或登录响应；浏览器发出的请求来源必须与 PUBLIC_ORIGIN 完全一致。因此管理台必须从设置的正式 HTTPS 域名登录，不能在其他域名、IP 地址或带路径的来源登录。

创建草稿必须传 Idempotency-Key。同一在途请求的网络重试复用该值；如果创建结果不明，先查询任务，不能自动用新 key 再创建草稿。

数据约定

第一版每次任务只允许一个 articles 元素。将任意公共 HTTPS 图片直链登记后，在正文中引用 asset://<asset_id>。服务不会把图片落盘；接口错误统一为：

{"error":{"code":"...","message":"...","details":{}}}

任务状态：queued、processing、submitting、verifying、succeeded、failed、needs_review。

图片消息 newspic

同一草稿接口支持独立的图片消息：正文使用纯文本 content，图片先登记，再用有序 image_asset_ids 列表提交 1–20 张，第一张为封面。标题最多 32 字符（微信限制），正文最多 20000 字符（本平台限制）。不接收 HTML、digest、独立封面、裁剪或商品标签。作者字段只对 news 有效；图片消息不接收 author，需要署名请写入正文。原有 news 请求保持兼容。预览为纵向校对视图，实际滑动展示与裁剪需在微信后台手机预览中确认。

{"account_id":"acct_...","articles":[{"article_type":"newspic","title":"图片消息标题","content":"第一行纯文本\n第二行纯文本","image_asset_ids":["asset_00000000000000000000000000000001"]}]}

先预检，再固定幂等键创建一次草稿任务。结果未知时查询原任务；仅写草稿，不发表或群发。

GET/v1/accounts

返回当前 API Key 可使用的公众号账号；管理员会看到全部账号。

{"items":[{"id":"acct_...","name":"公众号","appid":"wx...","status":"read_ready","last_error":null}]}

POST/v1/assets

二进制图片上传已全局拒绝，错误码为 IMAGE_LINK_REQUIRED。请先上传至你选择的图床，再登记 HTTPS 直链。

POST/v1/assets/from-url

登记任意公共 HTTPS 封面或正文图片直链，无需指定图床平台或域名白名单。请求 JSON：{"url":"https://images.example.com/image.jpg"}；需要 drafts:write 权限。服务只保存链接与校验得到的元数据，返回的 url 是需要认证的同站预览地址。

{"asset_id":"asset_...","mime":"image/png","size":12345,"width":800,"height":600,"warnings":[],"url":"/v1/assets/asset_..."}

GET/v1/assets/{asset_id}

通过同站受控代理读取已登记的图片。该接口也需要认证；使用 API Key 时只能读取该 API Key 自己登记的图片，管理员可读取全部图片。

POST/v1/draft-jobs/validate

校验并生成安全预览，不创建微信草稿。第一版 articles 只能包含一篇。

{"account_id":"acct_...","articles":[{"title":"标题","author":"可选","digest":"可选","content_html":"<p>正文</p>","cover_asset_id":"asset_..."}]}

{"valid":true,"warnings":[],"preview_html":"<p>正文</p>"}

POST/v1/draft-jobs

创建草稿任务。请求体与校验接口相同，额外必填请求头 Idempotency-Key（8–128 个可见 ASCII 字符）。

{"job_id":"job_...","status":"queued","status_url":"/v1/draft-jobs/job_..."}

GET/v1/draft-jobs

返回当前调用方可读取的最近 100 个任务。

{"items":[{"job_id":"job_...","title":"标题","account_id":"acct_...","account_name":"公众号","status":"succeeded","stage":"verified","created_at":"...","updated_at":"...","error":null,"warnings":[],"wechat_media_id":"...","verified":true}]}

GET/v1/draft-jobs/{job_id}

读取单个任务详情；响应与列表项一致，并可能包含 preview_html。

GET/v1/drafts/{draft_id}

按任务 ID 读取已有微信草稿标识的草稿记录；没有微信草稿标识或无访问权限时返回 404。

管理接口摘要