# Model File Upload

ModelVerse provides an OpenAI-compatible file upload API. Upload a local file to obtain a `file_id`, then reference that file in requests to models that support file input.

This document covers only uploads whose `purpose` is a three-part model identifier (`xxx:xxx:modelname`). For other `purpose` values, refer to the documentation for the corresponding feature.

## Limitations

- `purpose` must contain three parts separated by colons (`:`). The third part must be the model used in the subsequent request.
- For example, when uploading a file for `deepseek-v4-flash-vision-exp`, set `purpose` to `deepseek:version:deepseek-v4-flash-vision-exp`.
- The maximum upload request size is 1 GB. The file must also meet the target model's format and size requirements.
- Files expire 24 hours after creation. Use the returned `file_id` before it expires.
- A file can only be used by an API key from the same company and project that uploaded it. The model in the subsequent request must match the third part of `purpose`.

## Upload a File

**Request**

- **Method / Path**: `POST /v1/files`
- **Content-Type**: `multipart/form-data`
- **Header**: `Authorization: Bearer <your_api_key>`

**Form fields**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `purpose` | string | Yes | Three-part model identifier in the format `xxx:xxx:modelname` |
| `file` | binary | Yes | Local file to upload |

**Request example**

```bash
curl -X POST "https://api-us-ca.umodelverse.ai/v1/files" \
  -H "Authorization: Bearer $MODELVERSE_API_KEY" \
  -F "purpose=deepseek:version:deepseek-v4-flash-vision-exp" \
  -F "file=@example.pdf"
```

**Response example**

```json
{
  "id": "file-abc123",
  "object": "file",
  "bytes": 2456789,
  "created_at": 1787792400,
  "expires_at": 1787878800,
  "filename": "example.pdf",
  "purpose": "deepseek:version:deepseek-v4-flash-vision-exp",
  "status": "processed"
}
```

**Response fields**

| Field | Type | Description |
| --- | --- | --- |
| `id` | string | File ID to use as `file_id` in a subsequent model request |
| `object` | string | Object type; always `file` |
| `bytes` | int64 | File size in bytes |
| `created_at` | int64 | File creation time as a Unix timestamp in seconds |
| `expires_at` | int64 | File expiration time as a Unix timestamp in seconds |
| `filename` | string | File name |
| `purpose` | string | Three-part model identifier submitted in the request |
| `status` | string | File status; `processed` indicates a successful upload |

After a successful upload, use the response's `id` as `file_id` in the subsequent model request. Use an API key from the same project for both requests.