Gemini 批量任务 API

本文档描述通过 ModelVaults 创建、查询与下载 Gemini（Vertex 风格）批量预测任务的接口，适用于大批量异步文本生成场景。

当前支持的模型 ID（创建任务时 model 字段仅支持以下三种）：

认证说明

所有接口支持以下任一方式携带 API Key（请勿在文档或代码中写真实 Key，使用环境变量或配置占位符）：

• Authorization: Bearer <your_api_key>

• x-goog-api-key: <your_api_key>

Base URL 示例：https://api.modelverse.cn（海外可用 https://api.umodelverse.ai）。

流程概览

1. 上传输入文件：将 JSONL 输入文件上传到平台存储（GCS），获得文件标识。

2. 创建批量任务：提交批量任务，指定模型、输入文件 URI、输出目录前缀。

3. 查询任务状态：轮询任务状态，直至完成或失败。

4. 下载结果文件：任务完成后，根据输出目录下载 predictions.jsonl。

1. 上传批量任务输入文件

将批量任务的输入文件（JSONL）上传到平台，用于后续创建任务时作为输入源。

请求

• 方法 / 路径：POST /v1/files

• Content-Type：multipart/form-data

• 必填字段：

  • purpose：固定为 **batch:gcs**（用于 Gemini 批量任务时必须填写）。

  • file：输入文件（JSONL）。

响应

返回 OpenAI 风格文件对象，主要字段：

与创建任务的约定：上传接口返回的 id 为文件在 GCS 中的对象名。创建批量任务时，inputConfig.gcsSource.uris 需填写完整 GCS URI，格式为：**gs://<bucket>/<id>**，其中 <bucket> 由平台为批量任务分配，以控制台或当前环境说明为准（例如 gs://gemini-batch-001/<id>）。不可使用数组，仅支持字符串形式的单个 URI。

示例

curl -X POST "https://api.modelverse.cn/v1/files" \
  -H "Authorization: Bearer $MODELVAULTS_API_KEY" \
  -F "purpose=batch:gcs" \
  -F "file=@your-input.jsonl"

返回

{
  "id": "1773236148797418904_gemini-3.1-pro-preview.jsonl",
  "object": "file",
  "bytes": 224,
  "created_at": 1773236150,
  "expires_at": 0,
  "filename": "1773236148797418904_gemini-3.1-pro-preview.jsonl",
  "purpose": "batch:gcs"
}
 

2. 创建批量任务

请求

• 方法 / 路径：POST /v1beta/batchPredictionJobs

• Content-Type：application/json

请求体（仅列与 Gemini 批量任务相关字段）

响应

返回 Vertex 风格任务对象。成功创建时，响应中会包含 name 字段（可能为长资源名）。服务会将其中最后一段作为 batch_id / job_id 供后续查询与下载使用；客户端可按 name 或服务返回的简短 id 作为任务唯一标识。

示例

curl -X POST "https://api.modelverse.cn/v1beta/batchPredictionJobs" \
  -H "X-Goog-Api-Key: $MODELVAULTS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "displayName": "my-cloud-storage-batch-inference-job",
    "model": "publishers/google/models/gemini-3-flash-preview",
    "inputConfig": {
      "instancesFormat": "jsonl",
      "gcsSource": {
        "uris": "gs://gemini-batch-001/<上传返回的id>"
      }
    },
    "outputConfig": {
      "predictionsFormat": "jsonl",
      "gcsDestination": {
        "outputUriPrefix": "gs://gemini-batch-001/output"
      }
    }
  }'

返回

{
  "name": "projects/279887244472/locations/global/batchPredictionJobs/7737084104264384512",
  "displayName": "my-cloud-storage-batch-inference-job",
  "model": "publishers/google/models/gemini-3-flash-preview",
  "inputConfig": {
    "instancesFormat": "jsonl",
    "gcsSource": {
      "uris": [
        "gs://gvideo.modelverse.cn/batch_prompt_for_batch_gemini_predict.jsonl"
      ]
    }
  },
  "outputConfig": {
    "predictionsFormat": "jsonl",
    "gcsDestination": {
      "outputUriPrefix": "gs://gvideo.modelverse.cn/test"
    }
  },
  "outputInfo": {
    "gcsOutputDirectory": "gs://gvideo.modelverse.cn/test/prediction-model-2026-02-28T08:22:20.427871Z"
  },
  "state": "JOB_STATE_SUCCEEDED",
  "completionStats": {
    "successfulCount": "2"
  },
  "createTime": "2026-02-28T08:22:22.313780Z",
  "startTime": "2026-02-28T08:23:12.172401Z",
  "endTime": "2026-02-28T08:27:35.914509Z",
  "updateTime": "2026-02-28T08:27:35.914509Z",
  "encryptionSpec": {},
  "modelVersionId": "1"
}

3. 查询批量任务状态

请求

• 方法 / 路径：GET /v1beta/batchPredictionJobs/:job_id

• 路径参数：job_id 为创建任务后得到的任务 ID（即 name 中最后一段或接口返回的 id）。

响应

返回 Vertex 风格任务详情，主要字段包括：

{
  "name": "projects/279887244472/locations/global/batchPredictionJobs/7737084104264384512",
  "displayName": "my-cloud-storage-batch-inference-job",
  "model": "publishers/google/models/gemini-3-flash-preview",
  "inputConfig": {
    "instancesFormat": "jsonl",
    "gcsSource": {
      "uris": [
        "gs://gvideo.modelverse.cn/batch_prompt_for_batch_gemini_predict.jsonl"
      ]
    }
  },
  "outputConfig": {
    "predictionsFormat": "jsonl",
    "gcsDestination": {
      "outputUriPrefix": "gs://gvideo.modelverse.cn/test"
    }
  },
  "outputInfo": {
    "gcsOutputDirectory": "gs://gvideo.modelverse.cn/test/prediction-model-2026-02-28T08:22:20.4172871Z"
  },
  "state": "JOB_STATE_SUCCEEDED",
  "completionStats": {
    "successfulCount": "2"
  },
  "createTime": "2026-02-28T08:22:22.313780Z",
  "startTime": "2026-02-28T08:23:12.172401Z",
  "endTime": "2026-02-28T08:27:35.914509Z",
  "updateTime": "2026-02-28T08:27:35.914509Z",
  "encryptionSpec": {},
  "modelVersionId": "1"
}

任务状态码（state）

任务完成后，使用 outputInfo.gcsOutputDirectory 作为下一步下载接口的 file_id（传入的是目录，不是单文件路径）。

示例（Gemini 格式认证）

curl -X GET "https://api.modelverse.cn/v1beta/batchPredictionJobs/<job_id>" \
  -H "x-goog-api-key: $MODELVAULTS_API_KEY"

4. 下载批量任务结果文件

任务状态为完成后，可通过本接口下载该任务的结果文件（固定为 predictions.jsonl）。

请求

• 方法 / 路径：GET /v1/batchPredictionJobs/content?file_id=<gcsOutputDirectory>

• 查询参数：

  • file_id（必填）：任务输出目录的 GCS URI（即查询任务接口返回的 outputInfo.gcsOutputDirectory），例如 gs://gemini-batch-001/output/prediction-model-2026-03-11T06:15:44.636340Z。服务会在该目录下定位并返回 predictions.jsonl，因此传入的是目录，不要传单文件名。

响应

• 成功：返回 predictions.jsonl 文件流（如 Content-Type: application/octet-stream 或 application/jsonl）。

• 失败：返回相应 HTTP 状态码与错误信息。

示例

# 将 <output_directory> 替换为查询任务接口返回的 outputInfo.gcsOutputDirectory
curl -X GET "https://api.modelverse.cn/v1/batchPredictionJobs/content?file_id=<output_directory>" \
  -H "Authorization: Bearer $MODELVERSE_API_KEY" \
  -o predictions.jsonl

小结