跳到主要内容
开发者文档
文档目录

大文件上传

Markdown 版

用于超过 16 MiB 文件的分片上传。

发起大文件上传

POST/v2/spaces/{space_id}/uploads

发起分片上传。先调用 POST /v2/uploads/{upload_id}/parts 获取分片上传地址,逐片 PUT,再调用 POST /v2/uploads/{upload_id}/complete 完成上传。同一个 Idempotency-Key 返回同一个上传。带 branch 时,完成上传会写入该分支。需要 knowledge:write。

需要的能力 knowledge:write

参数

名称位置类型说明
space_id必填路径DevSpaceRefSpace id;default 表示你的默认 Space(你自己的默认 Space,否则为唯一可见的 Space);或 ext:<external_id>,表示带有你为它设定的 id 的 Space,例如 ext:user-42。三种写法均可用于路径、?space_id= 和 space_ids。没有可见的 Space 带有该 external_id 时返回 404。长度 1 到 256
branch查询DevBranchRef代替主线使用的分支:分支 id,或活跃分支的名称。在这个 Space 设有 read_root 的成员,对任何分支都返回 403 outside_read_root。
mode查询644 | 755文件权限,644 或 755(可执行)。只在带 branch 时有效。
Idempotency-Key请求头DevIdempotencyKeyIdempotency-Key、主体、API Key、操作和输入都相同时,24 小时内重放原结果。同一个 Idempotency-Key 搭配不同输入时返回 409 conflict。长度 1 到 512

请求体

application/json DevCreateUploadRequest 用于超过 16 MiB 的文件,更小的文件使用 PUT /v2/spaces/{space_id}/files。超过部署的大小上限返回 413。大到无法处理的文件仍会保存且可读,knowledge.state 最终为 failed。

字段类型说明
path必填DevPath在完成上传时才解析,所以这期间该路径上的文件可能出现或变化。
size必填integer整个文件的字节数。不小于 1
media_type必填string文件的媒体类型,比如 application/pdf。
checksum_sha256必填string整个文件 SHA-256 的 Base64,完成时校验。

响应

错误状态

400 401 403 404 408 409 410 412 413 415 422 429 500 503 错误结构见 错误,各错误码的含义见 错误码。

请求示例

curl
curl -X POST "https://api.mirabase.dev/v2/spaces/$SPACE_ID/uploads" \
  -H "Authorization: Bearer $MIRABASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"path":"/notes/hello.md","size":1,"media_type":"<media_type>","checksum_sha256":"<checksum_sha256>"}'

响应结构示例

json
{
  "id": "<id>",
  "path": "/notes/hello.md",
  "part_size": 1,
  "expires_at": "2026-11-06T00:00:00Z"
}

中止上传

POST/v2/uploads/{upload_id}/abort

丢弃已上传的分片。重复中止返回 204;中止已完成的上传返回 409 upload_not_open。需要 knowledge:write。

需要的能力 knowledge:write

参数

名称位置类型说明
upload_id必填路径DevId服务端签发的不透明标识符,客户端按字节比较。长度 1 到 256

响应

  • 204 无响应体

错误状态

400 401 403 404 408 409 410 412 413 415 422 429 500 503 错误结构见 错误,各错误码的含义见 错误码。

请求示例

curl
curl -X POST "https://api.mirabase.dev/v2/uploads/$UPLOAD_ID/abort" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"

完成上传

POST/v2/uploads/{upload_id}/complete

合并分片并写到路径上,行为与 PUT /v2/spaces/{space_id}/files 相同。内容相同时返回 version_created: false。重复完成返回同一版本,或同一个提案。已中止的上传返回 409 upload_not_open,过了 expires_at 的上传返回 422 upload_expired:请重新发起上传。存下的对象大小或媒体类型与上传时声明的不一致时,返回 422 upload_size_mismatch 或 415 upload_media_type_mismatch;字节的哈希与 checksum_sha256 不符时返回 422 validation_error。需要 knowledge:write。

需要的能力 knowledge:write

参数

名称位置类型说明
upload_id必填路径DevId服务端签发的不透明标识符,客户端按字节比较。长度 1 到 256
If-Match请求头string传入一个 ETag(带引号的版本 id):不是最新版本时返回 412。或传入 *:文件或 Entry 不存在时返回 412。不传时后写覆盖。
Prefer请求头stringhandling=proposal:将本会返回 403 proposal_required 的写入(即 proposal 模式的 Agent 修改不属于自己的文件)转为创建提案;其他情况下不起作用。其他偏好会被忽略。
If-None-Match请求头string* 表示只创建;文件已存在时返回 412 precondition_failed。

请求体

application/json DevCompleteUploadRequest

字段类型说明
parts必填DevCompletedPart[]文件的每一个分片,各带它的 PUT 返回的 ETag。至少 1 项
session_idstring你为该文件所出自的对话指定的 id,与 PUT files?session_id= 相同:记录在本次完成上传所创建的版本上,可通过 lineage 查看。仅用于主线:分支上传传入该字段返回 422。长度 1 到 256
occurred_atstring (date-time)文件内容发生的时间,例如录音或录像的录制时间。检索的 occurred_from / occurred_to 以此为准,段落中也会返回该时间;未提供时以文件写入时间为准。
metadataDevMetadata整体替换 Entry 的元数据,与 PATCH /v2/entries/{id} 上的 metadata 相同。检索的 filter.metadata 按它匹配。
memory_excludeboolean为 true 时该文件不参与记忆提炼:文件照常保存、建立索引并可检索,但不会从中提炼记忆;为 false 时重新提炼。与 PATCH /v2/entries/{id} 的 memory_exclude 是同一个开关。

响应

响应头

  • ETag 刚写入内容的 ETag:下次写入时可传入 If-Match,无需重新读取文件。
  • Preference-Applied 在接受 Prefer: wait 的操作上,请求实际发生等待时返回 wait=N;未等待时不返回(例如该 Key 已有 4 个等待中的请求)。写入转为提案时返回 handling=proposal。
  • Location /v2/proposals/{proposal_id}:这次写入变成的提案可以在这里读取。

错误状态

400 401 403 404 408 409 410 412 413 415 422 429 500 503 错误结构见 错误,各错误码的含义见 错误码。

请求示例

curl
curl -X POST "https://api.mirabase.dev/v2/uploads/$UPLOAD_ID/complete" \
  -H "Authorization: Bearer $MIRABASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"parts":[{"part_number":1,"etag":"<etag>"}]}'

响应结构示例

json
{
  "entry": {
    "id": "<id>",
    "space_id": "<space_id>",
    "title": "Launch notes",
    "latest_version_id": "<latest_version_id>",
    "metadata": {},
    "created_at": "2026-11-06T00:00:00Z",
    "updated_at": "2026-11-06T00:00:00Z",
    "file": {
      "path": "/notes/hello.md",
      "size": 1,
      "media_type": "<media_type>",
      "etag": "<etag>"
    },
    "knowledge": {
      "state": "readable"
    },
    "memory": {
      "scope": "project",
      "kind": "<kind>",
      "pinned": false,
      "exclude": false
    },
    "memory_exclude": false,
    "access": {
      "role": "owner",
      "capabilities": [
        "knowledge:read"
      ]
    }
  },
  "version_id": "<version_id>",
  "version_created": false
}

获取分片上传地址

POST/v2/uploads/{upload_id}/parts

为单次上传的最多 128 个分片获取签名 URL,有效期 5 分钟。使用返回的 required_headers 将每个分片 PUT 到对应 URL,并保存返回的 ETag。已接收的分片不会再次返回,因此再次调用即可续传。已完成或已中止的上传返回 409 upload_not_open,已超过 expires_at 的上传返回 422 upload_expired:请重新发起上传。需要 knowledge:write。

需要的能力 knowledge:write

指南:文件与版本

参数

名称位置类型说明
upload_id必填路径DevId服务端签发的不透明标识符,客户端按字节比较。长度 1 到 256

请求体

application/json DevUploadPartsRequest

字段类型说明
part_numbers必填integer[]从 1 开始编号。1 到 128 项

响应

错误状态

400 401 403 404 408 409 410 412 413 415 422 429 500 503 错误结构见 错误,各错误码的含义见 错误码。

请求示例

curl
curl -X POST "https://api.mirabase.dev/v2/uploads/$UPLOAD_ID/parts" \
  -H "Authorization: Bearer $MIRABASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"part_numbers":[1]}'

响应结构示例

json
{
  "data": [
    {
      "part_number": 1,
      "url": "https://example.com/article"
    }
  ],
  "received": [
    {
      "part_number": 1,
      "etag": "<etag>"
    }
  ],
  "expires_at": "2026-11-06T00:00:00Z",
  "required_headers": {
    "content-type": "<content-type>"
  }
}