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

# Upload File

> Upload an image or video file to the NavTalk storage.

**Supported formats:**
- **Images**: jpg, jpeg, png, gif, webp, bmp
- **Videos**: mp4, mov, webm, m4v, avi

**Limitations:**
- Maximum file size: 20 MB
- Only image and video files are accepted

**Note for avatar training (`/api/open/v1/avatar/add`)**:
- Video minimum duration: `2` seconds
- Video maximum resolution: `1920x1080`

Returns the uploaded file's metadata including accessible URL.

## Notes for Avatar Training

This endpoint only uploads files and returns a file URL.

If the uploaded video URL is later used in `POST /api/open/v1/avatar/add`, the backend will enforce:

* Minimum video duration: **2 seconds**
* Maximum video resolution: **1920x1080**


## OpenAPI

````yaml POST /api/open/v1/file/upload
openapi: 3.1.0
info:
  title: NavTalk API
  description: NavTalk API for AI avatar management, file uploads, and video generation
  version: 1.0.0
servers:
  - url: https://api.navtalk.ai
    description: NavTalk Production Environment Server
  - url: https://qaapi.navtalk.ai
    description: NavTalk QA Environment Server
  - url: https://devapi.navtalk.ai
    description: NavTalk Development Environment Server
security:
  - navtalkLicenseAuth: []
paths:
  /api/open/v1/file/upload:
    post:
      tags:
        - File
      summary: Upload File
      description: |-
        Upload an image or video file to the NavTalk storage.

        **Supported formats:**
        - **Images**: jpg, jpeg, png, gif, webp, bmp
        - **Videos**: mp4, mov, webm, m4v, avi

        **Limitations:**
        - Maximum file size: 20 MB
        - Only image and video files are accepted

        **Note for avatar training (`/api/open/v1/avatar/add`)**:
        - Video minimum duration: `2` seconds
        - Video maximum resolution: `1920x1080`

        Returns the uploaded file's metadata including accessible URL.
      operationId: uploadFile
      parameters: []
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - file
              properties:
                file:
                  type: string
                  format: binary
                  description: The image or video file to upload (max 20MB)
      responses:
        '200':
          description: File uploaded successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileUploadResponse'
              example:
                code: 200
                message: SUCCESS
                data:
                  fileName: img.png
                  fileUrl: >-
                    /uploadFiles/2026-02-19/eb836cdb-6a07-4424-bedd-0ddd5b28eb67.png
                  suffix: png
                  fileType: image/png
        '400':
          description: Upload failed due to validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NavtalkErrorResponse'
              examples:
                emptyFile:
                  summary: File is empty
                  value:
                    code: 400
                    message: file is empty
                invalidType:
                  summary: Invalid file type
                  value:
                    code: 400
                    message: file is not video or image
                tooLarge:
                  summary: File too large
                  value:
                    code: 400
                    message: file size is too large, max 20MB
                uploadFailed:
                  summary: Upload failed
                  value:
                    code: 400
                    message: failed to save file
      security:
        - navtalkLicenseAuth: []
components:
  schemas:
    FileUploadResponse:
      type: object
      properties:
        code:
          type: integer
          example: 200
        message:
          type: string
          example: SUCCESS
        data:
          $ref: '#/components/schemas/OpenFile'
    NavtalkErrorResponse:
      type: object
      properties:
        code:
          type: integer
          example: 400
        message:
          type: string
          example: Invalid license key
    OpenFile:
      type: object
      properties:
        fileName:
          type: string
          description: Original filename of the uploaded file.
          example: img.png
        fileUrl:
          type: string
          description: Relative path to the uploaded file.
          example: /uploadFiles/2026-02-19/eb836cdb-6a07-4424-bedd-0ddd5b28eb67.png
        suffix:
          type: string
          description: File extension without the dot.
          example: png
        fileType:
          type: string
          description: MIME type of the uploaded file.
          example: image/png
  securitySchemes:
    navtalkLicenseAuth:
      type: apiKey
      in: header
      name: license
      description: NavTalk API license key (e.g. sk_navtalk_...)

````