# Gemini Batch Tasks This document describes the APIs for creating, querying, and downloading **Gemini (Vertex-style) batch prediction jobs** via ModelVerse. It is suitable for large-scale asynchronous text generation scenarios. --- **Currently supported model IDs** (the `model` field only supports the following when creating jobs): | Model ID | |--------| | `publishers/google/models/gemini-3.1-pro-preview` | | `publishers/google/models/gemini-3-flash-preview` | | `publishers/google/models/gemini-3-pro-image-preview` | --- ## Authentication All APIs support either of the following methods to pass the API Key (do not include real keys in documentation or code; use environment variables or placeholders): - `Authorization: Bearer ` - `x-goog-api-key: ` Base URL examples: `https://api-us-ca.umodelverse.ai` --- ## Workflow Overview 1. **Upload input file**: Upload a JSONL input file to platform storage (GCS) and obtain the file identifier. 2. **Create batch job**: Submit a batch job with the model, input file URI, and output directory prefix. 3. **Query job status**: Poll the job status until it completes or fails. 4. **Download result file**: After completion, download `predictions.jsonl` from the output directory. --- ## 1. Upload Batch Input File Upload the JSONL input file for the batch job to the platform for use as the input source when creating the job. **Request** - **Method / Path**: `POST /v1/files` - **Content-Type**: `multipart/form-data` - **Required fields**: - `purpose`: must be `batch:gcs` (required for Gemini batch jobs). - `file`: input file (JSONL). **Response** Returns an OpenAI-style file object with key fields: | Field | Type | Description | |-------------|--------|-------------| | id | string | Object name in storage | | object | string | Always `"file"` | | bytes | int64 | File size (bytes) | | created_at | int64 | Creation timestamp | | purpose | string | Same as request (`batch:gcs`) | **Convention with job creation**: The returned **id** is the object name in GCS. When creating a batch job, `inputConfig.gcsSource.uris` must be the **full GCS URI** in the format: `gs:///`, where `` is assigned by the platform (refer to console or environment, e.g., `gs://gemini-batch-001/`). Only a **single string URI** is supported (not an array). **Example** ```bash curl -X POST "https://api-us-ca.umodelverse.ai/v1/files" \ -H "Authorization: Bearer $MODELVERSE_API_KEY" \ -F "purpose=batch:gcs" \ -F "file=@your-input.jsonl" ``` **Response** ```shell { "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. Create Batch Job **Request** - **Method / Path**: `POST /v1beta/batchPredictionJobs` - **Content-Type**: `application/json` **Request Body (only fields related to Gemini batch jobs)** | Field | Type | Required | Description | |-----------------------------------------------|--------|----------|-----------------------------------------------------------------------------| | displayName | string | No | Display name of the job | | model | string | Yes | Model resource name, e.g. `publishers/google/models/gemini-3.1-pro-preview` | | inputConfig.instancesFormat | string | Yes | Input format, e.g. `jsonl` | | inputConfig.gcsSource.uris | string | Yes | Input file GCS URI (**string**). Bucket must be `gemini-batch-001`, i.e. `gs://gemini-batch-001/` | | outputConfig.predictionsFormat | string | Yes | Output format, e.g. `jsonl` | | outputConfig.gcsDestination.outputUriPrefix | string | Yes | Output directory prefix. Must be `gs://gemini-batch-001/output` | **Response** Returns a Vertex-style job object. Upon successful creation, the response includes a `name` field (which may be a long resource name). The service will use the last segment as the **batch_id / job_id** for subsequent queries and downloads. Clients can use either the full `name` or the short ID as the unique identifier. **Example** ```bash curl -X POST "https://api-us-ca.umodelverse.ai/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/" } }, "outputConfig": { "predictionsFormat": "jsonl", "gcsDestination": { "outputUriPrefix": "gs://gemini-batch-001/output" } } }' ``` **Response** ```json { "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. Query Batch Job Status **Request** - **Method / Path**: `GET /v1beta/batchPredictionJobs/:job_id` - **Path Parameter**: `job_id` is the job ID obtained after task creation (i.e., the last segment of `name` or the returned id). **Response** Returns a Vertex-style job detail. Key fields include: ```json { "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" } ``` | Field | Type | Description | |------------------------------|--------|--------------------------------------------------| | name | string | Job resource name or short id | | state | string | Job status (see status codes below) | | outputInfo.gcsOutputDirectory| string | Output directory (used as `file_id` for download)| | completionStats | object | Completion statistics (e.g., `successfulCount`) | **Job Status Codes (state)** | State Value | Description | |----------------------|--------------------------| | `JOB_STATE_PENDING` | Created, waiting to be scheduled | | `JOB_STATE_RUNNING` | In progress | | `JOB_STATE_SUCCEEDED`| Completed successfully | | `JOB_STATE_FAILED` | Failed | | `JOB_STATE_CANCELLED`| Cancelled | | `JOB_STATE_PAUSED` | Paused | After the job is completed, use **outputInfo.gcsOutputDirectory** as the `file_id` for the next download API (this is a directory, not a single file path). **Example (Gemini-style authentication)** ```bash id="3j7v1p" curl -X GET "https://api-us-ca.umodelverse.ai/v1beta/batchPredictionJobs/" \ -H "x-goog-api-key: $MODELVERSE_API_KEY" ``` --- ## 4. Download Batch Job Result File After the job is completed, you can download the result file (`predictions.jsonl`) via this API. **Request** - **Method / Path**: `GET /v1/batchPredictionJobs/content?file_id=` - **Query Parameters**: - **file_id** (required): The GCS URI of the job **output directory** (i.e., `outputInfo.gcsOutputDirectory` returned by the query API), for example: `gs://gemini-batch-001/output/prediction-model-2026-03-11T06:15:44.636340Z`. The service will locate and return `predictions.jsonl` under this directory. Therefore, pass the **directory**, not a single file path. **Response** - Success: Returns the `predictions.jsonl` file stream (e.g., `Content-Type: application/octet-stream` or `application/jsonl`) - Failure: Returns the corresponding HTTP status code and error message **Example** ```bash id="8t5x1c" # Replace with outputInfo.gcsOutputDirectory returned by the query API curl -X GET "https://api-us-ca.umodelverse.ai/v1/batchPredictionJobs/content?file_id=" \ -H "Authorization: Bearer $MODELVERSE_API_KEY" \ -o predictions.jsonl ``` --- ## Summary | Step | API | Description | |------|------------------------------------------------------|-----------------------------------------------------------------------------| | 1 | `POST /v1/files` | Upload input file. **purpose must be `batch:gcs`**; returned id is used to construct gs:/// | | 2 | `POST /v1beta/batchPredictionJobs` | Create job. **uris must be a string** with full GCS URI | | 3 | `GET /v1beta/batchPredictionJobs/:job_id` | Query status and retrieve **outputInfo.gcsOutputDirectory** | | 4 | `GET /v1/batchPredictionJobs/content?file_id=` | Download results. **file_id must be the output directory**; the service returns the contents under this directory |