## 连接与鉴权

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 终端中先执行这些命令，再粘贴密钥并按回车；密钥输入不会回显：

```bash
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。它们只返回已通过审核的版本，不会暴露草稿。

## 第一次创建一本书

先获取工作区：

```bash
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`：

```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": []
  }
}
```

发送创建请求：

```bash
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。

```json
{
  "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 信息后上传。

申请上传的示例：

```json
{"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；不再使用的密钥请单独撤销。
