# 上传批量输入文件

> 通用

上传批量任务的输入文件（JSONL），`purpose` 固定为 `batch`。
每行是一个独立请求，包含 `custom_id`、`method`、`url` 和 `body`，
其中 `body.model` 决定整批任务路由的模型与供应商。

## 请求地址

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

## 请求体

## 响应

- **200** — 上传成功，返回文件对象。
- **400** — 请求参数无效或输入文件格式错误。
- **default** — 错误响应。

## OpenAPI 定义

```json
{
  "openapi": "3.1.0",
  "x-language": "zh-CN",
  "info": {
    "title": "批量任务-上传输入文件接口文档",
    "version": "1.0.0",
    "description": "这是 ModelVerse 上 **OpenAI 兼容批量（Batch）异步任务**的第 1 步：上传输入文件。\n将批量任务的输入文件（JSONL）上传到平台，得到 `file_id` 供后续创建任务使用。\n接口路径为 `POST /v1/files`。\n\n说明：服务会从输入文件（JSONL）的第一行自动识别 `body.model`，\n并据此将文件、后续 batch 任务路由到能够服务该模型的供应商。\n"
  },
  "servers": [
    {
      "url": "https://api.modelverse.cn",
      "description": "ModelVerse API endpoint."
    }
  ],
  "tags": [
    {
      "name": "批量异步任务",
      "description": "OpenAI 兼容的批量异步任务接口。"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "paths": {
    "/v1/files": {
      "post": {
        "tags": [
          "批量异步任务"
        ],
        "operationId": "uploadBatchInputFile",
        "summary": "上传批量输入文件",
        "description": "上传批量任务的输入文件（JSONL），`purpose` 固定为 `batch`。\n每行是一个独立请求，包含 `custom_id`、`method`、`url` 和 `body`，\n其中 `body.model` 决定整批任务路由的模型与供应商。\n",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "$ref": "#/components/schemas/UploadBatchFileRequest"
              },
              "encoding": {
                "file": {
                  "contentType": "application/octet-stream"
                }
              },
              "examples": {
                "default": {
                  "summary": "上传 JSONL 批量输入文件",
                  "value": {
                    "purpose": "batch",
                    "file": "/path/to/batch_input.jsonl"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "上传成功，返回文件对象。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BatchFileObject"
                },
                "examples": {
                  "success": {
                    "summary": "上传成功",
                    "value": {
                      "id": "file-abc123",
                      "object": "file",
                      "bytes": 512,
                      "created_at": 1781600000,
                      "expires_at": 0,
                      "filename": "batch_input.jsonl",
                      "purpose": "batch",
                      "status": "processed"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "请求参数无效或输入文件格式错误。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "error": {
                    "$ref": "#/components/examples/BatchError"
                  }
                }
              }
            }
          },
          "default": {
            "description": "错误响应。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "error": {
                    "$ref": "#/components/examples/BatchError"
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "API key",
        "description": "通过 HTTP 头 `Authorization` 携带 API Key，格式为 `Bearer <your_api_key>`。\n"
      }
    },
    "schemas": {
      "UploadBatchFileRequest": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "purpose",
          "file"
        ],
        "properties": {
          "purpose": {
            "type": "string",
            "const": "batch",
            "description": "文件用途，批量任务固定为 `batch`。"
          },
          "file": {
            "type": "string",
            "format": "binary",
            "description": "批量任务的输入文件（JSONL）。每行是一个独立请求对象：\n`custom_id`（自定义唯一标识）、`method`（固定 `POST`）、\n`url`（如 `/v1/chat/completions`）、`body`（具体请求体，含 `model`）。\n"
          }
        }
      },
      "BatchFileObject": {
        "type": "object",
        "additionalProperties": true,
        "required": [
          "id",
          "object",
          "bytes",
          "created_at",
          "filename",
          "purpose"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "文件 ID，用于查询文件状态、创建 batch 任务及下载结果。"
          },
          "object": {
            "type": "string",
            "const": "file",
            "description": "对象类型，固定为 `file`。"
          },
          "bytes": {
            "type": "integer",
            "format": "int64",
            "description": "文件大小（字节）。"
          },
          "created_at": {
            "type": "integer",
            "format": "int64",
            "description": "创建时间戳（秒）。"
          },
          "expires_at": {
            "type": "integer",
            "format": "int64",
            "description": "过期时间戳（秒），`0` 表示不过期。"
          },
          "filename": {
            "type": "string",
            "description": "文件名。"
          },
          "purpose": {
            "type": "string",
            "description": "文件用途，此处为 `batch`。"
          },
          "status": {
            "type": "string",
            "description": "文件状态，`processed` 表示已处理完成、可用于创建任务。",
            "examples": [
              "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": "错误类型。",
            "examples": [
              "invalid_request_error"
            ]
          },
          "code": {
            "type": "string",
            "description": "机器可读的错误码。"
          },
          "param": {
            "type": "string",
            "description": "出错的参数名或请求 ID。"
          }
        }
      }
    },
    "examples": {
      "BatchError": {
        "summary": "标准 JSON 错误响应",
        "value": {
          "error": {
            "message": "错误描述信息",
            "type": "invalid_request_error",
            "code": "error_code",
            "param": "purpose"
          }
        }
      }
    }
  }
}
```