人生之书帮助中心
返回人生之书
开发者

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_kindhuman 或 pet
original_localezh-CN、en、es、hi、ar
visibilityprivate、unlisted、public
location_basishistorical_anchor、publication_place、death_place
region未选城市时使用 undisclosed;发布前填写实际地区,如 Asia
latitude / longitude城市级坐标,纬度 -90–90,经度 -180–180
authorization.basisself、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 中。

上传图片与设置封面

  1. POST /studio/books/{id}/media/uploads,JSON 包含 filename、content_type、size、rights_basis,后者选 owned、licensed、public_domain、fair_use 或 unknown。
  2. 保存响应中的 asset.id 和上传方式。小于等于 8 MiB 的文件可 POST 原始字节到 /studio/media/{asset}/transfer;文件长度必须与申请的 size 一致。
  3. 大文件按响应的 part_size 与 part_count 分片,每片 POST 到 /studio/media/{asset}/parts/{part}/transfer。最多 256 MiB,part 从 1 开始。
  4. POST /studio/media/{asset}/complete。只有验证完成且状态为 ready 的文件才可用于封面或正文。
  5. 将 /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越权访问或不支持的接口检查书籍工作区权限与开放接口列表
409revision 冲突、待审核锁定或密钥数量上限重新读取状态并处理冲突
422发布语言不支持使用当前支持的语言
429超过每分钟 60 次按 Retry-After 等待后再调用
503服务暂时不可用稍后重试,写操作先核对是否已成功

创建请求暂不支持 Idempotency-Key。遇到超时,请先 GET /studio/books 按同一个 slug 查找;确认没有创建成功后,再用原 slug 重试,不要更换 slug 重复创建。服务不会自动重试写操作。

密钥的使用与撤销

密钥泄露或不再使用时,请到「设置 → API Key」撤销。撤销后,使用它的 AI 或应用将无法继续访问你的书籍,已保存的内容不会被删除。

注销账号时会撤销全部 API Key。退出登录只结束网页会话,不会撤销仍在使用的 API Key;不再使用的密钥请单独撤销。

杭州星序折页科技有限公司浙ICP备2026078098号