# Upload a model file

> Common

Upload one file as `multipart/form-data`. The maximum request size is
1 GB. The file must also meet the target model's format and size
requirements.

After a successful upload, use the response's `id` as `file_id` in the
subsequent model request.

## Endpoint

`POST https://api.modelverse.cn/v1/files`

## Request Body

## Responses

- **200** — File uploaded successfully.
- **400** — Invalid request, such as a malformed `purpose` or no available file provider for the target model.
- **401** — The ModelVerse API key is missing or invalid.
- **default** — File service or gateway error.

## OpenAPI Definition

```json
{
  "openapi": "3.1.0",
  "x-language": "en-US",
  "info": {
    "title": "File Upload API",
    "version": "1.0.0",
    "description": "Upload a local file to ModelVerse and obtain a `file_id` that can be\nreferenced in a model request.\n\nThis document applies only to uploads whose `purpose` is a three-part\nmodel identifier (`xxx:xxx:modelname`). For other `purpose` values, refer\nto the corresponding API documentation.\n\nThe third part of `purpose` identifies the target model. For example, to\nupload a file for `deepseek-v4-flash-vision-exp`, use\n`deepseek:version:deepseek-v4-flash-vision-exp`.\n\nFiles expire 24 hours after creation. The subsequent model request must use\nan API key from the same project, and its model must match the third part\nof `purpose`.\n"
  },
  "servers": [
    {
      "url": "https://api.modelverse.cn",
      "description": "ModelVerse API server"
    }
  ],
  "tags": [
    {
      "name": "File Upload",
      "description": "Upload files for models that support file input."
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "paths": {
    "/v1/files": {
      "post": {
        "tags": [
          "File Upload"
        ],
        "operationId": "uploadModelFile",
        "summary": "Upload a model file",
        "description": "Upload one file as `multipart/form-data`. The maximum request size is\n1 GB. The file must also meet the target model's format and size\nrequirements.\n\nAfter a successful upload, use the response's `id` as `file_id` in the\nsubsequent model request.\n",
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "$ref": "#/components/schemas/UploadModelFileRequest"
              },
              "encoding": {
                "file": {
                  "contentType": "application/octet-stream"
                }
              },
              "examples": {
                "deepseekVision": {
                  "summary": "Upload a file for the DeepSeek vision model",
                  "value": {
                    "purpose": "deepseek:version:deepseek-v4-flash-vision-exp",
                    "file": "/path/to/example.pdf"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "File uploaded successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ModelFileObject"
                },
                "examples": {
                  "success": {
                    "summary": "Upload succeeded",
                    "value": {
                      "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"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid request, such as a malformed `purpose` or no available file provider for the target model.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "invalidPurpose": {
                    "summary": "Invalid purpose format",
                    "value": {
                      "error": {
                        "message": "Invalid param: unsupported purpose: invalid-purpose",
                        "type": "invalid_request_error",
                        "code": "param_error",
                        "param": "request-trace-id"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "The ModelVerse API key is missing or invalid.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "default": {
            "description": "File service or gateway error.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "API key",
        "description": "Pass the ModelVerse API key as `Authorization: Bearer <your_api_key>`."
      }
    },
    "schemas": {
      "UploadModelFileRequest": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "purpose",
          "file"
        ],
        "properties": {
          "purpose": {
            "type": "string",
            "description": "Three-part model identifier in the format `xxx:xxx:modelname`.\nThe third part must be the model used in the subsequent request.\n",
            "example": "deepseek:version:deepseek-v4-flash-vision-exp"
          },
          "file": {
            "type": "string",
            "format": "binary",
            "description": "Local file to upload."
          }
        }
      },
      "ModelFileObject": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "id",
          "object",
          "bytes",
          "created_at",
          "expires_at",
          "filename",
          "purpose",
          "status"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "File ID to use as `file_id` in a subsequent model request.",
            "example": "file-abc123"
          },
          "object": {
            "type": "string",
            "const": "file",
            "description": "Object type. Always `file`."
          },
          "bytes": {
            "type": "integer",
            "format": "int64",
            "minimum": 0,
            "description": "File size in bytes."
          },
          "created_at": {
            "type": "integer",
            "format": "int64",
            "description": "File creation time as a Unix timestamp in seconds."
          },
          "expires_at": {
            "type": "integer",
            "format": "int64",
            "description": "File expiration time as a Unix timestamp in seconds; the file expires 24 hours after creation."
          },
          "filename": {
            "type": "string",
            "description": "File name."
          },
          "purpose": {
            "type": "string",
            "description": "Three-part model identifier submitted in the request.",
            "example": "deepseek:version:deepseek-v4-flash-vision-exp"
          },
          "status": {
            "type": "string",
            "const": "processed",
            "description": "File status. A successful upload returns `processed`."
          }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "$ref": "#/components/schemas/Error"
          }
        }
      },
      "Error": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "message",
          "type"
        ],
        "properties": {
          "message": {
            "type": "string",
            "description": "Error message."
          },
          "type": {
            "type": "string",
            "description": "Error type."
          },
          "code": {
            "type": "string",
            "description": "Machine-readable error code."
          },
          "param": {
            "type": "string",
            "description": "The offending parameter name or request ID."
          }
        }
      }
    }
  }
}
```