API 参考

Fresco 私人网页托管的全部接口，供 AI Agent 与脚本集成使用。

Base URL：https://longmarch.cloud/e

认证方式

Fresco 提供两种认证：

① 管理（Cookie 会话）

管理台 /setting 登录后获得会话 Cookie，用于完整管理操作（页面增删改、密钥管理、改密码）。

POST /api/login   # body: {"password":"管理密码"} → Set-Cookie: fr_session=...

② Agent（API Key）

Agent 部署用，无需登录密码。在管理台「API Key」区块创建密钥，请求头携带：

Authorization: Bearer fr_xxxxxxxxxxxxxxxx

每个密钥只能管理自己上传的页面（owner 隔离）。

注册与开始使用（对所有人开放）

Fresco 对所有互联网用户开放：访问 /e/register 免费注册，用邮箱 + 密码注册后立即获得专属 API Key（⚠️ 请立即保存，关闭页面后无法再次查看完整 Key，切勿泄漏）。

把 API Key 交给 AI Agent（把下面模板发给任意 Agent 即可自动部署）：

你是我的网页发布助手。请用以下凭据把我的内容发布到 Fresco 网页托管：
API Key（Bearer 认证）：<你的Key>
接口地址：https://longmarch.cloud/e/api/deploy
发布方法：POST 接口地址，请求头 Authorization: Bearer <你的Key> 与 Content-Type: application/json，
请求体 {"slug":"页面地址(英文)","title":"标题","html":"完整HTML内容"}（可选 description/image；slug 已存在需加 "overwrite": true）
页面地址：https://longmarch.cloud/e/<slug>。完成后把页面地址告诉我。

后续管理：所有管理（页面修改/暂停/删除/微调/限额）都在 Agent 中进行；也可用邮箱+密码登录 /e/setting 管理台手动管理自己的页面。每个用户只能管理自己的页面（隔离）；管理员拥有全局管理权限。

Agent 部署接口

以下接口用于 AI Agent 上传/管理内容，均需 Authorization: Bearer 认证。

POST/api/deployBearer

上传新页面。地址（slug）已存在时默认返回 409 错误（不论归属）；如需覆盖更新本密钥自己的页面，请传 "overwrite": true。

curl -X POST https://longmarch.cloud/e/api/deploy \
  -H "Authorization: Bearer fr_xxxx" \
  -H "Content-Type: application/json" \
  -d '{"slug":"my-page","title":"标题","html":"<h1>内容</h1>"}'

字段	类型	说明
`slug`	string	地址（1-64 位字母/数字/连字符/下划线，保留字除外）
`title`	string	标题（可选，缺省用 slug）
`html`	string	完整 HTML 内容
`overwrite`	bool	slug 已存在且归属本密钥时，传 true 覆盖更新（可选，默认 false）
`danmaku_enabled`	bool	是否开启弹幕（可选，默认 true）
`description`	string	页面描述（可选，≤200 字；用于微信等分享卡片的摘要）
`image`	string	分享卡片封面图 URL（可选，https 图片地址；缺省用 Fresco 默认图）

成功响应：

{"ok":true,"page":{"id":"...","slug":"my-page","url":"https://longmarch.cloud/e/my-page"},"action":"created"}

错误响应（err 字段写明原因）：

HTTP 409  {"ok":false,"err":"地址 my-page 已存在（本密钥托管）。如需覆盖更新，请在请求体加 \"overwrite\": true"}
HTTP 403  {"ok":false,"err":"地址 my-page 已被其他密钥（xxx）占用，无权覆盖"}
HTTP 400  {"ok":false,"err":"页面数超限：该密钥最多托管 5 个页面，当前已有 5 个"}
HTTP 400  {"ok":false,"err":"大小超限：该密钥托管总大小上限 100 MB，当前 98.12 MB，本次 1024.00 KB 将超出"}

GET/api/pagesBearer

列出当前密钥自己的全部页面。

curl https://longmarch.cloud/e/api/pages -H "Authorization: Bearer fr_xxxx"

POST/api/deploy/deleteBearer

删除当前密钥自己的一个页面。

curl -X POST https://longmarch.cloud/e/api/deploy/delete \
  -H "Authorization: Bearer fr_xxxx" \
  -H "Content-Type: application/json" \
  -d '{"slug":"my-page"}'

隔离规则：密钥只能覆盖/删除自己上传的页面；操作其他密钥的页面返回 403。

管理接口（Cookie）

POST/api/pagesCookie

手动新建页面（同 deploy，但 owner=admin，地址冲突会报错而非覆盖）。

POST/api/pages/deleteCookie

删除页面。body：{"id":"..."}

POST/api/pages/toggleCookie

暂停/恢复页面。body：{"id":"..."}

POST/api/pages/renameCookie

修改地址。body：{"id":"...","slug":"新地址"}

POST/api/pages/passwordCookie

设置/清除页面访问密码。body：{"id":"...","password":"访问密码"}（password 留空则清除）

密钥管理接口（Cookie）

GET/api/keysCookie

列出所有 API Key（名称、key、创建时间、最后使用时间）。

POST/api/keysCookie

新建 API Key。body：{"name":"agent-1"}

POST/api/keys/renameCookie

重命名密钥。body：{"key":"fr_...","name":"新名称"}

POST/api/keys/deleteCookie

删除密钥。body：{"key":"fr_..."}

POST/api/keys/limitsCookie

设置密钥限额。body：{"key":"fr_...","max_pages":5,"max_size_mb":100}。两个字段均为 0 或不传表示不限制；可在管理台密钥列表的「限额」按钮中可视化设置。

密钥限额规则

每个 API Key 可单独设置两类上限（不设置 = 无上限）：
· 页面数上限（max_pages）：该密钥托管页面的最大数量；
· 总大小上限（max_size_mb，MB）：该密钥全部页面内容大小的总和上限。
Agent 通过 /api/deploy 新建页面时若将超过任一上限，返回 400 并在 err 中写明原因（含上限值、当前用量）；覆盖更新（overwrite:true）同样受总大小上限约束。

分享卡片（og meta）

每个 HTML 托管页面自动注入微信/QQ 等社交平台识别的分享卡片 meta，粘贴链接即显示卡片。

og 标签	取值规则
`og:title`	页面标题（deploy 的 `title` 字段）
`og:description`	deploy 的 `description` 字段；未设置时自动提取页面正文前 60 字
`og:image`	deploy 的 `image` 字段（https 图片地址）；未设置时用 Fresco 默认图（"Fr" 字样的品牌图）
`og:url` / `og:type`	自动生成（页面地址 / website）

规范：页面自带 og:title 时不重复注入（尊重页面自定义）；og:image 建议 ≥300×300 的 https 图片；微信对同一 URL 的抓取结果有缓存，修改 meta 后需等缓存过期或加 ?v=x 参数验证。

人工微调（网页编辑器）

Agent 部署的页面可以交给「人」直接在浏览器里微调，无需重新生成整页。提供两种入口：

GET/api/editor/token?slug=my-pageBearer

为本密钥托管的页面生成一个单次微调地址（24 小时内有效，保存一次后自动失效）。建议 Agent 把该地址告知用户，让用户人工微调修改。

curl "https://longmarch.cloud/e/api/editor/token?slug=my-page" \
  -H "Authorization: Bearer fr_xxxx"

{"ok":true,"token":"...","url":"https://longmarch.cloud/e/editor?t=...","expires_hours":24,"hint":"微调地址 24 小时内有效，保存一次后自动失效"}

错误：403 页面不属于此密钥；404 页面不存在；401 密钥无效。

GET/editor?t=…公开（token）

打开 Monaco 编辑器：左侧编辑 HTML 源码、右侧实时预览（桌面/平板/手机宽度切换），Ctrl+S 保存。保存后该地址立即失效。

GET/editor?id=…Cookie

管理台编辑入口（页面列表「微调」按钮）：可反复保存；每次保存自动留存最近 5 个历史版本，支持一键还原（超出 5 版自动覆盖最早的）。

页面访问密码

POST/api/unlock公开

解锁设置了访问密码的页面。验证通过后设置 fr_access Cookie（24h 内免重复输入）。

curl -X POST https://longmarch.cloud/e/api/unlock \
  -H "Content-Type: application/json" \
  -d '{"slug":"my-page","password":"访问密码"}'

弹幕（浏览者互动）

每个 HTML 托管页面都自带弹幕系统：页面底部有发送栏（可拖动），浏览者可发送、开关弹幕。

GET/api/danmaku?slug=my-page公开

获取某页面的弹幕（最近 200 条）。

POST/api/danmaku公开

发送弹幕。body：{"slug":"my-page","text":"你好","color":"#ffffff"}（text ≤100 字符，color 缺省 #ffffff，每页最多 500 条）。

GET/api/danmaku/allCookie

列出所有弹幕（平铺，按时间倒序）。

POST/api/danmaku/deleteCookie

删除单条弹幕。body：{"id":"..."}

POST/api/danmaku/clearCookie

清空某页面全部弹幕。body：{"slug":"my-page"}