# Gemini Media Analysis

> Large Language Models

Analyze images, video, audio, PDFs, or text files with Gemini `generateContent`. Upload the file, then reference its URI in an analysis request alongside a question or instruction.

## File URIs and large-file analysis

The following URI types are supported:

| URI | Usage |
| --- | --- |
| `gs://bucket/object` | Use `gcs_uri` returned by this platform's upload API. Recommended for large files: the model reads the GCS object directly, without embedding the file contents in the analysis request. |
| `https://...` / `http://...` | Use the returned `s3_url` or another server-reachable public URL. Signed URLs must still be valid. |

`gs://` is the file reference returned after upload. Upload the local file using `multipart/form-data`. Do not construct the bucket yourself or use an arbitrary third-party GCS URI as a platform-uploaded file.

## 1. Upload the media file

Call `POST /v1/files` with one file per request. Authenticate with either `Authorization: Bearer <MODELVERSE_API_KEY>` or `x-goog-api-key: <MODELVERSE_API_KEY>`. Upload and analyze in the same environment using API keys belonging to the same company and organization.

| Form field | Type | Required | Description |
| --- | --- | --- | --- |
| `purpose` | string | Yes | Fixed to `batch:gcs`, including uploads for media analysis. |
| `usage` | string | For this workflow | Set to `inference` for online inference. The API defaults to `batch` when omitted, so explicitly set it for media analysis. |
| `model` | string | Yes | Required when `usage=inference`, for example `gemini-4-argon`. Use the model ID intended for analysis. Upload success does not guarantee that the model is callable; availability is checked during analysis. |
| `file` | binary | Yes | A local document or media file, such as a PDF, image, video, or audio file. Supported analysis formats depend on the selected model. |

This PDF example uses the API endpoint `https://api.modelverse.cn` and `gemini-4-argon`. Set the `MODELVERSE_API_KEY` environment variable and update the local file path. For another environment supporting this feature, replace `BASE_URL` and the model ID accordingly. Run the commands in order with `curl` and `jq` installed.

```bash
BASE_URL="https://api.modelverse.cn"
MODEL="gemini-4-argon"
FILE_PATH="/path/to/document.pdf"
PROMPT="Summarize this PDF and list its key chapters."

curl --fail-with-body --location "$BASE_URL/v1/files" \
  --header "Authorization: Bearer $MODELVERSE_API_KEY" \
  --form 'purpose=batch:gcs' \
  --form 'usage=inference' \
  --form "model=$MODEL" \
  --form "file=@$FILE_PATH;type=application/pdf" \
  --output upload.json
```

Example successful response (the bucket, object name, and signed URL are illustrative; use the values actually returned):

```json
{
  "id": "6fd9bc58-d80e-47cb-b6ab-5b0e19173487.pdf",
  "object": "file",
  "bytes": 52428800,
  "created_at": 1794441600,
  "expires_at": 1795046400,
  "filename": "document.pdf",
  "purpose": "batch:gcs",
  "gcs_uri": "gs://example-modelverse-bucket/6fd9bc58-d80e-47cb-b6ab-5b0e19173487.pdf",
  "s3_url": "https://storage.googleapis.com/example-modelverse-bucket/6fd9bc58-d80e-47cb-b6ab-5b0e19173487.pdf?REPLACE_WITH_RETURNED_SIGNATURE"
}
```

| Response field | Description |
| --- | --- |
| `id` | Platform file identifier. Pass the full `gcs_uri` for analysis, not just `id`. |
| `gcs_uri` | Full `gs://` URI to pass as `fileData.fileUri` in the next step. |
| `s3_url` | Signed HTTPS URL, also usable for media analysis. Do not edit its signature parameters. |
| `bytes` / `filename` | File size in bytes and original filename. |
| `created_at` / `expires_at` | Creation and expiration times as Unix timestamps in seconds. Uploaded files currently remain valid for 7 days; use the returned `expires_at` as the source of truth. |

## 2. Analyze the uploaded file

Extract `gcs_uri` from the saved `upload.json` and use it as `fileData.fileUri`, with `application/pdf` as the PDF's `mimeType`. These commands build the request JSON, run analysis, and print the resulting text:

```bash
GCS_URI=$(jq -er '.gcs_uri | select(startswith("gs://"))' upload.json)
jq -n --arg uri "$GCS_URI" --arg prompt "$PROMPT" '{
  contents: [{
    role: "user",
    parts: [
      {fileData: {fileUri: $uri, mimeType: "application/pdf"}},
      {text: $prompt}
    ]
  }]
}' > analysis-request.json

curl --fail-with-body --location "$BASE_URL/v1beta/models/$MODEL:generateContent" \
  --header "Authorization: Bearer $MODELVERSE_API_KEY" \
  --header 'Content-Type: application/json' \
  --data-binary @analysis-request.json \
  --output analysis.json

jq -r '.candidates[]?.content.parts[]? | .text // empty' analysis.json
```

Read analysis text from `candidates[].content.parts[].text` and token usage from `usageMetadata`. The request examples also cover images, video, audio, text files, and a GCS PDF.

## Limits and troubleshooting

- The upload request body limit is **1 GiB (1,073,741,824 bytes, including multipart overhead)**. GCS references support large files, while the selected model still imposes its own file size, page count, duration, and context token limits.
- GCS files must have been uploaded through this platform under the current company and organization and must not have expired. Re-upload expired files and use the new `gcs_uri`; a `gs://` reference is not permanent.
- All GCS files in one request must belong to the same provider and project. Any explicit cache used with them must also match. If they do not match, prepare compatible files or cache in the same environment and organization.
- Media parts accept `fileData.mimeType` / `fileData.fileUri` or `file_data.mime_type` / `file_data.file_uri`; use only one naming style per field. MIME types must match the actual format: `application/pdf` for PDF, `image/jpeg` for JPEG, `video/mp4` for MP4, and `audio/mpeg` for MP3.
- A GCS URI must include a bucket and object path, without query parameters or a fragment. Do not append HTTPS signature parameters to it.

| Error or symptom | Action |
| --- | --- |
| Upload: `model is required for inference uploads` | Include a nonempty `model` form field. |
| Upload: `usage must be batch or inference` | Use `usage=inference` for media analysis uploads. |
| `400`: `invalid GCS file URI` / `GCS file mimeType is required` | Use the full returned `gcs_uri` and provide the correct MIME type. |
| `404`: `GCS file not found or expired` | Check the environment, company, organization, and expiration time; re-upload if needed. |
| `400`: `file provider is not available for requested model` | The file cannot be used with the requested model. Check model and file compatibility in this environment. |
| `400`: `referenced files belong to different providers or projects` | The referenced GCS files are incompatible; prepare matching files. |
| `503`: `affinity_unavailable` | The file service is temporarily unavailable. Retry later; contact support with the request ID if it persists. |
| Public URL cannot be read | Check server reachability, signature expiration, and the MIME type. |

See the [Gemini documentation](https://docs.cloud.google.com/vertex-ai/generative-ai/docs/multimodal/image-understanding) for formats and model capabilities.

## Endpoint

`POST https://api.modelverse.cn/v1beta/models/{modelsId}:generateContent`

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| modelsId | path | string | Yes | Gemini model ID supporting the supplied media format, for example `gemini-4-argon`. |

## Request Body

## Responses

- **200** — Analysis succeeded. Returns a Gemini content generation response.
- **400** — Invalid request parameters, MIME mismatch, invalid GCS URI, or file incompatible with the requested model.
- **404** — GCS file is missing, expired, or not owned by the current company and organization.
- **503** — The file service is temporarily unavailable; retry later.
- **default** — Error response.

## OpenAPI Definition

```json
{
  "openapi": "3.1.0",
  "info": {
    "title": "Gemini Add-ons API",
    "version": "v1beta",
    "description": "This document describes the Gemini add-on APIs on ModelVerse, covering media analysis, explicit caching, Gemini Embedding 2 embeddings, and Vertex-style batch prediction jobs, including request bodies, response bodies, examples, and error responses."
  },
  "servers": [
    {
      "url": "https://api.modelverse.cn",
      "description": "Mainland China"
    },
    {
      "url": "https://api.umodelverse.ai",
      "description": "Global"
    },
    {
      "url": "https://api-us-ca.umodelverse.ai",
      "description": "Los Angeles, US"
    },
    {
      "url": "https://api-sg.umodelverse.ai",
      "description": "Singapore"
    },
    {
      "url": "https://api-ge-fra.umodelverse.ai",
      "description": "Frankfurt"
    }
  ],
  "tags": [
    {
      "name": "Gemini Add-ons",
      "description": "Gemini media analysis, explicit caching, embeddings, and batch prediction jobs."
    }
  ],
  "security": [
    {
      "bearerAuth": []
    },
    {
      "xGoogApiKey": []
    }
  ],
  "paths": {
    "/v1beta/models/{modelsId}:generateContent": {
      "post": {
        "tags": [
          "Gemini Add-ons"
        ],
        "operationId": "geminiMediaAnalysis",
        "summary": "Gemini Media Analysis",
        "description": "Analyze images, video, audio, PDFs, or text files with Gemini `generateContent`. Upload the file, then reference its URI in an analysis request alongside a question or instruction.\n\n## File URIs and large-file analysis\n\nThe following URI types are supported:\n\n| URI | Usage |\n| --- | --- |\n| `gs://bucket/object` | Use `gcs_uri` returned by this platform's upload API. Recommended for large files: the model reads the GCS object directly, without embedding the file contents in the analysis request. |\n| `https://...` / `http://...` | Use the returned `s3_url` or another server-reachable public URL. Signed URLs must still be valid. |\n\n`gs://` is the file reference returned after upload. Upload the local file using `multipart/form-data`. Do not construct the bucket yourself or use an arbitrary third-party GCS URI as a platform-uploaded file.\n\n## 1. Upload the media file\n\nCall `POST /v1/files` with one file per request. Authenticate with either `Authorization: Bearer <MODELVERSE_API_KEY>` or `x-goog-api-key: <MODELVERSE_API_KEY>`. Upload and analyze in the same environment using API keys belonging to the same company and organization.\n\n| Form field | Type | Required | Description |\n| --- | --- | --- | --- |\n| `purpose` | string | Yes | Fixed to `batch:gcs`, including uploads for media analysis. |\n| `usage` | string | For this workflow | Set to `inference` for online inference. The API defaults to `batch` when omitted, so explicitly set it for media analysis. |\n| `model` | string | Yes | Required when `usage=inference`, for example `gemini-4-argon`. Use the model ID intended for analysis. Upload success does not guarantee that the model is callable; availability is checked during analysis. |\n| `file` | binary | Yes | A local document or media file, such as a PDF, image, video, or audio file. Supported analysis formats depend on the selected model. |\n\nThis PDF example uses the API endpoint `https://api.modelverse.cn` and `gemini-4-argon`. Set the `MODELVERSE_API_KEY` environment variable and update the local file path. For another environment supporting this feature, replace `BASE_URL` and the model ID accordingly. Run the commands in order with `curl` and `jq` installed.\n\n```bash\nBASE_URL=\"https://api.modelverse.cn\"\nMODEL=\"gemini-4-argon\"\nFILE_PATH=\"/path/to/document.pdf\"\nPROMPT=\"Summarize this PDF and list its key chapters.\"\n\ncurl --fail-with-body --location \"$BASE_URL/v1/files\" \\\n  --header \"Authorization: Bearer $MODELVERSE_API_KEY\" \\\n  --form 'purpose=batch:gcs' \\\n  --form 'usage=inference' \\\n  --form \"model=$MODEL\" \\\n  --form \"file=@$FILE_PATH;type=application/pdf\" \\\n  --output upload.json\n```\n\nExample successful response (the bucket, object name, and signed URL are illustrative; use the values actually returned):\n\n```json\n{\n  \"id\": \"6fd9bc58-d80e-47cb-b6ab-5b0e19173487.pdf\",\n  \"object\": \"file\",\n  \"bytes\": 52428800,\n  \"created_at\": 1794441600,\n  \"expires_at\": 1795046400,\n  \"filename\": \"document.pdf\",\n  \"purpose\": \"batch:gcs\",\n  \"gcs_uri\": \"gs://example-modelverse-bucket/6fd9bc58-d80e-47cb-b6ab-5b0e19173487.pdf\",\n  \"s3_url\": \"https://storage.googleapis.com/example-modelverse-bucket/6fd9bc58-d80e-47cb-b6ab-5b0e19173487.pdf?REPLACE_WITH_RETURNED_SIGNATURE\"\n}\n```\n\n| Response field | Description |\n| --- | --- |\n| `id` | Platform file identifier. Pass the full `gcs_uri` for analysis, not just `id`. |\n| `gcs_uri` | Full `gs://` URI to pass as `fileData.fileUri` in the next step. |\n| `s3_url` | Signed HTTPS URL, also usable for media analysis. Do not edit its signature parameters. |\n| `bytes` / `filename` | File size in bytes and original filename. |\n| `created_at` / `expires_at` | Creation and expiration times as Unix timestamps in seconds. Uploaded files currently remain valid for 7 days; use the returned `expires_at` as the source of truth. |\n\n## 2. Analyze the uploaded file\n\nExtract `gcs_uri` from the saved `upload.json` and use it as `fileData.fileUri`, with `application/pdf` as the PDF's `mimeType`. These commands build the request JSON, run analysis, and print the resulting text:\n\n```bash\nGCS_URI=$(jq -er '.gcs_uri | select(startswith(\"gs://\"))' upload.json)\njq -n --arg uri \"$GCS_URI\" --arg prompt \"$PROMPT\" '{\n  contents: [{\n    role: \"user\",\n    parts: [\n      {fileData: {fileUri: $uri, mimeType: \"application/pdf\"}},\n      {text: $prompt}\n    ]\n  }]\n}' > analysis-request.json\n\ncurl --fail-with-body --location \"$BASE_URL/v1beta/models/$MODEL:generateContent\" \\\n  --header \"Authorization: Bearer $MODELVERSE_API_KEY\" \\\n  --header 'Content-Type: application/json' \\\n  --data-binary @analysis-request.json \\\n  --output analysis.json\n\njq -r '.candidates[]?.content.parts[]? | .text // empty' analysis.json\n```\n\nRead analysis text from `candidates[].content.parts[].text` and token usage from `usageMetadata`. The request examples also cover images, video, audio, text files, and a GCS PDF.\n\n## Limits and troubleshooting\n\n- The upload request body limit is **1 GiB (1,073,741,824 bytes, including multipart overhead)**. GCS references support large files, while the selected model still imposes its own file size, page count, duration, and context token limits.\n- GCS files must have been uploaded through this platform under the current company and organization and must not have expired. Re-upload expired files and use the new `gcs_uri`; a `gs://` reference is not permanent.\n- All GCS files in one request must belong to the same provider and project. Any explicit cache used with them must also match. If they do not match, prepare compatible files or cache in the same environment and organization.\n- Media parts accept `fileData.mimeType` / `fileData.fileUri` or `file_data.mime_type` / `file_data.file_uri`; use only one naming style per field. MIME types must match the actual format: `application/pdf` for PDF, `image/jpeg` for JPEG, `video/mp4` for MP4, and `audio/mpeg` for MP3.\n- A GCS URI must include a bucket and object path, without query parameters or a fragment. Do not append HTTPS signature parameters to it.\n\n| Error or symptom | Action |\n| --- | --- |\n| Upload: `model is required for inference uploads` | Include a nonempty `model` form field. |\n| Upload: `usage must be batch or inference` | Use `usage=inference` for media analysis uploads. |\n| `400`: `invalid GCS file URI` / `GCS file mimeType is required` | Use the full returned `gcs_uri` and provide the correct MIME type. |\n| `404`: `GCS file not found or expired` | Check the environment, company, organization, and expiration time; re-upload if needed. |\n| `400`: `file provider is not available for requested model` | The file cannot be used with the requested model. Check model and file compatibility in this environment. |\n| `400`: `referenced files belong to different providers or projects` | The referenced GCS files are incompatible; prepare matching files. |\n| `503`: `affinity_unavailable` | The file service is temporarily unavailable. Retry later; contact support with the request ID if it persists. |\n| Public URL cannot be read | Check server reachability, signature expiration, and the MIME type. |\n\nSee the [Gemini documentation](https://docs.cloud.google.com/vertex-ai/generative-ai/docs/multimodal/image-understanding) for formats and model capabilities.",
        "parameters": [
          {
            "name": "modelsId",
            "in": "path",
            "required": true,
            "description": "Gemini model ID supporting the supplied media format, for example `gemini-4-argon`.",
            "schema": {
              "type": "string",
              "example": "gemini-4-argon"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/GeminiMediaGenerateContentRequest"
              },
              "examples": {
                "gcsPdf": {
                  "summary": "Analyze a large PDF from GCS",
                  "description": "Replace fileUri with gcs_uri from the upload response.",
                  "value": {
                    "contents": [
                      {
                        "role": "user",
                        "parts": [
                          {
                            "fileData": {
                              "fileUri": "gs://example-modelverse-bucket/6fd9bc58-d80e-47cb-b6ab-5b0e19173487.pdf",
                              "mimeType": "application/pdf"
                            }
                          },
                          {
                            "text": "Summarize this PDF and list its key chapters."
                          }
                        ]
                      }
                    ]
                  }
                },
                "image": {
                  "summary": "Image analysis",
                  "value": {
                    "contents": [
                      {
                        "role": "user",
                        "parts": [
                          {
                            "file_data": {
                              "mime_type": "image/jpeg",
                              "file_uri": "https://example-file-host/modelverse/demo-image.jpg"
                            }
                          },
                          {
                            "text": "Describe the main objects and scene in this image."
                          }
                        ]
                      }
                    ]
                  }
                },
                "video": {
                  "summary": "Video analysis",
                  "value": {
                    "contents": [
                      {
                        "role": "user",
                        "parts": [
                          {
                            "file_data": {
                              "mime_type": "video/mp4",
                              "file_uri": "https://example-file-host/modelverse/demo-video.mp4"
                            }
                          },
                          {
                            "text": "Please summarize the main events of this video and list key segments in chronological order."
                          }
                        ]
                      }
                    ]
                  }
                },
                "audio": {
                  "summary": "Audio analysis",
                  "value": {
                    "contents": [
                      {
                        "role": "user",
                        "parts": [
                          {
                            "file_data": {
                              "mime_type": "audio/mpeg",
                              "file_uri": "https://example-file-host/modelverse/demo-audio.mp3"
                            }
                          },
                          {
                            "text": "Please transcribe this audio and summarize its key points."
                          }
                        ]
                      }
                    ]
                  }
                },
                "textFile": {
                  "summary": "Text file analysis",
                  "value": {
                    "contents": [
                      {
                        "role": "user",
                        "parts": [
                          {
                            "fileData": {
                              "mimeType": "text/plain",
                              "fileUri": "https://example-file-host/modelverse/demo.txt"
                            }
                          },
                          {
                            "text": "What is in the text?"
                          }
                        ]
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Analysis succeeded. Returns a Gemini content generation response.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GeminiMediaGenerateContentResponse"
                },
                "examples": {
                  "success": {
                    "summary": "Media analysis result",
                    "value": {
                      "candidates": [
                        {
                          "content": {
                            "role": "model",
                            "parts": [
                              {
                                "text": "The scene contains a laptop and a cup of coffee, resembling a work desk."
                              }
                            ]
                          },
                          "finishReason": "STOP"
                        }
                      ],
                      "usageMetadata": {
                        "promptTokenCount": 258,
                        "candidatesTokenCount": 32,
                        "totalTokenCount": 290
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid request parameters, MIME mismatch, invalid GCS URI, or file incompatible with the requested model.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GeminiMediaErrorResponse"
                },
                "examples": {
                  "gcsError": {
                    "value": {
                      "error": {
                        "message": "GCS file mimeType is required",
                        "type": "invalid_request_error",
                        "code": "param_error",
                        "param": "req_example"
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "GCS file is missing, expired, or not owned by the current company and organization.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GeminiMediaErrorResponse"
                },
                "examples": {
                  "gcsError": {
                    "value": {
                      "error": {
                        "message": "GCS file not found or expired",
                        "type": "not_found_error",
                        "code": "not_found",
                        "param": "req_example"
                      }
                    }
                  }
                }
              }
            }
          },
          "503": {
            "description": "The file service is temporarily unavailable; retry later.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GeminiMediaErrorResponse"
                },
                "examples": {
                  "gcsError": {
                    "value": {
                      "error": {
                        "message": "GCS file provider credentials unavailable",
                        "type": "internal_error",
                        "code": "affinity_unavailable",
                        "param": "req_example"
                      }
                    }
                  }
                }
              }
            }
          },
          "default": {
            "description": "Error response.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GeminiMediaErrorResponse"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "python",
            "label": "Python: upload and analyze a PDF (pip install httpx google-genai)",
            "source": "import os\nfrom pathlib import Path\n\nimport httpx\nfrom google import genai\nfrom google.genai.types import HttpOptions, Part\n\nbase_url = os.environ.get(\"MODELVERSE_BASE_URL\", \"https://api.modelverse.cn\")\napi_key = os.environ[\"MODELVERSE_API_KEY\"]\nmodel = \"gemini-4-argon\"\nfile_path = Path(\"/path/to/document.pdf\")\n\nwith httpx.Client(timeout=600.0) as http:\n    with file_path.open(\"rb\") as media:\n        uploaded = http.post(\n            f\"{base_url}/v1/files\",\n            headers={\"Authorization\": f\"Bearer {api_key}\"},\n            data={\"purpose\": \"batch:gcs\", \"usage\": \"inference\", \"model\": model},\n            files={\"file\": (file_path.name, media, \"application/pdf\")},\n        )\n    uploaded.raise_for_status()\n    gcs_uri = uploaded.json()[\"gcs_uri\"]\n\nwith genai.Client(\n    api_key=api_key,\n    http_options=HttpOptions(api_version=\"v1beta\", base_url=base_url, timeout=600_000),\n) as client:\n    response = client.models.generate_content(\n        model=model,\n        contents=[\n            Part.from_uri(file_uri=gcs_uri, mime_type=\"application/pdf\"),\n            \"Summarize this PDF and list its key chapters.\",\n        ],\n    )\n    print(response.text)"
          }
        ]
      }
    },
    "/v1beta/cachedContents": {
      "post": {
        "tags": [
          "Gemini Add-ons"
        ],
        "operationId": "createGeminiCachedContent",
        "summary": "Gemini Explicit Caching",
        "description": "Explicit caching reuses large context that would otherwise be resent on every request — product manuals, knowledge bases, fixed system rules, images, audio, or video. Create the shared context once, then send only `cache_id` plus the new question to avoid retransmitting and reprocessing it.\n\n`systemInstruction` (optional fixed role and answering rules, text parts only) and `contents` (the material to reuse) from the create request are stored together as one cache, and at least one of them must contain a non-empty part. Cache content cannot be modified and cannot be deleted manually; you can only extend its validity (see \"Extend Gemini Cache Validity\"), after which it expires automatically and disappears from the cache list.\n\n## Supported models and minimum cache tokens\n\n| Model ID | Minimum cache tokens |\n| --- | ---: |\n| `gemini-2.5-flash` | 2,048 |\n| `gemini-3.5-flash-lite`, `gemini-3.5-flash`, `gemini-3.6-flash`, `gemini-3.1-pro-preview`, `gemini-3-flash-preview` | 4,096 |\n\nGemini models outside this table cannot create explicit caches even though they generate content normally, and content below the minimum token count fails to create.\n\n## Using a cache\n\nSave `cache_id` from the create response (never Google's `projects/.../cachedContents/...` resource name), then call `generateContent` or `streamGenerateContent` on the same model with only `cachedContent` and the new question:\n\n```json\n{\n  \"cachedContent\": \"cache_abc123\",\n  \"contents\": [{ \"role\": \"user\", \"parts\": [{ \"text\": \"Summarize the main features based on the cached product manual.\" }] }]\n}\n```\n\n- Use the same API Key and the same model as at creation time, and the cache must still be valid; other API Keys in the same company cannot see it.\n- Do not resend `systemInstruction`, `tools`, or `toolConfig`; `generationConfig`, `safetySettings`, and request-specific `contents` (including new `inlineData` images) work as usual.\n- New content in a request is never written back to the cache — create another cache if it also needs to be reused.\n- On a cache hit, `usageMetadata.cachedContentTokenCount` reports the cached tokens reused by that request.\n\n## Validity and billing\n\n- Pass either `ttl` or `expire_time`, never both; with neither, the cache expires in about 60 minutes and the response `expire_time` is authoritative.\n- The minimum `ttl` is 60 seconds, and the final expiration after create or update cannot exceed 7 days from that request.\n- Creation charges all cached tokens once as input, and storage is charged from `created_at` to `expire_time`; extending only charges the additional storage window.\n- Cached tokens are billed as cache reads on use, and using a cache does not refresh its validity. Actual prices follow the ModelVerse billing documentation.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/GeminiCacheCreateCachedContentRequest"
              },
              "examples": {
                "create": {
                  "summary": "Create a product manual cache",
                  "value": {
                    "model": "gemini-2.5-flash",
                    "displayName": "product-manual",
                    "ttl": "3600s",
                    "systemInstruction": {
                      "parts": [
                        {
                          "text": "You are a product support assistant. Answer based on the cached material first; when the material does not contain the answer, say so explicitly and do not guess."
                        }
                      ]
                    },
                    "contents": [
                      {
                        "role": "user",
                        "parts": [
                          {
                            "text": "Put the complete product manual, FAQs, and handling procedures that need to be reused here..."
                          }
                        ]
                      }
                    ]
                  }
                },
                "textImage": {
                  "summary": "Text and an image",
                  "value": {
                    "model": "gemini-2.5-flash",
                    "displayName": "product-image-context",
                    "ttl": "3600s",
                    "contents": [
                      {
                        "role": "user",
                        "parts": [
                          {
                            "text": "This is a screenshot of the product console. The blue area indicates the available quota, and the gray area indicates the used quota."
                          },
                          {
                            "inlineData": {
                              "mimeType": "image/png",
                              "data": "<IMAGE_BASE64>",
                              "displayName": "console.png"
                            }
                          },
                          {
                            "text": "Subsequent answers must explain the screenshot based on the meaning of the interface described above."
                          }
                        ]
                      }
                    ]
                  }
                },
                "pdfText": {
                  "summary": "PDF and a text description",
                  "value": {
                    "model": "gemini-2.5-flash",
                    "displayName": "product-manual",
                    "ttl": "7200s",
                    "contents": [
                      {
                        "role": "user",
                        "parts": [
                          {
                            "inlineData": {
                              "mimeType": "application/pdf",
                              "data": "<PDF_BASE64>",
                              "displayName": "product-manual.pdf"
                            }
                          },
                          {
                            "text": "Answer subsequent questions based on this product manual first; state explicitly when the manual contains no relevant information."
                          }
                        ]
                      }
                    ]
                  }
                },
                "audioGlossary": {
                  "summary": "Audio and a background glossary",
                  "value": {
                    "model": "gemini-2.5-flash",
                    "displayName": "meeting-audio",
                    "ttl": "3600s",
                    "contents": [
                      {
                        "role": "user",
                        "parts": [
                          {
                            "text": "Background glossary: ModelVerse is a product name, UMInfer is a service name, and UCloud is a company name."
                          },
                          {
                            "inlineData": {
                              "mimeType": "audio/mpeg",
                              "data": "<AUDIO_BASE64>",
                              "displayName": "weekly-meeting.mp3"
                            }
                          },
                          {
                            "text": "Preserve the capitalization of the proper nouns above when generating summaries later."
                          }
                        ]
                      }
                    ]
                  }
                },
                "fewShot": {
                  "summary": "System rules, multi-turn text, and an image",
                  "value": {
                    "model": "gemini-2.5-flash",
                    "displayName": "inspection-examples",
                    "ttl": "3600s",
                    "systemInstruction": {
                      "parts": [
                        {
                          "text": "You are a device inspection assistant and must output in three sections: Appearance, Ports, and Risks."
                        }
                      ]
                    },
                    "contents": [
                      {
                        "role": "user",
                        "parts": [
                          {
                            "text": "Please inspect this sample device."
                          },
                          {
                            "inlineData": {
                              "mimeType": "image/jpeg",
                              "data": "<SAMPLE_IMAGE_BASE64>",
                              "displayName": "sample-device.jpg"
                            }
                          }
                        ]
                      },
                      {
                        "role": "model",
                        "parts": [
                          {
                            "text": "Appearance: the casing is intact. Ports: no obstructions. Risks: no obvious risks found."
                          }
                        ]
                      }
                    ]
                  }
                },
                "multiImage": {
                  "summary": "Text and multiple images",
                  "value": {
                    "model": "gemini-2.5-flash",
                    "displayName": "device-images",
                    "ttl": "3600s",
                    "contents": [
                      {
                        "role": "user",
                        "parts": [
                          {
                            "text": "The first image is the front of the device:"
                          },
                          {
                            "inlineData": {
                              "mimeType": "image/jpeg",
                              "data": "<FRONT_IMAGE_BASE64>",
                              "displayName": "device-front.jpg"
                            }
                          },
                          {
                            "text": "The second image is the back of the device:"
                          },
                          {
                            "inlineData": {
                              "mimeType": "image/jpeg",
                              "data": "<BACK_IMAGE_BASE64>",
                              "displayName": "device-back.jpg"
                            }
                          }
                        ]
                      }
                    ]
                  }
                },
                "videoRequirement": {
                  "summary": "Video and analysis requirements",
                  "value": {
                    "model": "gemini-2.5-flash",
                    "displayName": "console-demo-video",
                    "ttl": "3600s",
                    "contents": [
                      {
                        "role": "user",
                        "parts": [
                          {
                            "inlineData": {
                              "mimeType": "video/mp4",
                              "data": "<VIDEO_BASE64>",
                              "displayName": "console-demo.mp4"
                            }
                          },
                          {
                            "text": "This is a screen recording of console operations. Subsequent answers must distinguish between page navigation, user input, and system responses."
                          }
                        ]
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Created successfully. Returns a ModelVerse cache ID.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GeminiCacheCachedContent"
                },
                "examples": {
                  "success": {
                    "summary": "Created",
                    "value": {
                      "cache_id": "cache_abc123",
                      "model": "gemini-2.5-flash",
                      "display_name": "product-manual",
                      "status": "active",
                      "created_at": "2026-07-24T02:00:00Z",
                      "updated_at": "2026-07-24T02:00:00Z",
                      "expire_time": "2026-07-24T03:00:00Z",
                      "total_token_count": 11426
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid request, such as cache content too short, both `ttl` and `expire_time` provided, or a model that does not support explicit caching.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GeminiCacheErrorResponse"
                }
              }
            }
          },
          "default": {
            "description": "Error response.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GeminiCacheErrorResponse"
                }
              }
            }
          }
        }
      },
      "get": {
        "tags": [
          "Gemini Add-ons"
        ],
        "operationId": "listGeminiCachedContents",
        "summary": "List Gemini Caches",
        "description": "List Gemini explicit caches that are still valid under the current API Key. Creating and using caches is covered in \"Gemini Explicit Caching\".\n\n- Only unexpired caches with `active` status created by the current API Key are returned; other API Keys in the same company cannot see them.\n- Each `cache_id` returns only its latest successful state, ordered by creation time descending.\n- When no valid cache exists, the response is `{\"cachedContents\":[]}`.\n- Create and update responses use `created_at`, `updated_at`, and `expire_time`; this API follows the Gemini list structure and uses `createTime`, `updateTime`, and `expireTime`.",
        "responses": {
          "200": {
            "description": "Cache list.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GeminiCacheListCachedContentsResponse"
                },
                "examples": {
                  "success": {
                    "value": {
                      "cachedContents": [
                        {
                          "cache_id": "cache_abc123",
                          "model": "gemini-2.5-flash",
                          "status": "active",
                          "display_name": "product-manual",
                          "createTime": "2026-07-24T02:00:00Z",
                          "updateTime": "2026-07-24T02:00:00Z",
                          "expireTime": "2026-07-24T03:00:00Z",
                          "total_token_count": 11426
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "default": {
            "description": "Error response.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GeminiCacheErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/v1beta/cachedContents/{cache_id}": {
      "patch": {
        "tags": [
          "Gemini Add-ons"
        ],
        "operationId": "updateGeminiCachedContent",
        "summary": "Extend Gemini Cache Validity",
        "description": "Extend the validity of a Gemini explicit cache. Cache content and model cannot be changed. The request body must contain exactly one of `ttl` or `expire_time`; creating and using caches is covered in \"Gemini Explicit Caching\".\n\n- `ttl` is added to the **current expiration time** rather than recalculated from the request time: with a current expiration of `10:30:00Z`, `{\"ttl\":\"600s\"}` moves it to `10:40:00Z`.\n- `expire_time` must be later than the current expiration and at least 60 seconds after the request time. You do not need to look up or resend the old expiration — the server reads and validates the current cache state.\n- The final expiration cannot exceed 7 days from this request, so how much you can extend depends on the remaining validity.\n- In the response, `old_expire_time` is the expiration before the update and `expire_time` is the one that actually took effect.",
        "parameters": [
          {
            "name": "cache_id",
            "in": "path",
            "required": true,
            "description": "The ModelVerse cache ID returned when the cache was created.",
            "schema": {
              "type": "string",
              "example": "cache_abc123"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/GeminiCacheUpdateCachedContentRequest"
              },
              "examples": {
                "ttl": {
                  "summary": "Extend with relative TTL",
                  "value": {
                    "ttl": "600s"
                  }
                },
                "expireTime": {
                  "summary": "Extend with absolute expiration time",
                  "value": {
                    "expire_time": "2026-07-24T12:00:00Z"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Updated successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GeminiCacheCachedContent"
                },
                "examples": {
                  "success": {
                    "value": {
                      "cache_id": "cache_abc123",
                      "model": "gemini-2.5-flash",
                      "display_name": "product-manual",
                      "status": "active",
                      "created_at": "2026-07-24T02:00:00Z",
                      "updated_at": "2026-07-24T02:10:00Z",
                      "old_expire_time": "2026-07-24T03:00:00Z",
                      "expire_time": "2026-07-24T03:10:00Z"
                    }
                  }
                }
              }
            }
          },
          "default": {
            "description": "Error response.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GeminiCacheErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/v1beta/models/{modelsId}:embedContent": {
      "post": {
        "tags": [
          "Gemini Add-ons"
        ],
        "operationId": "embedGeminiContent",
        "summary": "Gemini Embedding 2",
        "description": "Gemini Embedding 2 (`gemini-embedding-2`) is Google's multimodal embedding model. It turns text, images, video, audio, and PDFs into high-dimensional vectors for multimodal semantic search, content recommendation, clustering, and anomaly detection. A single request may mix modalities; for text-only embeddings the OpenAI-compatible `POST /v1/embeddings` also works.\n\n`content.parts[]` accepts text parts `{\"text\":\"...\"}` and file parts `{\"file_data\":{\"mime_type\":\"...\",\"file_uri\":\"...\"}}`, where files must be served from a URL the server can reach. The response returns the `embedding.values` vector and per-modality token usage in `usageMetadata`.\n\n## Output dimensionality\n\n`outputDimensionality` accepts 128 to 3072 and defaults to 3072. Lowering it to 768 or 1536 reduces storage and compute cost with a slight, usually negligible, loss of semantic search accuracy; keep the default when accuracy matters most.\n\n## Per-request limits\n\n| Modality | Max count | Other limits | Supported MIME |\n| --- | --- | --- | --- |\n| Image | 6 | — | `image/png`, `image/jpeg`, `image/webp`, `image/bmp`, `image/heic`, `image/heif`, `image/avif` |\n| Document | 1 | Up to 6 pages | `application/pdf` |\n| Video | 1 | Up to 80s with audio, 120s without | `video/mp4`, `video/mpeg` |\n| Audio | 1 | Up to 180s | `audio/mp3`, `audio/wav` |",
        "parameters": [
          {
            "name": "modelsId",
            "in": "path",
            "required": true,
            "description": "Use `gemini-embedding-2`.",
            "schema": {
              "type": "string",
              "example": "gemini-embedding-2"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/GeminiEmbeddingEmbedContentRequest"
              },
              "examples": {
                "multimodal": {
                  "summary": "Multimodal embedding",
                  "value": {
                    "content": {
                      "parts": [
                        {
                          "text": "Whats this"
                        },
                        {
                          "text": "Whats this like"
                        },
                        {
                          "file_data": {
                            "mime_type": "video/mp4",
                            "file_uri": "https://example.com/video.mp4"
                          }
                        },
                        {
                          "file_data": {
                            "mime_type": "image/png",
                            "file_uri": "https://example.com/image.png"
                          }
                        },
                        {
                          "file_data": {
                            "mime_type": "audio/wav",
                            "file_uri": "https://example.com/audio.wav"
                          }
                        },
                        {
                          "file_data": {
                            "mime_type": "application/pdf",
                            "file_uri": "https://example.com/document.pdf"
                          }
                        }
                      ]
                    }
                  }
                },
                "outputDimensionality": {
                  "summary": "Custom output dimension",
                  "value": {
                    "outputDimensionality": 768,
                    "content": {
                      "parts": [
                        {
                          "text": "Find video tutorials about machine learning"
                        },
                        {
                          "file_data": {
                            "mime_type": "image/png",
                            "file_uri": "https://example.com/ml-diagram.png"
                          }
                        }
                      ]
                    }
                  }
                },
                "semanticSearch": {
                  "summary": "Multimodal semantic search",
                  "value": {
                    "content": {
                      "parts": [
                        {
                          "text": "Find video tutorials about machine learning"
                        },
                        {
                          "file_data": {
                            "mime_type": "image/png",
                            "file_uri": "https://example.com/ml-diagram.png"
                          }
                        }
                      ]
                    }
                  }
                },
                "videoOnly": {
                  "summary": "Video content embedding",
                  "value": {
                    "content": {
                      "parts": [
                        {
                          "file_data": {
                            "mime_type": "video/mp4",
                            "file_uri": "https://example.com/tutorial.mp4"
                          }
                        }
                      ]
                    }
                  }
                },
                "pdf": {
                  "summary": "PDF document embedding",
                  "value": {
                    "content": {
                      "parts": [
                        {
                          "text": "Summarize the key points of this report"
                        },
                        {
                          "file_data": {
                            "mime_type": "application/pdf",
                            "file_uri": "https://example.com/report.pdf"
                          }
                        }
                      ]
                    }
                  }
                },
                "audio": {
                  "summary": "Audio embedding",
                  "value": {
                    "content": {
                      "parts": [
                        {
                          "file_data": {
                            "mime_type": "audio/wav",
                            "file_uri": "https://example.com/speech.wav"
                          }
                        }
                      ]
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Embedding vector and usage information.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GeminiEmbeddingEmbedContentResponse"
                },
                "examples": {
                  "success": {
                    "summary": "Embedding response",
                    "value": {
                      "embedding": {
                        "values": [
                          0.0015015427,
                          0.014678672,
                          -0.018105509,
                          -0.013457718,
                          0.015227248,
                          0.003112343
                        ]
                      },
                      "usageMetadata": {
                        "promptTokenCount": 2517,
                        "totalTokenCount": 2517,
                        "promptTokensDetails": [
                          {
                            "modality": "VIDEO",
                            "tokenCount": 330
                          },
                          {
                            "modality": "TEXT",
                            "tokenCount": 5
                          },
                          {
                            "modality": "DOCUMENT",
                            "tokenCount": 1548
                          },
                          {
                            "modality": "IMAGE",
                            "tokenCount": 258
                          },
                          {
                            "modality": "AUDIO",
                            "tokenCount": 376
                          }
                        ]
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid request, such as `outputDimensionality` out of range, inaccessible file URI, or MIME type mismatch.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GeminiEmbeddingErrorResponse"
                }
              }
            }
          },
          "default": {
            "description": "Error response.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GeminiEmbeddingErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/v1/files": {
      "post": {
        "tags": [
          "Gemini Add-ons"
        ],
        "operationId": "uploadGeminiBatchGcsFile",
        "summary": "Upload Gemini Batch Input File",
        "description": "Upload an input file for Gemini batch tasks. `purpose` must be `batch:gcs`, and the file is JSONL. The returned `id` is the object name in storage; when creating a job, construct a full GCS URI such as `gs://gemini-batch-001/<uploaded_id>`.",
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "$ref": "#/components/schemas/GeminiBatchUploadGeminiBatchFileRequest"
              },
              "examples": {
                "default": {
                  "summary": "Upload a JSONL file",
                  "value": {
                    "purpose": "batch:gcs",
                    "file": "/path/to/your-input.jsonl"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Upload succeeded.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GeminiBatchFileObject"
                },
                "examples": {
                  "success": {
                    "value": {
                      "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"
                    }
                  }
                }
              }
            }
          },
          "default": {
            "description": "Error response.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GeminiBatchErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/v1beta/batchPredictionJobs": {
      "post": {
        "tags": [
          "Gemini Add-ons"
        ],
        "operationId": "createGeminiBatchPredictionJob",
        "summary": "Gemini Batch Tasks",
        "description": "Create a Gemini (Vertex-style) batch prediction job for large-scale asynchronous text generation. `model` must be a batch model name; see the Model Marketplace for the supported batch models.\n\nThe full flow has four steps, one API each:\n\n1. **Upload the input file** (`POST /v1/files`, see \"Upload Gemini Batch Input File\"): upload JSONL with `purpose` fixed to `batch:gcs` and keep the `id` from the response.\n2. **Create the job** (this API): pass `inputConfig.gcsSource.uris` as the full GCS URI built from that `id` — `gs://gemini-batch-001/<id>`, a single string rather than an array — and set `outputConfig.gcsDestination.outputUriPrefix` to `gs://gemini-batch-001/output`. The bucket `gemini-batch-001` is assigned by the platform.\n3. **Poll the job state** (`GET /v1beta/batchPredictionJobs/{job_id}`, see \"Retrieve Gemini Batch Job Status\"): `job_id` is the last segment of `name` in the create response; poll until `JOB_STATE_SUCCEEDED` or a failure state.\n4. **Download the results** (`GET /v1/batchPredictionJobs/content`, see \"Download Gemini Batch Job Results\"): pass `outputInfo.gcsOutputDirectory` from the status response as `file_id` — it is the output directory, not a single file — and the service returns `predictions.jsonl` from it.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/GeminiBatchCreateBatchPredictionJobRequest"
              },
              "examples": {
                "default": {
                  "summary": "Create a Gemini batch prediction job",
                  "value": {
                    "displayName": "my-cloud-storage-batch-inference-job",
                    "model": "publishers/google/models/gemini-3-flash-preview",
                    "inputConfig": {
                      "instancesFormat": "jsonl",
                      "gcsSource": {
                        "uris": "gs://gemini-batch-001/1773236148797418904_gemini-3.1-pro-preview.jsonl"
                      }
                    },
                    "outputConfig": {
                      "predictionsFormat": "jsonl",
                      "gcsDestination": {
                        "outputUriPrefix": "gs://gemini-batch-001/output"
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Created successfully. Returns a Vertex-style job object.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GeminiBatchBatchPredictionJob"
                },
                "examples": {
                  "success": {
                    "value": {
                      "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",
                      "modelVersionId": "1"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid request, such as malformed GCS URI, unsupported input/output format, or unavailable model.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GeminiBatchErrorResponse"
                }
              }
            }
          },
          "default": {
            "description": "Error response.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GeminiBatchErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/v1beta/batchPredictionJobs/{job_id}": {
      "get": {
        "tags": [
          "Gemini Add-ons"
        ],
        "operationId": "getGeminiBatchPredictionJob",
        "summary": "Retrieve Gemini Batch Job Status",
        "description": "Retrieve Gemini batch job status by `job_id`. The `job_id` is usually the last segment of the `name` field returned by the create API. After completion, use `outputInfo.gcsOutputDirectory` as the output directory for downloading results.",
        "parameters": [
          {
            "name": "job_id",
            "in": "path",
            "required": true,
            "description": "Job ID, usually the last segment of the `name` field returned by the create API.",
            "schema": {
              "type": "string",
              "example": "7737084104264384512"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Job details.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GeminiBatchBatchPredictionJob"
                }
              }
            }
          },
          "default": {
            "description": "Error response.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GeminiBatchErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/v1/batchPredictionJobs/content": {
      "get": {
        "tags": [
          "Gemini Add-ons"
        ],
        "operationId": "downloadGeminiBatchPredictionJobContent",
        "summary": "Download Gemini Batch Job Results",
        "description": "Download `predictions.jsonl` for a completed Gemini batch job. `file_id` must be the output directory from `outputInfo.gcsOutputDirectory`, not a single file name; the service locates and returns the result file under that directory.",
        "parameters": [
          {
            "name": "file_id",
            "in": "query",
            "required": true,
            "description": "Output directory, for example `gs://gemini-batch-001/output/prediction-model-...`.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "`predictions.jsonl` file content.",
            "content": {
              "application/jsonl": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              },
              "application/octet-stream": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "default": {
            "description": "Error response.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GeminiBatchErrorResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "API key",
        "description": "Pass the API Key with `Authorization: Bearer <your_api_key>`."
      },
      "xGoogApiKey": {
        "type": "apiKey",
        "in": "header",
        "name": "x-goog-api-key",
        "description": "Gemini-compatible API Key header."
      }
    },
    "schemas": {
      "GeminiMediaGenerateContentRequest": {
        "type": "object",
        "additionalProperties": true,
        "required": [
          "contents"
        ],
        "properties": {
          "contents": {
            "type": "array",
            "minItems": 1,
            "description": "Conversation content list. Media analysis usually sends one user message containing media parts and a text prompt.",
            "items": {
              "$ref": "#/components/schemas/GeminiMediaContent"
            }
          }
        }
      },
      "GeminiMediaContent": {
        "type": "object",
        "additionalProperties": true,
        "properties": {
          "role": {
            "type": "string",
            "description": "Message role. Media analysis usually sends a single `user` message.",
            "enum": [
              "user",
              "model"
            ]
          },
          "parts": {
            "type": "array",
            "description": "Message parts, which may mix media parts and text prompts.",
            "items": {
              "$ref": "#/components/schemas/GeminiMediaPart"
            }
          }
        }
      },
      "GeminiMediaPart": {
        "type": "object",
        "additionalProperties": true,
        "properties": {
          "text": {
            "type": "string",
            "description": "Question or instruction text."
          },
          "file_data": {
            "$ref": "#/components/schemas/GeminiMediaFileData"
          },
          "fileData": {
            "$ref": "#/components/schemas/GeminiMediaFileDataCamel"
          }
        }
      },
      "GeminiMediaFileData": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "mime_type",
          "file_uri"
        ],
        "description": "Media file in snake_case form. Equivalent to `fileData`; use only one of them per part.",
        "properties": {
          "mime_type": {
            "type": "string",
            "description": "Media MIME type, which must match the actual file format.",
            "examples": [
              "image/jpeg",
              "video/mp4",
              "audio/mpeg",
              "application/pdf"
            ]
          },
          "file_uri": {
            "type": "string",
            "format": "uri",
            "description": "Media URI. Use the returned `gcs_uri` (gs://, recommended for large files), `s3_url` (HTTPS), or another server-reachable public URL. GCS files must belong to the current company and organization and remain valid; use the returned URI without constructing it yourself."
          }
        }
      },
      "GeminiMediaFileDataCamel": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "mimeType",
          "fileUri"
        ],
        "description": "Media file in camelCase form. Equivalent to `file_data`; use only one of them per part.",
        "properties": {
          "mimeType": {
            "type": "string",
            "description": "Media MIME type, which must match the actual file format."
          },
          "fileUri": {
            "type": "string",
            "format": "uri",
            "description": "Media URI. Use the returned `gcs_uri` (gs://, recommended for large files), `s3_url` (HTTPS), or another server-reachable public URL. GCS files must belong to the current company and organization and remain valid; use the returned URI without constructing it yourself."
          }
        }
      },
      "GeminiMediaGenerateContentResponse": {
        "type": "object",
        "additionalProperties": true,
        "properties": {
          "candidates": {
            "type": "array",
            "description": "Generated candidates. The analysis text is in `candidates[].content.parts[].text`.",
            "items": {
              "type": "object",
              "additionalProperties": true
            }
          },
          "usageMetadata": {
            "type": "object",
            "additionalProperties": true,
            "description": "Token usage, including `promptTokenCount`, `candidatesTokenCount`, and `totalTokenCount`."
          }
        }
      },
      "GeminiCacheCreateCachedContentRequest": {
        "type": "object",
        "additionalProperties": true,
        "required": [
          "model"
        ],
        "properties": {
          "model": {
            "type": "string",
            "description": "Gemini model ID that supports explicit caching. It must match when creating and using the cache.",
            "examples": [
              "gemini-2.5-flash",
              "gemini-3-flash-preview"
            ]
          },
          "contents": {
            "type": "array",
            "description": "Actual material to cache. Supports `text` and `inlineData` parts.",
            "items": {
              "$ref": "#/components/schemas/GeminiCacheContent"
            }
          },
          "systemInstruction": {
            "$ref": "#/components/schemas/GeminiCacheSystemInstruction"
          },
          "displayName": {
            "type": "string",
            "description": "Display name for easier identification."
          },
          "ttl": {
            "description": "Relative validity period. A string such as `3600s` is recommended; seconds/nanos object is also supported.",
            "oneOf": [
              {
                "type": "string",
                "title": "string"
              },
              {
                "type": "object",
                "additionalProperties": true,
                "title": "object"
              }
            ]
          },
          "expire_time": {
            "type": "string",
            "format": "date-time",
            "description": "Absolute expiration time in RFC 3339 format."
          }
        },
        "description": "Create cache request. Field naming compatibility is supported: `displayName/display_name`, `systemInstruction/system_instruction`, `inlineData/inline_data`, `mimeType/mime_type`, `cachedContent/cached_content`, and `expireTime/expire_time`. Do not pass both naming styles for the same field."
      },
      "GeminiCacheUpdateCachedContentRequest": {
        "type": "object",
        "additionalProperties": false,
        "description": "Extend-validity request. It must contain exactly one of `ttl` or `expire_time`.",
        "properties": {
          "ttl": {
            "description": "Duration added to the current expiration time. A string such as `600s` is recommended; a seconds/nanos object also works. Minimum 60 seconds.",
            "oneOf": [
              {
                "type": "string",
                "title": "string"
              },
              {
                "type": "object",
                "additionalProperties": true,
                "title": "object"
              }
            ]
          },
          "expire_time": {
            "type": "string",
            "format": "date-time",
            "description": "New absolute expiration time in RFC 3339 format. It must be later than the current expiration, at least 60 seconds after the request time, and within 7 days."
          }
        },
        "minProperties": 1,
        "maxProperties": 1
      },
      "GeminiCacheSystemInstruction": {
        "type": "object",
        "additionalProperties": true,
        "properties": {
          "parts": {
            "type": "array",
            "description": "Fixed role and answering rules cached alongside the content. Text parts only.",
            "items": {
              "type": "object",
              "additionalProperties": true,
              "properties": {
                "text": {
                  "type": "string"
                }
              }
            }
          }
        }
      },
      "GeminiCacheContent": {
        "type": "object",
        "additionalProperties": true,
        "properties": {
          "role": {
            "type": "string",
            "description": "Message role. Few-shot examples can use the `model` role for demonstration answers.",
            "enum": [
              "user",
              "model"
            ]
          },
          "parts": {
            "type": "array",
            "description": "Parts to cache, which may mix `text` and `inlineData`.",
            "items": {
              "type": "object",
              "additionalProperties": true,
              "properties": {
                "text": {
                  "type": "string",
                  "description": "Text content."
                },
                "inlineData": {
                  "type": "object",
                  "additionalProperties": true,
                  "description": "Base64-encoded blob. The total decoded size of all `inlineData` fields must not exceed 10 MiB.",
                  "required": [
                    "mimeType",
                    "data"
                  ],
                  "properties": {
                    "mimeType": {
                      "type": "string",
                      "description": "Standard MIME type of the file, which must match the actual content.",
                      "examples": [
                        "image/png",
                        "application/pdf",
                        "audio/mpeg",
                        "video/mp4"
                      ]
                    },
                    "data": {
                      "type": "string",
                      "description": "Base64 string of the file content (for example `base64 -w 0 product-manual.pdf`). Do not add a Data URL prefix such as `data:application/pdf;base64,`."
                    },
                    "displayName": {
                      "type": "string",
                      "description": "File name that helps the model and the caller identify the file."
                    }
                  }
                }
              }
            }
          }
        },
        "description": "Cached content message. One `parts` array may mix several text and blob parts, but each part must be either `text` or `inlineData` — never both. `systemInstruction.parts[]` supports text only, so media must be placed in `contents[].parts[].inlineData`. The caching APIs do not accept `fileData`, Cloud Storage URIs, or local file paths.\n\nCommon MIME types include `image/png`, `image/jpeg`, `image/webp`, `image/heic`, `application/pdf`, `text/plain`, `audio/mpeg`, `audio/wav`, `audio/flac`, `video/mp4`, `video/webm`, and `video/quicktime`. Actual support depends on the multimodal capability of the selected model, so re-check it when switching models."
      },
      "GeminiCacheCachedContent": {
        "type": "object",
        "additionalProperties": true,
        "description": "Cache object. Create and update responses use `created_at`, `updated_at`, and `expire_time`; the cache list follows the Gemini list structure and uses `createTime`, `updateTime`, and `expireTime`.",
        "properties": {
          "cache_id": {
            "type": "string",
            "description": "ModelVerse cache ID. Pass this value when using or updating the cache."
          },
          "model": {
            "type": "string",
            "description": "ModelVerse model ID used to create the cache."
          },
          "display_name": {
            "type": "string",
            "description": "Display name provided at creation time; omitted when not provided."
          },
          "status": {
            "type": "string",
            "description": "Cache status. Valid caches are `active`."
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "description": "Cache creation time (create and update responses)."
          },
          "updated_at": {
            "type": "string",
            "format": "date-time",
            "description": "Last update time (create and update responses)."
          },
          "old_expire_time": {
            "type": "string",
            "format": "date-time",
            "description": "Expiration time before the update. Returned only by the extend-validity response."
          },
          "expire_time": {
            "type": "string",
            "format": "date-time",
            "description": "Expiration time that actually took effect upstream."
          },
          "createTime": {
            "type": "string",
            "format": "date-time",
            "description": "Cache creation time (cache list response)."
          },
          "updateTime": {
            "type": "string",
            "format": "date-time",
            "description": "Last update time (cache list response)."
          },
          "expireTime": {
            "type": "string",
            "format": "date-time",
            "description": "Expiration time that actually took effect upstream (cache list response)."
          },
          "total_token_count": {
            "type": "integer",
            "description": "Total tokens of the whole cache, including `systemInstruction` and `contents`."
          }
        }
      },
      "GeminiCacheListCachedContentsResponse": {
        "type": "object",
        "additionalProperties": true,
        "properties": {
          "cachedContents": {
            "type": "array",
            "description": "Caches that are still valid. An empty array when none exist.",
            "items": {
              "$ref": "#/components/schemas/GeminiCacheCachedContent"
            }
          }
        }
      },
      "GeminiEmbeddingEmbedContentRequest": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "content"
        ],
        "properties": {
          "content": {
            "$ref": "#/components/schemas/GeminiEmbeddingContent"
          },
          "outputDimensionality": {
            "type": "integer",
            "minimum": 128,
            "maximum": 3072,
            "default": 3072,
            "description": "Output embedding dimension. Lower dimensions can reduce storage and compute costs."
          }
        }
      },
      "GeminiEmbeddingContent": {
        "type": "object",
        "additionalProperties": true,
        "required": [
          "parts"
        ],
        "properties": {
          "parts": {
            "type": "array",
            "minItems": 1,
            "description": "Content parts array. Supports text and multimodal files.",
            "items": {
              "$ref": "#/components/schemas/GeminiEmbeddingPart"
            }
          }
        }
      },
      "GeminiEmbeddingPart": {
        "type": "object",
        "additionalProperties": true,
        "properties": {
          "text": {
            "type": "string",
            "description": "Text content to embed."
          },
          "file_data": {
            "$ref": "#/components/schemas/GeminiEmbeddingFileData"
          }
        }
      },
      "GeminiEmbeddingFileData": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "mime_type",
          "file_uri"
        ],
        "properties": {
          "mime_type": {
            "type": "string",
            "description": "File MIME type, such as `video/mp4`, `image/png`, `audio/wav`, or `application/pdf`."
          },
          "file_uri": {
            "type": "string",
            "format": "uri",
            "description": "File URL accessible by the server."
          }
        },
        "description": "File part. Common types include images image/png, image/jpeg, image/webp; video video/mp4, video/mpeg; audio audio/wav, audio/mp3, audio/mpeg; and document application/pdf. The file URI must be accessible by the server."
      },
      "GeminiEmbeddingEmbedContentResponse": {
        "type": "object",
        "additionalProperties": true,
        "properties": {
          "embedding": {
            "type": "object",
            "additionalProperties": true,
            "description": "Embedding result.",
            "properties": {
              "values": {
                "type": "array",
                "description": "Embedding vector as a list of floats.",
                "items": {
                  "type": "number"
                }
              }
            }
          },
          "usageMetadata": {
            "type": "object",
            "additionalProperties": true,
            "description": "Token usage.",
            "properties": {
              "promptTokenCount": {
                "type": "integer",
                "description": "Total input tokens."
              },
              "totalTokenCount": {
                "type": "integer",
                "description": "Total tokens."
              },
              "promptTokensDetails": {
                "type": "array",
                "description": "Per-modality token usage breakdown.",
                "items": {
                  "type": "object",
                  "additionalProperties": true,
                  "properties": {
                    "modality": {
                      "type": "string",
                      "description": "Modality type.",
                      "enum": [
                        "TEXT",
                        "IMAGE",
                        "VIDEO",
                        "AUDIO",
                        "DOCUMENT"
                      ]
                    },
                    "tokenCount": {
                      "type": "integer",
                      "description": "Tokens consumed by that modality."
                    }
                  }
                }
              }
            }
          }
        }
      },
      "GeminiBatchUploadGeminiBatchFileRequest": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "purpose",
          "file"
        ],
        "properties": {
          "purpose": {
            "type": "string",
            "const": "batch:gcs",
            "description": "Gemini batch input files must use `batch:gcs`."
          },
          "file": {
            "type": "string",
            "format": "binary",
            "description": "JSONL input file."
          }
        }
      },
      "GeminiBatchFileObject": {
        "type": "object",
        "additionalProperties": true,
        "properties": {
          "id": {
            "type": "string",
            "description": "Object name in storage. Build the full GCS URI `gs://gemini-batch-001/<id>` from it when creating a job."
          },
          "object": {
            "type": "string",
            "const": "file",
            "description": "Always `file`."
          },
          "bytes": {
            "type": "integer",
            "format": "int64",
            "description": "File size in bytes."
          },
          "created_at": {
            "type": "integer",
            "format": "int64",
            "description": "Creation timestamp."
          },
          "filename": {
            "type": "string",
            "description": "File name."
          },
          "purpose": {
            "type": "string",
            "description": "Same as the request, always `batch:gcs`."
          }
        }
      },
      "GeminiBatchCreateBatchPredictionJobRequest": {
        "type": "object",
        "additionalProperties": true,
        "required": [
          "model",
          "inputConfig",
          "outputConfig"
        ],
        "properties": {
          "displayName": {
            "type": "string",
            "description": "Job display name."
          },
          "model": {
            "type": "string",
            "description": "Must be a batch model name. See the Model Marketplace for the supported batch models.",
            "examples": [
              "publishers/google/models/gemini-3.1-pro-preview",
              "publishers/google/models/gemini-3-flash-preview"
            ]
          },
          "inputConfig": {
            "type": "object",
            "additionalProperties": true,
            "description": "Input configuration.",
            "required": [
              "instancesFormat",
              "gcsSource"
            ],
            "properties": {
              "instancesFormat": {
                "type": "string",
                "examples": [
                  "jsonl"
                ]
              },
              "gcsSource": {
                "type": "object",
                "additionalProperties": true,
                "properties": {
                  "uris": {
                    "oneOf": [
                      {
                        "type": "string",
                        "title": "string"
                      },
                      {
                        "type": "array",
                        "items": {
                          "type": "string"
                        },
                        "title": "array"
                      }
                    ],
                    "description": "Full GCS URI of the input file. Only a single string is supported, in the form `gs://gemini-batch-001/<uploaded id>`."
                  }
                }
              }
            }
          },
          "outputConfig": {
            "type": "object",
            "additionalProperties": true,
            "description": "Output configuration.",
            "required": [
              "predictionsFormat",
              "gcsDestination"
            ],
            "properties": {
              "predictionsFormat": {
                "type": "string",
                "examples": [
                  "jsonl"
                ]
              },
              "gcsDestination": {
                "type": "object",
                "additionalProperties": true,
                "properties": {
                  "outputUriPrefix": {
                    "type": "string",
                    "description": "Output directory prefix, which must be `gs://gemini-batch-001/output`."
                  }
                }
              }
            }
          }
        }
      },
      "GeminiBatchBatchPredictionJob": {
        "type": "object",
        "additionalProperties": true,
        "properties": {
          "name": {
            "type": "string",
            "description": "Job resource name or short ID."
          },
          "state": {
            "type": "string",
            "description": "Job state. `JOB_STATE_PENDING` created and waiting to be scheduled, `JOB_STATE_RUNNING` in progress, `JOB_STATE_SUCCEEDED` finished successfully, `JOB_STATE_FAILED` failed, `JOB_STATE_CANCELLED` cancelled, `JOB_STATE_PAUSED` paused.",
            "enum": [
              "JOB_STATE_PENDING",
              "JOB_STATE_RUNNING",
              "JOB_STATE_SUCCEEDED",
              "JOB_STATE_FAILED",
              "JOB_STATE_CANCELLED",
              "JOB_STATE_PAUSED"
            ]
          },
          "outputInfo": {
            "type": "object",
            "additionalProperties": true,
            "description": "Output information, available once the job finishes.",
            "properties": {
              "gcsOutputDirectory": {
                "type": "string",
                "description": "Output directory used as `file_id` when downloading results."
              }
            }
          },
          "completionStats": {
            "type": "object",
            "additionalProperties": true,
            "description": "Completion statistics such as `successfulCount`."
          }
        }
      },
      "GeminiMediaErrorResponse": {
        "$ref": "#/components/schemas/ModelVerseErrorResponse"
      },
      "GeminiCacheErrorResponse": {
        "$ref": "#/components/schemas/ModelVerseErrorResponse"
      },
      "GeminiEmbeddingErrorResponse": {
        "$ref": "#/components/schemas/ModelVerseErrorResponse"
      },
      "GeminiBatchErrorResponse": {
        "$ref": "#/components/schemas/ModelVerseErrorResponse"
      },
      "ModelVerseErrorResponse": {
        "type": "object",
        "additionalProperties": true,
        "description": "Error response. `error.message` is the error description, `error.code` is the error code, and `error.param` is usually a request identifier that helps with troubleshooting.",
        "properties": {
          "error": {
            "type": "object",
            "additionalProperties": true,
            "description": "Error details."
          }
        }
      }
    }
  }
}
```
