API 文档
使用 API Key 创建书籍、更新章节和上传图片。
连接与鉴权
API 根地址:https://life.starfold.tech/api/v1。
私有书籍接口使用 HTTP 请求头 Authorization: Bearer YOUR_API_KEY。JSON 请求使用 Content-Type: application/json。不要把密钥放在 URL 查询参数里。API Key 调用不需要 Cookie 或 Origin 请求头。
在「设置 → API Key」创建密钥,并妥善保存。完整密钥只显示一次,之后可在设置中查看前缀、有效期和最近使用时间,或撤销不再使用的密钥。有效期可选 30、90 或 365 天;每个账号最多 20 个有效密钥,所有密钥合计最多每分钟 60 次请求。
每个 API Key 都能调用本页列出的全部开放用户 API,不需要选择权限。它只能操作你的账号有权访问的书籍,不能访问其他账号的私有内容,也不能管理账号、家庭或其他密钥。
以下示例使用环境变量保存连接地址和密钥。可在 Bash 或 Zsh 终端中先执行这些命令,再粘贴密钥并按回车;密钥输入不会回显:
export LIFE_BOOK_API_URL="https://life.starfold.tech/api/v1"
read -r -s LIFE_BOOK_API_KEY
export LIFE_BOOK_API_KEY可用接口
以下路径都相对于 API 根地址。
| 方法 | 路径 | 用途 |
|---|---|---|
| GET | /workspaces | 列出当前账号可访问的工作区 |
| GET | /studio/books | 列出自己的书架及有权访问的书籍 |
| POST | /studio/books | 创建书籍草稿 |
| GET | /studio/books/{id} | 读取草稿与最新 revision |
| PATCH | /studio/books/{id} | 更新书籍,带上 revision |
| DELETE | /studio/books/{id} | 删除书籍;需要书籍所有者权限 |
| POST | /studio/books/{id}/submit | 提交审核,不是直接公开 |
| POST | /studio/books/{id}/withdraw | 撤回发布 |
| POST | /studio/books/{id}/media/uploads | 申请上传图片或视频 |
| POST | /studio/media/{asset}/transfer | 传输不超过 8 MiB 的原始文件字节 |
| POST | /studio/media/{asset}/parts/{part}/transfer | 大文件分片传输,part 从 1 开始 |
| POST | /studio/media/{asset}/complete | 完成并验证上传 |
| POST | /studio/media/{asset}/download | 获取临时下载地址 |
公开阅读接口 GET /books 和 GET /books/{slug} 不需要 API Key。它们只返回已通过审核的版本,不会暴露草稿。
第一次创建一本书
先获取工作区:
curl --fail-with-body "$LIFE_BOOK_API_URL/workspaces" \
-H "Authorization: Bearer $LIFE_BOOK_API_KEY"响应为 {"items":[...]}。选择 kind=personal、role=owner 的工作区,并把它的 id 填入下面的 workspace_id。这里只使用虚构示例,请按自己的真实材料修改。
把请求保存为 book.json:
{
"workspace_id": "替换为你的工作区 UUID",
"slug": "my-memory-example-20261005",
"subject_kind": "human",
"original_locale": "zh-CN",
"visibility": "private",
"location_basis": "historical_anchor",
"region": "undisclosed",
"latitude": 0,
"longitude": 0,
"authorization": {
"basis": "self",
"subject_living": true,
"subject_consent": true,
"statement": "仅用于演示的虚构人物"
},
"document": {
"name": "示例人物(虚构)",
"title": "那些值得记住的小事",
"dek": "从一个日常片段开始。",
"epitaph": "",
"cover": "",
"location_name": "",
"life_dates": {
"birth": {"precision": "unknown", "value": ""},
"end": {"precision": "present", "value": ""}
},
"chapters": [
{
"id": "chapter-1",
"title": "第一段回忆",
"blocks": [
{"id": "text-1", "type": "text", "text": "这里写下你的真实回忆。示例文字不代表真实人物经历。"}
]
}
],
"timeline": [],
"media": [],
"sources": []
}
}发送创建请求:
curl --fail-with-body "$LIFE_BOOK_API_URL/studio/books" \
-H "Authorization: Bearer $LIFE_BOOK_API_KEY" \
-H "Content-Type: application/json" \
--data-binary @book.json成功返回 201,响应包含 id、revision、publication_status 和 document。默认工作流建议显式使用 visibility=private;未提交审核的内容不会出现在探索页。网页编辑地址为 /zh-CN/studio/books/{id}。
创建字段
| 字段 | 规则 |
|---|---|
workspace_id | 当前账号具有编写权限的工作区 UUID |
slug | 全站唯一,2–80 字符,只用小写英文字母、数字和连字符;建议带随机后缀 |
subject_kind | human 或 pet |
original_locale | zh-CN、en、es、hi、ar |
visibility | private、unlisted、public |
location_basis | historical_anchor、publication_place、death_place |
region | 未选城市时使用 undisclosed;发布前填写实际地区,如 Asia |
latitude / longitude | 城市级坐标,纬度 -90–90,经度 -180–180 |
authorization.basis | self、family、estate、pet_owner、institution、public_figure_editorial |
授权信息必须真实;不要把「公开人物」或「家人」当成自动取得授权。在世人物应如实填写同意状态;未成年人还需监护人同意。
书籍内容结构
| 内容 | 写法 |
|---|---|
| 姓名与书名 | document.name 最多 120 字,title 最多 200 字;提交审核时不可为空 |
| 简介与封面短句 | dek 是简介,epitaph 是封面短句,后者最多 1000 字 |
| 封面 | cover 填自己的已验证媒体地址,如 /api/v1/media/{asset}/content;留空使用默认封面 |
| 章节 | chapters 为 1–30 章;每章有唯一 id、标题和 blocks |
| 正文块 | type 为 text、quote、image、video 或 timeline_event;每个块 id 在整本书中唯一 |
| 文字 | 单个块 text 最多 20000 字;每章最多 200 块 |
| 时间轴 | timeline 最多 100 项,每项含 year、title、detail |
| 来源 | sources 最多 100 项,每项含 title 和 HTTP(S) url |
| 图片与视频 | media 最多 200 项,每项含 id、type、src、alt、caption、creator、license、source_url |
日期写在 life_dates.birth 与 life_dates.end 中。precision 可为 unknown(value 为空)、year(如 1985)、date(如 1985-06-12);结束时间另支持 present(value 为空)。时间不详时不要猜测。
图片块通过 media_id 引用 media 中的 id。普通文字不需要 rich_content;从网页读取到该字段时,请在更新时保留,避免丢失已有格式。整个 document 不得超过 2 MiB。
修改书籍:先读取,再更新
先 GET 书籍,取得最新 revision 和整个 document。修改需要变化的部分,保留其他章节、图片、来源和 rich_content。PATCH 不是对 document 的局部合并,它会替换整个 document。
{
"revision": 1,
"visibility": "private",
"document": {
"name": "示例人物(虚构)",
"title": "更新后的书名",
"chapters": [
{"id": "chapter-1", "title": "第一段回忆", "blocks": [{"id": "text-1", "type": "text", "text": "新的内容。"}]}
],
"timeline": [],
"media": [],
"sources": []
}
}成功返回 200 和递增的 revision。若返回 409,说明版本已改变或正在审核;请重新读取并比较修改,不要盲目覆盖。待审核版本会锁定编辑。
更新城市时,在 PATCH 中加入 location:包含 basis、region、latitude、longitude,并在 document.location_name 保存城市名称。可在网页选择城市,也可使用 GET /api/cities?q=北京&locale=zh-CN 获取建议;此建议接口位于网站根地址,不在 v1 中。
上传图片与设置封面
- POST
/studio/books/{id}/media/uploads,JSON 包含 filename、content_type、size、rights_basis,后者选 owned、licensed、public_domain、fair_use 或 unknown。 - 保存响应中的 asset.id 和上传方式。小于等于 8 MiB 的文件可 POST 原始字节到
/studio/media/{asset}/transfer;文件长度必须与申请的 size 一致。 - 大文件按响应的 part_size 与 part_count 分片,每片 POST 到
/studio/media/{asset}/parts/{part}/transfer。最多 256 MiB,part 从 1 开始。 - POST
/studio/media/{asset}/complete。只有验证完成且状态为 ready 的文件才可用于封面或正文。 - 将
/api/v1/media/{asset}/content放入 document.cover 或 media.src,再 PATCH 保存文档。
transfer 请求仍要带 API Key,Content-Type 使用文件的真实 MIME 类型,例如 image/jpeg;不要把原始图片包在 JSON 或 FormData 中。调用脚本支持 --file photo.jpg。系统会检查文件类型、大小和隐私元数据;请清除图片的 EXIF/GPS 信息后上传。
申请上传的示例:
{"filename":"cover.jpg","content_type":"image/jpeg","size":12345,"rights_basis":"owned"}来源说明和图片授权请同时保存到 document.media 中,不要把尚未验证的上传地址当成永久封面。
提交审核
每个 API Key 都支持提交审核。提交之前,请把 visibility 改为 public 或 unlisted、选好城市、补齐标题和章节,并确认授权与公开范围。
POST /studio/books/{id}/submit,无需请求体。成功返回 202,status 为 pending。这意味着「已提交审核」,不意味着已经公开。
修改已发布图书后也需要重新审核。审核通过之前,阅读页与探索页保留上一版内容和封面;通过之后切换新版。DELETE 会移除书籍并使已发布阅读链接失效,请先确认用户确实希望删除。
错误与重试
错误响应形如 {"error":{"code":"api_key_invalid"}}。
| 状态码 | 常见原因 | 处理 |
|---|---|---|
| 400 | 字段、文档、日期或上传大小不符合要求 | 修正请求,不重复发送同样的错误内容 |
| 401 | 密钥错误、过期、撤销,或账号暂停/注销 | 检查密钥;不要回退到账号密码 |
| 403 | 越权访问或不支持的接口 | 检查书籍工作区权限与开放接口列表 |
| 409 | revision 冲突、待审核锁定或密钥数量上限 | 重新读取状态并处理冲突 |
| 422 | 发布语言不支持 | 使用当前支持的语言 |
| 429 | 超过每分钟 60 次 | 按 Retry-After 等待后再调用 |
| 503 | 服务暂时不可用 | 稍后重试,写操作先核对是否已成功 |
创建请求暂不支持 Idempotency-Key。遇到超时,请先 GET /studio/books 按同一个 slug 查找;确认没有创建成功后,再用原 slug 重试,不要更换 slug 重复创建。服务不会自动重试写操作。
密钥的使用与撤销
密钥泄露或不再使用时,请到「设置 → API Key」撤销。撤销后,使用它的 AI 或应用将无法继续访问你的书籍,已保存的内容不会被删除。
注销账号时会撤销全部 API Key。退出登录只结束网页会话,不会撤销仍在使用的 API Key;不再使用的密钥请单独撤销。