# 创建批量任务

> 通用

使用第 1 步上传返回的 `input_file_id` 创建批量任务。
服务会按输入文件识别到的模型路由到对应供应商执行任务。

## 请求地址

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

## 请求体

## 响应

- **200** — 创建成功，返回 batch 任务对象。
- **400** — 请求参数无效（如 `input_file_id` 不存在）。
- **default** — 错误响应。

## OpenAPI 定义

```json
{
  "openapi": "3.1.0",
  "x-language": "zh-CN",
  "info": {
    "title": "批量任务-创建批量任务接口文档",
    "version": "1.0.0",
    "description": "这是 ModelVerse 上 **OpenAI 兼容批量（Batch）异步任务**的第 3 步：创建 batch 任务。\n使用已上传的输入文件创建批量任务。接口路径为 `POST /v1/batches`。\n"
  },
  "servers": [
    {
      "url": "https://api.modelverse.cn",
      "description": "ModelVerse API endpoint."
    }
  ],
  "tags": [
    {
      "name": "批量异步任务",
      "description": "OpenAI 兼容的批量异步任务接口。"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "paths": {
    "/v1/batches": {
      "post": {
        "tags": [
          "批量异步任务"
        ],
        "operationId": "createBatch",
        "summary": "创建批量任务",
        "description": "使用第 1 步上传返回的 `input_file_id` 创建批量任务。\n服务会按输入文件识别到的模型路由到对应供应商执行任务。\n",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateBatchRequest"
              },
              "examples": {
                "default": {
                  "summary": "创建批量对话补全任务",
                  "value": {
                    "input_file_id": "file-abc123",
                    "endpoint": "/v1/chat/completions",
                    "completion_window": "24h",
                    "metadata": {
                      "job": "demo-batch"
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "创建成功，返回 batch 任务对象。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BatchObject"
                },
                "examples": {
                  "success": {
                    "summary": "创建成功（状态为 validating）",
                    "value": {
                      "id": "batch_abc123",
                      "object": "batch",
                      "endpoint": "/v1/chat/completions",
                      "errors": null,
                      "input_file_id": "file-abc123",
                      "completion_window": "24h",
                      "status": "validating",
                      "created_at": 1781600010,
                      "request_counts": {
                        "total": 0,
                        "completed": 0,
                        "failed": 0
                      },
                      "metadata": {
                        "job": "demo-batch"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "请求参数无效（如 `input_file_id` 不存在）。",
            "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": {
      "CreateBatchRequest": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "input_file_id",
          "endpoint",
          "completion_window"
        ],
        "properties": {
          "input_file_id": {
            "type": "string",
            "description": "第 1 步上传返回的输入文件 ID。",
            "examples": [
              "file-abc123"
            ]
          },
          "endpoint": {
            "type": "string",
            "description": "处理批量请求的目标接口。",
            "examples": [
              "/v1/chat/completions"
            ]
          },
          "completion_window": {
            "type": "string",
            "description": "任务完成时间窗口，固定为 `24h`。",
            "const": "24h"
          },
          "metadata": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            },
            "description": "自定义元数据，键值均为字符串。"
          }
        }
      },
      "BatchObject": {
        "type": "object",
        "additionalProperties": true,
        "required": [
          "id",
          "object",
          "endpoint",
          "input_file_id",
          "completion_window",
          "status",
          "created_at"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "batch 任务 ID，用于查询任务状态。"
          },
          "object": {
            "type": "string",
            "const": "batch",
            "description": "对象类型，固定为 `batch`。"
          },
          "endpoint": {
            "type": "string",
            "description": "处理请求的目标接口。"
          },
          "errors": {
            "type": [
              "object",
              "null"
            ],
            "description": "错误信息对象；无错误时为 `null`。"
          },
          "input_file_id": {
            "type": "string",
            "description": "输入文件 ID。"
          },
          "completion_window": {
            "type": "string",
            "description": "任务完成时间窗口。"
          },
          "status": {
            "type": "string",
            "description": "任务状态：`validating`（校验输入文件）、`in_progress`（执行中）、\n`finalizing`（准备结果）、`completed`（已完成）、`failed`（失败）、\n`expired`（超时）、`cancelling`（取消中）、`cancelled`（已取消）。\n",
            "enum": [
              "validating",
              "in_progress",
              "finalizing",
              "completed",
              "failed",
              "expired",
              "cancelling",
              "cancelled"
            ]
          },
          "output_file_id": {
            "type": "string",
            "description": "结果文件 ID（任务完成后出现），用于下载成功结果。"
          },
          "error_file_id": {
            "type": "string",
            "description": "错误明细文件 ID（部分请求失败时出现）。"
          },
          "created_at": {
            "type": "integer",
            "format": "int64",
            "description": "创建时间戳（秒）。"
          },
          "request_counts": {
            "$ref": "#/components/schemas/BatchRequestCounts"
          },
          "metadata": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            },
            "description": "创建时传入的自定义元数据。"
          }
        }
      },
      "BatchRequestCounts": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "total": {
            "type": "integer",
            "description": "总请求数。"
          },
          "completed": {
            "type": "integer",
            "description": "已完成请求数。"
          },
          "failed": {
            "type": "integer",
            "description": "失败请求数。"
          }
        }
      },
      "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": "unknown input_file_id: file-abc123",
            "type": "invalid_request_error",
            "code": "error_code",
            "param": "input_file_id"
          }
        }
      }
    }
  }
}
```