> ## Documentation Index
> Fetch the complete documentation index at: https://api-tools.memories.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Upload File

> Upload a video, audio, or image file to Visual Intelligence for processing and analysis.

<Info>
  **Product**: Visual Intelligence — Asset Management
  **Use case**: Upload, manage, and download video/image assets used by other Visual Intelligence APIs
  **Host**: `https://mavi-backend.memories.ai/serve/api/v2`
  **Auth**: `Authorization: sk-mavi-...` (no `Bearer` prefix)
</Info>

This endpoint allows you to upload a file to the server. After a successful upload, you will receive an `asset_id` that can be used to reference this asset in all subsequent API calls.

<Note>
  **Pricing:**

  * API calls are free
  * Storage fee: \$0.001/1GB per day
</Note>

### Supported File Formats

| Category  | Formats                                  |
| --------- | ---------------------------------------- |
| **Video** | MP4, MOV, AVI, WebM, MKV, FLV, WMV, MPEG |
| **Audio** | MP3, WAV, AAC, FLAC, OGG, M4A            |
| **Image** | JPEG, PNG, GIF, WebP, BMP, TIFF          |

### Code Example

<CodeGroup>
  ```bash cURL theme={null}
  curl --request POST \
    --url https://mavi-backend.memories.ai/serve/api/v2/upload \
    --header 'Authorization: sk-mavi-...' \
    --form 'file=@video.mp4'
  ```

  ```javascript fetch theme={null}
  const BASE_URL = "https://mavi-backend.memories.ai/serve/api/v2";
  const API_KEY = "sk-mavi-...";

  const formData = new FormData();
  formData.append('file', fileInput.files[0]);

  const response = await fetch(`${BASE_URL}/upload`, {
    method: 'POST',
    headers: {
      'Authorization': API_KEY
    },
    body: formData
  });

  const data = await response.json();
  console.log(data);
  // { code: 200, msg: "success", data: { asset_id: "re_660727003963174912" } }
  ```

  ```python Python theme={null}
  import requests

  BASE_URL = "https://mavi-backend.memories.ai/serve/api/v2"
  API_KEY = "sk-mavi-..."
  HEADERS = {
      "Authorization": f"{API_KEY}"
  }

  def upload(file_path):
      url = f"{BASE_URL}/upload"
      files = {"file": open(file_path, "rb")}
      response = requests.post(url, headers=HEADERS, files=files)
      return response.json()

  # Usage example
  result = upload("video.mp4")
  print(result)
  ```
</CodeGroup>

### Request Body

| Parameter | Type | Required | Description                                                            |
| --------- | ---- | -------- | ---------------------------------------------------------------------- |
| file      | file | Yes      | The file to upload (multipart/form-data). See supported formats above. |

### Response

Return the resource information after the upload is successful.

<ResponseExample>
  ```json theme={null}
  {
    "code": 200,
    "msg": "success",
    "data": {
      "asset_id": "re_660727003963174912"
    },
    "success": true,
    "failed": false
  }
  ```
</ResponseExample>

### Response Parameters

| Parameter      | Type    | Description                                                                                                |
| -------------- | ------- | ---------------------------------------------------------------------------------------------------------- |
| code           | integer | Response code (`200` on success — the example shows this correctly but the prose previously said `string`) |
| msg            | string  | Response message describing the operation result                                                           |
| data           | object  | Response data object containing the uploaded asset information                                             |
| data.asset\_id | string  | Unique identifier of the uploaded asset, format `re_<digits>`. Use this ID in all subsequent API calls.    |
| success        | boolean | Indicates whether the operation was successful                                                             |
| failed         | boolean | Indicates whether the operation failed                                                                     |

### Error Responses

```json theme={null}
// Missing `file` part in the multipart body (note `msg` is null on this path)
HTTP 500 {"code": 500, "msg": null, "data": null}
```

Most other validation failures (empty file, unsupported MIME, oversized payload) surface as `HTTP 400` with a generic `"Request has exceeded the limit."` body — that string is shared between rate-limit and several validation paths, so don't parse `msg` to distinguish them; rely on the HTTP status code.

### Upload Status

After uploading, the asset goes through the following states. Only assets with `SUCCESS` status can be used in subsequent API calls.

| Status      | Description                                            |
| ----------- | ------------------------------------------------------ |
| `WAITING`   | Upload request received, waiting to process            |
| `UPLOADING` | File is being uploaded and processed                   |
| `SUCCESS`   | Upload completed successfully — asset is ready for use |
| `FAILED`    | Upload failed — retry the upload                       |

Use the [Get Metadata](/visual-intelligence/base/get-metadata) endpoint to check the current `upload_status` of an asset.

### File Size Limit

<Warning>
  The maximum file size for direct upload is **500 MB**. For files larger than 500 MB, use the [Signed URL Upload](/visual-intelligence/base/upload-by-signed-url/get-upload-signed-url) method, which supports files up to **5 GB** and provides more reliable uploads for large files.
</Warning>

### Notes

* The returned `asset_id` is required for all subsequent operations (transcription, editing, embedding, etc.)
* Only assets with `upload_status: "SUCCESS"` can be used in subsequent API calls
* Use [Get Metadata](/visual-intelligence/base/get-metadata) to verify the asset is ready before calling other endpoints


## OpenAPI

````yaml POST /upload
openapi: 3.1.0
info:
  title: MAVI API Reference
  description: REST APIs for memory management, search, and entity operations
  version: v1.0.1
servers:
  - url: https://mavi-backend.memories.ai/serve/api/v2
security:
  - ApiKeyAuth: []
paths:
  /upload:
    post:
      summary: Upload File
      operationId: upload_file
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
                  description: The file to upload
              required:
                - file
      responses:
        '200':
          description: File uploaded successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                    example: 200
                    description: Response code indicating the result status
                  msg:
                    type: string
                    example: success
                    description: Response message describing the operation result
                  data:
                    type: object
                    properties:
                      asset_id:
                        type: string
                        example: re_660727003963174912
                        description: Unique identifier of the uploaded asset
                    description: >-
                      Response data object containing the uploaded asset
                      information
                  success:
                    type: boolean
                    example: true
                    description: Indicates whether the operation was successful
                  failed:
                    type: boolean
                    example: false
                    description: Indicates whether the operation failed
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Authorization

````