# File Management (/docs/files)


## Overview [#overview]

The File API allows you to upload files that can be used with batch operations, document analysis in chat, and other features. Files are stored securely in cloud storage and are only accessible to your account.

## Upload File [#upload-file]

```
POST /v1/files
```

Upload a file for later use.

### Request [#request]

```python
file = client.files.create(
    file=open("report.pdf", "rb"),
    purpose="assistants"
)

print(f"File ID: {file.id}")
```

### Parameters [#parameters]

| Parameter | Type   | Required | Description                                 |
| --------- | ------ | -------- | ------------------------------------------- |
| `file`    | file   | Yes      | The file to upload                          |
| `purpose` | string | Yes      | Purpose: `batch`, `fine-tune`, `assistants` |

## List Files [#list-files]

```
GET /v1/files
```

```python
files = client.files.list()

for f in files.data:
    print(f"{f.id} - {f.filename} ({f.bytes} bytes)")
```

## Get File Info [#get-file-info]

```
GET /v1/files/{file_id}
```

## Get File Content [#get-file-content]

```
GET /v1/files/{file_id}/content
```

Returns a presigned URL or direct content for accessing the file.

## Delete File [#delete-file]

```
DELETE /v1/files/{file_id}
```

```python
client.files.delete("file-abc123")
```

## Using Files in Chat [#using-files-in-chat]

Upload a file and then reference it in chat messages using `file_url`:

```python
# Step 1: Upload the file
file = client.files.create(
    file=open("report.pdf", "rb"),
    purpose="assistants"
)

# Step 2: Reference it in a chat message
response = client.chat.completions.create(
    model="model-id",
    messages=[{
        "role": "user",
        "content": [
            {"type": "text", "text": "Analyze this document."},
            {"type": "file_url", "file_url": {"url": f"https://api.yuhuanstudio.com/v1/files/{file.id}/content"}}
        ]
    }]
)

print(response.choices[0].message.content)
```

Files are also accessible in the Messages API via `document` blocks and in the Responses API via `input_file` — see [Messages API](/docs/messages) and [Responses API](/docs/responses-api) for details.

## Supported Formats [#supported-formats]

| Purpose      | Formats                                                           |
| ------------ | ----------------------------------------------------------------- |
| `batch`      | `.jsonl`                                                          |
| `fine-tune`  | `.jsonl`                                                          |
| `assistants` | `.pdf`, `.txt`, `.md`, `.docx`, `.csv`, `.json`, images, and more |

## File Size Limits [#file-size-limits]

| Plan       | Max File Size | Max Total Storage |
| ---------- | ------------- | ----------------- |
| Free       | 10 MB         | 100 MB            |
| Basic      | 100 MB        | 1 GB              |
| Pro        | 512 MB        | 10 GB             |
| Enterprise | Custom        | Custom            |

## Storage & Security [#storage--security]

* Files are stored in secure cloud infrastructure with encryption at rest
* Files are private and only accessible to the uploading account
* Presigned URLs are generated on-the-fly for LLM provider access
* Files may be deleted after a period of inactivity (see our [Terms of Service](/docs/legal/terms))