# 上传文件

上传图片文件，之后可在对话补全请求中通过其 `file_id` 引用。

支持的格式：JPEG、PNG、GIF、WebP。格式由文件内容判断。详见 [Files API 指南](https://api-docs.deepseek.com/zh-cn/guides/files_api.md)。

上传文档时，把 `purpose` 设为 `text_recognition` 或 `rich_layout_recognition`，并放在 `file` 字段之前。详见 [文件解析指南](https://api-docs.deepseek.com/zh-cn/guides/document_parsing.md)。

## 接口

```http
POST /files
```

operationId: `createFile`

### 服务地址

- `https://api.deepseek.com`

## 身份验证

### 验证方式 1

**bearerAuth**

`Authorization: Bearer <API_KEY>`

```yaml
type: http
scheme: bearer
```

## 请求体

**必填**

### multipart/form-data

- 引用: [CreateFileRequest](#schema-create-file-request) (`#/components/schemas/CreateFileRequest`)

## 响应

### 200

OK, 返回上传的 `file object`。

#### application/json

- 引用: [FileObject](#schema-file-object) (`#/components/schemas/FileObject`)

**示例**

```json
{
  "id": "file-api-0a1b2c3d4e5f60718293a4b5c6d7e8f9",
  "object": "file",
  "bytes": 102400,
  "created_at": 1700000000,
  "filename": "image.jpg",
  "purpose": "user_data"
}
```

## 代码示例

### curl

```bash
# Set DEEPSEEK_API_KEY to your API key before running this example.
# Set DEEPSEEK_FILE_PATH to a local JPEG, PNG, GIF, or WebP image.
curl --silent --show-error --max-time 60 "https://api.deepseek.com/files" \
  --header "Authorization: Bearer ${DEEPSEEK_API_KEY}" \
  --form "purpose=user_data" \
  --form "file=@${DEEPSEEK_FILE_PATH}"
```

### Python — OpenAI SDK

```python
# Set DEEPSEEK_API_KEY to your API key before running this example.
# Set DEEPSEEK_FILE_PATH to a local JPEG, PNG, GIF, or WebP image.
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["DEEPSEEK_API_KEY"],
    base_url="https://api.deepseek.com",
    timeout=60.0,
)

with open(os.environ["DEEPSEEK_FILE_PATH"], "rb") as image:
    uploaded = client.files.create(file=image, purpose="user_data")
print(uploaded.model_dump_json(indent=2))
```

## 引用的数据结构

### schema-create-file-request

**CreateFileRequest** — `#/components/schemas/CreateFileRequest`

- `type`: `object`

- `required`: `["file","purpose"]`

- **字段**

  - **`purpose`** (必填)

    上传文件的用途。上传文档时，请把该字段放在 `file` 之前。各用途支持的文件类型见 [Files API 指南](https://api-docs.deepseek.com/zh-cn/guides/files_api.md)。

    - `type`: `string`

    - `enum`: `["user_data","text_recognition","rich_layout_recognition"]`

  - **`file`** (必填)

    要上传的文件。可上传的文件类型取决于 `purpose`。

    - `type`: `string`

    - `format`: `binary`

  - **`expires_after[anchor]`** (可选)

    过期时间的锚点。若提供，必须为 `created_at`，且需与 `expires_after[seconds]` 一起使用。

    - `type`: `string`

    - `enum`: `["created_at"]`

  - **`expires_after[seconds]`** (可选)

    文件的有效期（秒），取值在 3600（1 小时）到 2592000（30 天）之间。需与 `expires_after[anchor]` 一起使用。不传这两个 `expires_after` 字段则文件永久有效。

    - `type`: `integer`

    - `minimum`: `3600`

    - `maximum`: `2592000`

### schema-file-object

**FileObject** — `#/components/schemas/FileObject`

描述一个已上传到 Files API 的文件。以 OCR 用途上传的文件只在解析成功后返回。

- `type`: `object`

- `required`: `["id","object","bytes","created_at","filename","purpose"]`

- **字段**

  - **`id`** (必填)

    文件标识符，形如 `file-api-...`，可在对话补全请求中引用。

    - `type`: `string`

  - **`object`** (必填)

    对象的类型，其值为 `file`。

    - `type`: `string`

    - `enum`: `["file"]`

  - **`bytes`** (必填)

    文件大小（字节）。

    - `type`: `integer`

  - **`created_at`** (必填)

    文件创建时的 Unix 时间戳（以秒为单位）。

    - `type`: `integer`

  - **`filename`** (必填)

    文件名。

    - `type`: `string`

  - **`purpose`** (必填)

    文件的用途。

    - `type`: `string`

    - `enum`: `["user_data","text_recognition","rich_layout_recognition"]`

  - **`expires_at`** (可选)

    文件过期时的 Unix 时间戳（以秒为单位）。仅在上传时设置了过期时间才会出现。

    - `type`: `integer`
