---
title: "玩家上传的图片"
description: "用 api.media 保存玩家上传的图片，相关的小段 JSON 放进会话存储，适合自己写界面代码的世界。"
---
<div v-pre>

# 玩家上传的图片

玩家的图片用 `api.media` 保存，和它相关的小段 JSON 用 `api.sessionStorage` 保存。两样都属于当前这一局，同一个账号在另一台设备上登录也能读到。创作者自己提供的图片还是放在 **面板 → 素材** 里，用 `@asset:` 引用来使用。

玩家界面的模板里没有上传用的部件，所以这篇食谱要写界面代码（**面板 → 界面代码**）。

## 先想清楚数据放在哪

| 数据 | API |
|------|-----|
| 玩家图片的文件本身和图库的元数据 | `api.media` |
| 选中的图片 ID、有长度限制的笔记，或者别的只属于这个存档的 JSON | `api.sessionStorage` |
| 只在这个浏览器里用的偏好，和丢了也没关系的缓存 | `api.storage` |
| 规则或 AI 要用到的游戏状态 | 声明好的游戏变量 |

不要把图片的 base64 塞进 JSON、游戏变量或浏览器存储。云端保存需要联网。这一局的图片和世界的导出包是分开的，别承诺导出世界就能把玩家的私人文件一起下载下来。

## 上传和显示

在组件里先拿到 `const api = useYumina()`。打开的时候、改动之后，以及临时显示链接过期之前（五分钟），都重新读一遍列表：

```tsx
const page = await api.media.list(0);
// page.items contains { id, entryId, metadata, version, url, thumbnailUrl, deleted, ... }.
// Load subsequent pages when page.hasMore is true.

if (!api.readOnly && page.uploadsEnabled) {
  const result = await api.media.pick({
    metadata: { title: "Character portrait" }
  });
  if (result) {
    // result is { mediaId, entryId }; null means the player canceled.
    // Reload the list to obtain its temporary display URL.
  }
}
```

显示的时候用没被删除的条目的 `url` 或 `thumbnailUrl`。文件被彻底删除以后，条目的 URL 可能是 null。请求被拒绝时要接住，留一个错误状态，promise 成功了才显示保存成功。要不要开放上传控件，看 `api.readOnly` 和 `uploadsEnabled`。

已经有文件输入框的话，调用 `api.media.upload(file, { entryId, uploadId, metadata })`。请求失败后，留着选中的 `File`，重试同一个文件或请求时用同一个 `uploadId`。千万别一边退回本地存储，一边说已经存到云端了。

## 保存选中的图片

JSON 里只记一个稳定的条目 ID，显示时再去 `media.list()` 里找它。`url` 和 `thumbnailUrl` 不要存：

```tsx
const previous = await api.sessionStorage.get("selected-portrait");
const saved = await api.sessionStorage.set(
  "selected-portrait",
  { entryId: selectedItem.entryId, mediaId: selectedItem.id },
  { expectedVersion: previous.version }
);
// Keep saved.version for later changes.
```

所有 JSON 方法都返回 `{ value, version, exists }`。读的时候检查 `exists`。每次 `set` 和 `remove` 都必须带 `{ expectedVersion }`；要是另一台设备已经改过这条记录，写入会被 `SESSION_STORAGE_CONFLICT` 拒绝。这时留着草稿，重新读一遍，理清楚了再提交。不要拿着过期的选择盲目重试。

只想清掉选择，就用最新的版本号调用 `api.sessionStorage.remove("selected-portrait", { expectedVersion })`。想把一张图片从这一局里移走，就调用 `api.media.remove(item.entryId, item.version)`。这是两个独立的操作；清掉选择不会删除图片。文件的彻底删除在 **我的库 → 资源 → 存档图片** 里管理，可能会影响别的存档、存档点和分享。

## 限制和保存下来的副本

- 图片：静态的 JPEG/PNG/WebP，输入最大 16 MiB，解码后最多 4000 万像素。服务器会生成一张最长边 2048 像素的 WebP 显示图，外加一张缩略图。这不是原文件的备份。图片占用账号现有的素材容量。
- JSON：每个值序列化成 UTF-8 后最多 32 KiB；每一局当前值合计 256 KiB、最多 128 个键（含删除标记）、值的历史最多 16 MiB；同一个所有者的全部会话每小时最多 1,000 次修改。
- 恢复存档点时如果改动了 JSON，也受这些限制。容量超限返回 HTTP 413，每小时次数超限返回 429；整个恢复会回滚，图片和剧情状态也一起回滚。历史会保留。恢复时值没变的话，不会重复写历史，就算已经到了这些 JSON 上限也照样能恢复。
- 存档点、同账号的分支和分享快照会把 JSON 和图片引用一起记下来。恢复存档点时两样一起恢复。分享只保留创建那一刻的快照，之后新增的私人内容不会进去。
- 分享回放是只读的，沿用现有的可见性、世界的发布状态、隐藏或审核状态，以及内容分级规则。分享者和卡的创作者是快照的特权读者，隐藏、未发布或敏感的快照也能看；别的查看者要通过相应的检查。不公开列出的分享可以通过链接访问。这不会让创作者看到所有者私人的实时会话数据，那些还是只有所有者能看。

## 已有的浏览器图库

兼容适配器能在任何世界里识别通过校验的现行 Oncin v2/v3/v4 和 `gallery_data` 格式。迁移要在存着原图的那个浏览器里进行，旧数据会保留。它不会去猜损坏或含糊的日志和备份，不会从另一台设备的浏览器里找回数据，不会抓取远程 URL，也不会自动转换任意 localStorage 键。

新卡请直接用上面这些明确的 SDK API。其他旧格式的话，在上传和云端保存都确认成功之前，保留本地的原件。

## 验证接入

1. 上传一张小的、受支持的图片，等确认成功后重新加载这一局。
2. 用同一个账号在另一台设备上打开这一局，确认图片和选择都在。
3. 保存一个存档点，换一个选择，再恢复存档点；确认图片引用和 JSON 一起回来了。
4. 创建一个同账号的分支和一个分享快照；检查它们记下来的状态，以及回放是不是只读。
5. 试一遍取消选择、上传失败、容量超限，还有另一台设备改动 JSON 造成的冲突。要留着草稿，并把失败显示出来。

方法签名见 [API 参考](../08-api-reference.md)。给 AI 看图片是另一个功能，走聊天附件；在界面上显示一张图片，不会把它的像素发给模型。

</div>
