{
  "openapi": "3.1.0",
  "info": {
    "title": "MiniMax File Management API",
    "description": "MiniMax file management API for uploading, retrieving, listing, and deleting files",
    "license": {
      "name": "MIT"
    },
    "version": "1.0.0"
  },
  "servers": [
    {
      "url": "https://api.minimax.io"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "paths": {
    "/v1/files/upload": {
      "post": {
        "summary": "Upload File",
        "operationId": "uploadFile",
        "tags": ["Files"],
        "parameters": [
          {
            "name": "Content-Type",
            "in": "header",
            "required": true,
            "description": "Indicates the request is a multipart file upload.",
            "schema": {
              "type": "string",
              "enum": ["multipart/form-data"],
              "default": "multipart/form-data"
            }
          }
        ],
        "requestBody": {
          "description": "",
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "required": ["purpose", "file"],
                "properties": {
                  "purpose": {
                    "type": "string",
                    "description": "The purpose of the file. The values and supported formats are as follows:\n\n1. __voice_clone__: For quick cloning of the original voice file (supports mp3, m4a, wav formats).\n2. __prompt_audio__: Sample audio for voice cloning (supports mp3, m4a, wav formats).\n3. __t2a_async_input__: Text file in the request body for asynchronous long-text-to-speech synthesis.\n4. __video_understanding__: Video file for multimodal understanding, referenced in chat requests as `mm_file://{file_id}` and retained for up to 7 days (supports MP4, AVI, MOV, MKV formats).\n5. __video_generation_input__: Input materials for video generation (first-frame image / reference image / reference video / reference audio), referenced in the generation request's content `url` field as `mm_file://{file_id}`, valid for 7 days (after expiry, generation returns file expired and you must re-upload); specs are validated on upload, invalid files are rejected with 400 and not retained, and heic/heif dimensions are parsed server-side (no client-side transcoding).\n\nSupported formats and per-file size limits for `video_generation_input`:\n\n| Type | Extensions | Per-file limit |\n| --- | --- | --- |\n| Image | jpg / jpeg / png / webp / heic / heif | 30 MB |\n| Reference video | mp4 / mov | 50 MB |\n| Reference audio | wav / mp3 | 15 MB |",
                    "enum": ["voice_clone", "prompt_audio", "t2a_async_input", "video_understanding", "video_generation_input"],
                    "example": "t2a_async_input"
                  },
                  "file": {
                    "type": "string",
                    "format": "binary",
                    "description": "The file to be uploaded."
                  }
                }
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UploadFileResp"
                }
              }
            }
          }
        }
      }
    },
    "/v1/files/retrieve": {
      "get": {
        "summary": "Retrieve File",
        "operationId": "retrieveFile",
        "tags": ["Files"],
        "parameters": [
          {
            "name": "file_id",
            "in": "query",
            "required": true,
            "description": "The unique identifier for the file.\nSupports `file_id` obtained from video generation and asynchronous speech synthesis tasks.",
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RetrieveFileResp"
                }
              }
            }
          }
        }
      }
    },
    "/v1/files/list": {
      "get": {
        "summary": "List Files",
        "operationId": "listFiles",
        "tags": ["Files"],
        "parameters": [
          {
            "name": "purpose",
            "in": "query",
            "required": true,
            "description": "The purpose category of the files to list. The values and supported formats are as follows:\n\n1. __voice_clone__: For quick cloning of the original voice file (supports mp3, m4a, wav formats).\n2. __prompt_audio__: Sample audio for voice cloning (supports mp3, m4a, wav formats).\n3. __t2a_async_input__: Text file in the request body for asynchronous long-text-to-speech synthesis (supports txt, zip formats).\n4. __video_generation_input__: Input materials for video generation (first-frame image / reference image / reference video / reference audio).",
            "schema": {
              "type": "string",
              "enum": ["voice_clone", "prompt_audio", "t2a_async_input", "video_generation_input"],
              "example": "t2a_async_input"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ListFileResp"
                }
              }
            }
          }
        }
      }
    },
    "/v1/files/retrieve_content": {
      "get": {
        "summary": "Retrieve File Content",
        "description": "",
        "operationId": "retrieveFileContent",
        "tags": ["Files"],
        "parameters": [
          {
            "name": "file_id",
            "in": "query",
            "required": true,
            "description": "The ID of the file to download.",
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          }
        }
      }
    },
    "/v1/files/delete": {
      "post": {
        "summary": "Delete File",
        "description": "",
        "operationId": "deleteFile",
        "tags": ["Files"],
        "parameters": [
          {
            "name": "Content-Type",
            "in": "header",
            "required": true,
            "description": "The media type of the request body. Must be set to `application/json` to ensure the data is sent in JSON format.",
            "schema": {
              "type": "string",
              "enum": ["application/json"],
              "default": "application/json"
            }
          }
        ],
        "requestBody": {
          "description": "",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/DeleteFileReq"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DeleteFileResp"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "UploadFileResp": {
        "type": "object",
        "properties": {
          "file": {
            "$ref": "#/components/schemas/FileObject"
          },
          "base_resp": {
            "$ref": "#/components/schemas/UploadFileBaseResp"
          }
        },
        "example": {
          "file": {
            "file_id": "${file_id}",
            "bytes": 5896337,
            "created_at": 1700469398,
            "filename": "MiniMax Open Platform-Test bot.docx",
            "purpose": "t2a_async_input"
          },
          "base_resp": {
            "status_code": 0,
            "status_msg": "success"
          }
        }
      },
      "FileObject": {
        "type": "object",
        "properties": {
          "file_id": {
            "type": "integer",
            "format": "int64",
            "description": "The unique identifier for the file."
          },
          "bytes": {
            "type": "integer",
            "format": "int64",
            "description": "The size of the file in bytes."
          },
          "created_at": {
            "type": "integer",
            "format": "int64",
            "description": "The Unix timestamp (in seconds) when the file was created."
          },
          "filename": {
            "type": "string",
            "description": "The name of the file."
          },
          "purpose": {
            "type": "string",
            "description": "The purpose of the file."
          }
        }
      },
      "RetrieveFileResp": {
        "type": "object",
        "properties": {
          "file": {
            "$ref": "#/components/schemas/FileObject"
          },
          "base_resp": {
            "$ref": "#/components/schemas/ListRetrieveDeleteFileBaseResp"
          }
        },
        "example": {
          "file": {
            "file_id": "${file_id}",
            "bytes": 5896337,
            "created_at": 1700469398,
            "filename": "output_aigc.mp4",
            "purpose": "video_generation",
            "download_url": "www.downloadurl.com"
          },
          "base_resp": {
            "status_code": 0,
            "status_msg": "success"
          }
        }
      },
      "ListFileResp": {
        "type": "object",
        "properties": {
          "files": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/FileObject"
            },
            "description": "List of files"
          },
          "base_resp": {
            "$ref": "#/components/schemas/ListRetrieveDeleteFileBaseResp"
          }
        },
        "example": {
          "files": [
            {
              "file_id": "${file_id}",
              "bytes": 5896337,
              "created_at": 1699964873,
              "filename": "297990555456011.tar",
              "purpose": "t2a_async_input"
            },
            {
              "file_id": "${file_id}",
              "bytes": 5896337,
              "created_at": 1700469398,
              "filename": "297990555456911.tar",
              "purpose": "t2a_async_input"
            }
          ],
          "base_resp": {
            "status_code": 0,
            "status_msg": "success"
          }
        }
      },
      "DeleteFileReq": {
        "type": "object",
        "required": ["file_id", "purpose"],
        "properties": {
          "file_id": {
            "type": "integer",
            "format": "int64",
            "description": "The unique identifier for the file."
          },
          "purpose": {
            "type": "string",
            "description": "The purpose of the file. Possible values are:\n1. voice_clone\n2. prompt_audio\n3. t2a_async\n4. t2a_async_input\n5. video_generation",
            "enum": [
              "voice_clone",
              "prompt_audio",
              "t2a_async",
              "t2a_async_input",
              "video_generation"
            ]
          }
        },
        "example": {
          "file_id": "${file_id}",
          "purpose": "t2a_async_input"
        }
      },
      "DeleteFileResp": {
        "type": "object",
        "properties": {
          "file_id": {
            "type": "integer",
            "format": "int64",
            "description": "The unique identifier for the file."
          },
          "base_resp": {
            "$ref": "#/components/schemas/ListRetrieveDeleteFileBaseResp"
          }
        },
        "example": {
          "file_id": "${file_id}",
          "base_resp": {
            "status_code": 0,
            "status_msg": "success"
          }
        }
      },
      "UploadFileBaseResp": {
        "type": "object",
        "properties": {
          "status_code": {
            "type": "integer",
            "description": "The status codes and their meanings are as follows:\n0, Request successful\n1002, Rate limit triggered, please try again later\n1004, Account authentication failed, please check if the API Key is correct\n1008, Insufficient account balance\n1026, The image description contains sensitive content\n2013, Invalid input parameters, please check if the parameters are filled in as required\n2049, Invalid API Key"
          },
          "status_msg": {
            "type": "string",
            "description": "Status details."
          }
        }
      },
      "ListRetrieveDeleteFileBaseResp": {
        "type": "object",
        "properties": {
          "status_code": {
            "type": "integer",
            "description": "The status codes are as follows:\n- 1000, Unknown error;\n- 1001, Timeout;\n- 1002, RPM limit triggered;\n- 1004, Authentication failed;\n- 1008, Insufficient balance;\n- 1013, Internal service error;\n- 1026, Input content error;\n- 1027, Output content error;\n- 1039, TPM limit triggered;\n- 2013, Abnormal input format.\n\n For more information, please refer to the [Error Code Reference](/api-reference/errorcode)."
          },
          "status_msg": {
            "type": "string",
            "description": "Status details."
          }
        }
      }
    },
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT",
        "description": "`HTTP: Bearer Auth`\n- Security Scheme Type: http\n- HTTP Authorization Scheme: `Bearer API_key`, can be found in [Account Management>API Keys](https://platform.minimax.io/user-center/basic-information/interface-key)."
      }
    }
  }
}