---
title: "Files API：上传 PDF 和图片给 Responses API 使用"
description: "上传 PDF、图片和文档，然后在 Responses API 中通过 file_id 引用。"
source: https://lazu.ai/docs/zh/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`         | 元数据  |
| 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/endpoints/responses) 中解引用 `file_id`。
Chat completions 不会自动拉取文件内容。

对于 `purpose=vision` 的图片文件，请使用 `input_image`
而不是 `input_file`。

## 限制

| 限制                        | 值      |
| ------------------------- | ------ |
| 单个 `purpose=user_data` 文件 | 512 MB |
| 单个 `purpose=vision` 文件    | 20 MB  |
| 单次 Responses 调用解引用总大小     | 64 MB  |

## 错误

- `missing_required_parameter` `400` — 缺少 `purpose` 或文件字节。
- `purpose_not_supported` `400` — 不支持的 purpose，例如 `batch` 或 `fine-tune`。
- `file_too_large` `413` — 单文件或解引用总大小超过限制。
- `file_not_found` `404` — 文件不存在，或不属于当前 API Key。