# 上传模型文件

> 通用

使用 `multipart/form-data` 上传单个文件。请求体最大为 1 GB；
文件格式和大小还须符合目标模型的要求。

上传成功后，将响应中的 `id` 作为后续模型请求中的 `file_id`。

## 请求地址

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

## 请求体

## 响应

- **200** — 文件上传成功。
- **400** — 请求参数无效，例如 `purpose` 格式错误或目标模型没有可用的文件服务。
- **401** — ModelVerse API Key 缺失或无效。
- **default** — 文件服务或网关错误。

## OpenAPI 定义

```json
{
  "openapi": "3.1.0",
  "x-language": "zh-CN",
  "info": {
    "title": "文件上传接口文档",
    "version": "1.0.0",
    "description": "将本地文件上传到 ModelVerse，获取可在模型请求中引用的 `file_id`。\n\n本文档仅适用于 `purpose` 为三段式模型标识（`xxx:xxx:modelname`）的文件上传。\n其他 `purpose` 类型请参考对应接口文档。\n\n`purpose` 的第三部分用于指定目标模型。例如，为\n`deepseek-v4-flash-vision-exp` 上传文件时，应传入\n`deepseek:version:deepseek-v4-flash-vision-exp`。\n\n文件有效期为创建后的 24 小时。后续模型请求须使用同一项目下的 API Key，\n且请求中的模型名称须与 `purpose` 的第三部分一致。\n"
  },
  "servers": [
    {
      "url": "https://api.modelverse.cn",
      "description": "ModelVerse API 服务器"
    }
  ],
  "tags": [
    {
      "name": "文件上传",
      "description": "为支持文件输入的模型上传文件。"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "paths": {
    "/v1/files": {
      "post": {
        "tags": [
          "文件上传"
        ],
        "operationId": "uploadModelFile",
        "summary": "上传模型文件",
        "description": "使用 `multipart/form-data` 上传单个文件。请求体最大为 1 GB；\n文件格式和大小还须符合目标模型的要求。\n\n上传成功后，将响应中的 `id` 作为后续模型请求中的 `file_id`。\n",
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "$ref": "#/components/schemas/UploadModelFileRequest"
              },
              "encoding": {
                "file": {
                  "contentType": "application/octet-stream"
                }
              },
              "examples": {
                "deepseekVision": {
                  "summary": "为 DeepSeek 视觉模型上传文件",
                  "value": {
                    "purpose": "deepseek:version:deepseek-v4-flash-vision-exp",
                    "file": "/path/to/example.pdf"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "文件上传成功。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ModelFileObject"
                },
                "examples": {
                  "success": {
                    "summary": "上传成功",
                    "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": "请求参数无效，例如 `purpose` 格式错误或目标模型没有可用的文件服务。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "invalidPurpose": {
                    "summary": "purpose 格式错误",
                    "value": {
                      "error": {
                        "message": "Invalid param: unsupported purpose: invalid-purpose",
                        "type": "invalid_request_error",
                        "code": "param_error",
                        "param": "request-trace-id"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "ModelVerse API Key 缺失或无效。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "default": {
            "description": "文件服务或网关错误。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "API key",
        "description": "使用 `Authorization: Bearer <your_api_key>` 请求头传递 ModelVerse API Key。"
      }
    },
    "schemas": {
      "UploadModelFileRequest": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "purpose",
          "file"
        ],
        "properties": {
          "purpose": {
            "type": "string",
            "description": "三段式模型标识，格式为 `xxx:xxx:modelname`。第三部分必须是后续请求使用的模型名称。\n",
            "example": "deepseek:version:deepseek-v4-flash-vision-exp"
          },
          "file": {
            "type": "string",
            "format": "binary",
            "description": "要上传的本地文件。"
          }
        }
      },
      "ModelFileObject": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "id",
          "object",
          "bytes",
          "created_at",
          "expires_at",
          "filename",
          "purpose",
          "status"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "文件 ID，在后续模型请求中作为 `file_id` 使用。",
            "example": "file-abc123"
          },
          "object": {
            "type": "string",
            "const": "file",
            "description": "对象类型，固定为 `file`。"
          },
          "bytes": {
            "type": "integer",
            "format": "int64",
            "minimum": 0,
            "description": "文件大小，单位为字节。"
          },
          "created_at": {
            "type": "integer",
            "format": "int64",
            "description": "文件创建时间，Unix 秒级时间戳。"
          },
          "expires_at": {
            "type": "integer",
            "format": "int64",
            "description": "文件过期时间，Unix 秒级时间戳；文件在创建 24 小时后过期。"
          },
          "filename": {
            "type": "string",
            "description": "文件名。"
          },
          "purpose": {
            "type": "string",
            "description": "请求中提交的三段式模型标识。",
            "example": "deepseek:version:deepseek-v4-flash-vision-exp"
          },
          "status": {
            "type": "string",
            "const": "processed",
            "description": "文件状态；上传成功时为 `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": "错误说明。"
          },
          "type": {
            "type": "string",
            "description": "错误类型。"
          },
          "code": {
            "type": "string",
            "description": "机器可读的错误码。"
          },
          "param": {
            "type": "string",
            "description": "出错的参数名或请求 ID。"
          }
        }
      }
    }
  }
}
```