---
title: "Files API：上傳 PDF 和圖片給 Responses API 使用"
description: "上傳 PDF、圖片和文件，然後在 Responses API 中透過 file_id 引用。"
source: https://lazu.ai/docs/zh-TW/endpoints/files
updated: 2026-10-02
---

# Files API

**POST** `/v1/files`

文件和圖片可以先上傳一次，再在 Responses API 中透過 file\_id 引用。Files API 盡量保持 OpenAI-compatible，同時明確 Lazu 的保留期和 purpose 規則。

## 請求範例

```bash
curl https://api.lazu.ai/v1/files \
  -H "Authorization: Bearer $LAZU_API_KEY" \
  -F purpose=user_data \
  -F file=@./paper.pdf
```

## 回應範例

```json
{
  "id": "file-lazu-01ABCDEF",
  "object": "file",
  "bytes": 421337,
  "filename": "paper.pdf",
  "purpose": "user_data",
  "created_at": 1765980000
}
```

## File endpoints

| Method | Path                    | 用途       |
| ------ | ----------------------- | -------- |
| POST   | `/v1/files`             | 上傳       |
| GET    | `/v1/files`             | 列表       |
| GET    | `/v1/files/:id`         | metadata |
| GET    | `/v1/files/:id/content` | 下載內容     |
| DELETE | `/v1/files/:id`         | 刪除       |

所有 endpoint 都使用 `Authorization: Bearer $LAZU_API_KEY`。

## 上傳請求

- `purpose` `string` (必填) — 宣告檔案用途。 取值: `user_data`, `vision`
- `file` `multipart file` (必填) — 上傳的檔案位元組。

## 支援的 purpose

- **user\_data** — 最大 512 MB。用於 PDF、文字和結構化資料，透過 Responses 的
  `input_file` 傳入。
- **vision** — 最大 20 MB。允許 `image/png`、`image/jpeg`、
  `image/gif`、`image/webp`。

OpenAI 的 `batch`、`fine-tune` 和

`assistants` purpose 暫不支援。無論 purpose
如何，都會拒絕可執行檔副檔名。

## 上傳響應

- `id` `string` — File ID，例如 `file-lazu-01KSBV4MC6THZ9TCZEM38KPYRX`。
- `object` `string` — 始終為 `file`。
- `bytes` `integer` — 上傳位元組數。
- `filename` `string` — 原始檔名。
- `purpose` `string` — 儲存的 purpose。
- `status` `string` — 通常為 `processed`。

成功上傳時 Lazu 返回 `201 Created`。如果用戶端只接受 200，需要把
201 也視作成功。

## 在 Responses 中引用

Lazu 只會在 [Responses](https://lazu.ai/docs/zh-TW/endpoints/responses) 中解引用 `file_id`。
Chat completions 不會自動拉取檔案內容。

## 限制

| 限制                        | 值      |
| ------------------------- | ------ |
| 單個 `purpose=user_data` 檔案 | 512 MB |
| 單個 `purpose=vision` 檔案    | 20 MB  |
| 單次 Responses 呼叫解引用總大小     | 64 MB  |