> ## Documentation Index
> Fetch the complete documentation index at: https://docs.acturehub.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 上传 PDF

> 比较 relay 与 STS 直传，并说明上传会话和 file_id 的约束。

上传固定分为三步：初始化、传输文件、完成上传。完成后服务返回可用于创建任务的 `file_id`。

## 初始化参数

| 字段          | 类型      | 说明                     |
| ----------- | ------- | ---------------------- |
| `file_name` | string  | 必须以 `.pdf` 结尾          |
| `file_size` | integer | 文件字节数，必须大于 0           |
| `file_md5`  | string  | 32 位小写 MD5             |
| `strategy`  | string  | `relay` 或 `sts_direct` |

<Tabs>
  <Tab title="relay">
    文件通过 BP-Agent API 上传。测试环境固定使用该策略，生产环境也可使用。

    初始化后向 `data.relay.upload_url` 发送 `PUT application/octet-stream`，再调用 `/api/open/uploads/complete`。
  </Tab>

  <Tab title="sts_direct">
    文件直接上传至生产 OSS。只有生产环境启用 STS 并配置角色后才可使用。

    初始化响应会返回临时 STS 凭证、Bucket、Endpoint 和 Object Key。上传至 OSS 后，将 `upload_id` 和 `object_key` 传给 `/api/open/uploads/complete`。
  </Tab>
</Tabs>

## 校验规则

* 只支持 PDF。
* 实际文件大小必须等于初始化声明值。
* 实际 MD5 必须等于初始化声明值。
* `upload_id` 绑定租户与上传策略。
* 上传会话当前最长保留约 24 小时。
* 完成上传后签发的 `file_id` 默认约 24 小时有效。

<Warning>
  上传会话属于短期状态。调用方应连续完成 init、文件传输和 complete，不要把 `upload_id` 当作长期文件标识保存。
</Warning>