Gemini 批量任务 API

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

支持模型ID

创建任务时，model 字段仅支持以下三种模型ID：

模型 ID
publishers/google/models/gemini-3.1-pro-preview
publishers/google/models/gemini-3-flash-preview
publishers/google/models/gemini-3-pro-image-preview

认证说明

请勿在文档或代码中写真实 API Key，使用环境变量或配置占位符。

所有接口支持以下任一方式携带 API Key：

请求头携带：Authorization: Bearer \<your\_api\_key\>
请求头携带：x\-goog\-api\-key: \<your\_api\_key\>

Base URL

国内地址：https://api\.modelverse\.cn
海外地址：https://api\.umodelverse\.ai

流程概览

Gemini 批量预测任务需按以下4个步骤执行，流程连贯且不可逆：

上传输入文件：将 JSONL 输入文件上传到平台存储（GCS），获得文件标识。
创建批量任务：提交批量任务，指定模型、输入文件 URI、输出目录前缀。
查询任务状态：轮询任务状态，直至完成或失败。
下载结果文件：任务完成后，根据输出目录下载 predictions\.jsonl。

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

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

请求说明

请求方法 / 路径：POST /v1/files
Content-Type：multipart/form\-data
必填字段：
- purpose：固定为 batch:gcs（用于 Gemini 批量任务时必须填写）。
- file：输入文件（JSONL 格式）。

响应说明

返回 OpenAI 风格文件对象，主要字段说明如下：

字段	类型	说明
`id`	string	文件在存储中的对象名，用于后续拼接 GCS URI
`object`	string	固定为 "file"
`bytes`	int64	文件大小（字节）
`created\_at`	int64	创建时间戳
`purpose`	string	即请求中的 `batch:gcs`

关键约定

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

请求示例（curl）

curl -X POST "https://api.modelverse.cn/v1/files" \
  -H "Authorization: Bearer $MODELVERSE_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. 创建批量任务

提交批量预测任务，指定模型、输入文件 GCS URI、输出目录前缀等核心参数，触发异步批量生成。

请求说明

请求方法 / 路径：POST /v1beta/batchPredictionJobs
Content-Type：application/json

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

字段	类型	必填	说明
`displayName`	string	否	任务展示名称，便于区分不同任务
`model`	string	是	模型资源名，必须是本文档开头指定的三种模型ID之一
`inputConfig\.instancesFormat`	string	是	输入格式，固定为 `jsonl`
`inputConfig\.gcsSource\.uris`	string	是	输入文件 GCS URI（字符串），bucket 必须为 `gemini\-batch\-001`，格式为 `gs://gemini\-batch\-001/\<上传返回的id\>`
`outputConfig\.predictionsFormat`	string	是	输出格式，固定为 `jsonl`
`outputConfig\.gcsDestination\.outputUriPrefix`	string	是	输出目录前缀，必须指定为 `gs://gemini\-batch\-001/output`

响应说明

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

请求示例（curl）

curl -X POST "https://api.modelverse.cn/v1beta/batchPredictionJobs" \
  -H "X-Goog-Api-Key: $MODELVERSE_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. 查询批量任务状态

任务创建后，需轮询查询任务状态，直至任务完成（JOB_STATE_SUCCEEDED）或失败（JOB_STATE_FAILED），再进行后续下载操作。

请求说明

请求方法 / 路径：GET /v1beta/batchPredictionJobs/:job\_id
路径参数：job\_id 为创建任务后得到的任务 ID（即 name 中最后一段或接口返回的 id）。

响应说明

返回 Vertex 风格任务详情，核心字段说明如下：

字段	类型	说明
`name`	string	任务资源名或短 id，用于唯一标识任务
`state`	string	任务状态，具体取值见下方状态码说明
`outputInfo\.gcsOutputDirectory`	string	输出目录（用于下载时作为 `file\_id`）
`completionStats`	object	完成统计，包含 `successfulCount`（成功数量）等字段

任务状态码说明（state 取值）

state 取值	含义
JOB_STATE_PENDING	已创建，等待调度
JOB_STATE_RUNNING	执行中
JOB_STATE_SUCCEEDED	成功完成
JOB_STATE_FAILED	失败
JOB_STATE_CANCELLED	已取消
JOB_STATE_PAUSED	已暂停

关键说明

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

请求示例（curl，Gemini 格式认证）

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

响应示例

{
  "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"
}

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

当任务状态为 JOB\_STATE\_SUCCEEDED 后，可通过本接口下载该任务的结果文件（固定为 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 状态码与错误信息。

请求示例（curl）

# 将 <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

小结

Gemini（Vertex 风格）批量预测任务核心步骤汇总如下，便于快速查阅：

步骤	接口	说明
1	POST /v1/files	上传输入文件，`purpose` 固定为 `batch:gcs`；返回的 `id` 用于拼成 `gs://\<bucket\>/\<id\>`
2	POST /v1beta/batchPredictionJobs	创建任务，`uris` 为字符串，填完整 GCS URI；指定模型和输出目录前缀
3	GET /v1beta/batchPredictionJobs/:job_id	查询状态，从响应中取`outputInfo\.gcsOutputDirectory`（用于下载）
4	GET /v1/batchPredictionJobs/content?file_id=<目录>	下载结果，`file\_id` 填输出目录，服务返回该目录下 `predictions\.jsonl`

注意事项

输入文件必须为 JSONL 格式，上传时 purpose 必须填写 batch:gcs，否则无法用于批量任务。
创建任务时，inputConfig\.gcsSource\.uris 必须是字符串（非数组），且 bucket 为平台指定的 gemini\-batch\-001。
下载结果时，file\_id 必须传入任务输出目录（outputInfo\.gcsOutputDirectory），不可传入单个文件路径。
任务为异步执行，需通过轮询查询状态，不可在任务未完成时尝试下载结果。
API Key 需通过环境变量或占位符使用，严禁在代码、文档中硬编码真实 Key。