Gemini 批量任务 API

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

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

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（请勿在文档或代码中写真实 Key，使用环境变量或配置占位符）：

Authorization: Bearer <your_api_key>
x-goog-api-key: <your_api_key>

Base URL 示例： https://airouter.xincache.cn。

流程概览

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

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

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

请求

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

响应

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

字段	类型	说明
id	string	文件在存储中的对象名
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 -X POST "https://airouter.xincache.cn/v1/files" \
  -H "Authorization: Bearer $XINNETMODEL_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 批量任务相关字段）

字段	类型	必填	说明
displayName	string	否	任务展示名称
model	string	是	模型资源名，如 `publishers/google/models/gemini-3.1-pro-preview`
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 -X POST "https://airouter.xincache.cn/v1beta/batchPredictionJobs" \
  -H "X-Goog-Api-Key: $XINNETMODEL_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://xinnetmodel-batch/batch_prompt_for_batch_gemini_predict.jsonl"
      ]
    }
  },
  "outputConfig": {
    "predictionsFormat": "jsonl",
    "gcsDestination": {
      "outputUriPrefix": "gs://xinnetmodel-batch/test"
    }
  },
  "outputInfo": {
    "gcsOutputDirectory": "gs://xinnetmodel-batch/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://xinnetmodel-batch/batch_prompt_for_batch_gemini_predict.jsonl"
      ]
    }
  },
  "outputConfig": {
    "predictionsFormat": "jsonl",
    "gcsDestination": {
      "outputUriPrefix": "gs://xinnetmodel-batch/test"
    }
  },
  "outputInfo": {
    "gcsOutputDirectory": "gs://xinnetmodel-batch/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"
}

字段	类型	说明
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 （传入的是目录，不是单文件路径）。

示例（Gemini 格式认证）

curl -X GET "https://airouter.xincache.cn/v1beta/batchPredictionJobs/<job_id>" \
  -H "x-goog-api-key: $XINNETMODEL_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://airouter.xincache.cn/v1/batchPredictionJobs/content?file_id=<output_directory>" \
  -H "Authorization: Bearer $XINNETMODEL_API_KEY" \
  -o predictions.jsonl

小结

步骤	接口	说明
1	`POST /v1/files`	上传输入文件， `purpose` 固定为 `batch:gcs` ；返回的 id 用于拼成 gs:///
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

Last modified: 25 April 2026