spb/doc-api

1# Gemini long-running operations (`Operation`, `*/operations`, `batches`, `generatedFiles`)23**Status:** `DOCUMENTED` · partly `LIVE_VERIFIED` 2026-09-18 (list model operations 200, list generatedFiles 200, list batches 200, error shapes for bogus names) · no real operation could be created with this key (Veo not run for cost; batch/tuning gated — see their pages).4**Sources:** [Batch reference — Resource: Operation](https://ai.google.dev/api/batch-api#Operation) · [Veo guide — asynchronous operations](https://ai.google.dev/gemini-api/docs/veo#handling-asynchronous-operations) · [Tuning reference](https://ai.google.dev/api/tuning) · [All methods](https://ai.google.dev/api/all-methods) · [Webhooks](https://ai.google.dev/gemini-api/docs/webhooks) · discovery v1beta rev. 20260918.5**Last verified:** 2026-09-18. Twins: endpoints fragment (api_family `operations`, `files`, `batch`), objects `Operation`, `Status`, `GeneratedFile`, lifecycles `Operation (predictLongRunning / Veo)`, `GeneratedFile`, `GenerateContentBatch`.67## 1. The `Operation` resource (google.longrunning)89```json10{"name": "models/veo-3.1-generate-preview/operations/abc123", "metadata": {"@type": "…", …}, "done": false}11{"name": "batches/123456789", "metadata": {"@type": "type.googleapis.com/google.ai.generativelanguage.v1beta.GenerateContentBatch", "state": "BATCH_STATE_PENDING", …}, "done": false}12{"name": "…", "done": true, "response": {"@type": "…", …}}      // exactly one of response | error when done13{"name": "…", "done": true, "error": {"code": 3, "message": "…", "status": "INVALID_ARGUMENT", "details": []}}14```1516| Field | Meaning |17|---|---|18| `name` | server-assigned; the resource path you poll |19| `metadata` | service-specific progress (`@type` + fields): Veo none/progress; batch → the `GenerateContentBatch` / `EmbedContentBatch` (with `state`, `batchStats`); tuning → `CreateTunedModelMetadata {tunedModel, totalSteps, completedSteps, completedPercent, snapshots[]}` |20| `done` | `false` while running |21| `response` | success payload (`PredictLongRunningResponse.generateVideoResponse`, `GenerateContentBatchOutput`, `TunedModel`) |22| `error` | `google.rpc.Status {code, message, details[]}`; code `1` = CANCELLED after `batches/*:cancel` |2324## 2. Who returns operations, and where to poll2526| Producer | Operation name pattern | Poll (GET) | List | Cancel | Delete |27|---|---|---|---|---|---|28| `models/{m}:predictLongRunning` (Veo) | `models/{m}/operations/{id}` | `GET /v1beta/{name}` | `GET /v1beta/models/{m}/operations` (`filter`, `pageSize`, `pageToken`, `returnPartialSuccess`) | — (none in discovery) | — |29| `models/{m}:batchGenerateContent`, `:asyncBatchEmbedContent` | `batches/{id}` | `GET /v1beta/batches/{id}` | `GET /v1beta/batches` | `POST /v1beta/batches/{id}:cancel` | `DELETE /v1beta/batches/{id}` (does not cancel) |30| `tunedModels` create | `tunedModels/{id}/operations/{op}` | `GET /v1beta/{name}` | `GET /v1beta/tunedModels/{id}/operations` | — | — |31| generated media | `generatedFiles/{id}/operations/{op}` | `GET /v1beta/{name}` | `GET /v1beta/generatedFiles` (files, not operations) | — | — |32| file search / corpora (other agents) | `fileSearchStores/{s}/operations/{op}`, `fileSearchStores/{s}/upload/operations/{op}`, `corpora/{c}/operations/{op}` | `GET /v1beta/{name}` | — | — | — |3334`GET /v1beta/{name}` works with the full `name` string returned by the producer — the guide's Veo loop is literally `curl "${BASE_URL}/${operation_name}"`. SDK: `client.operations.get(operation)` (Python), `ai.operations.getVideosOperation({operation})` (Node); batches have their own `client.batches.get`.3536## 3. Polling guidance and alternatives3738* Veo: poll every ~10 s; total latency 11 s – 6 min. Batch: minutes to 24 h (expiry 48 h); poll every 20–60 s or use webhooks.39* **Webhooks** (launched 2026): `POST /v1/webhooks?webhook_id=…` with `subscribed_events: ["batch.succeeded","batch.failed"]`, or per-request `webhookConfig.uris[]` (batch and SDK `GenerateVideosConfig.webhook_config`). Replaces `GET /operations` polling for batch and long-running operations.40* Results retention: Veo files 2 days (→ `files/{id}:download?alt=media`), batch response files 6 weeks, uploaded files 48 h.4142## 4. `generatedFiles`4344`GeneratedFile {name: "generatedFiles/abc-123", state: GENERATING | GENERATED | FAILED, mimeType, error}`; `GET /v1beta/generatedFiles?pageSize&pageToken` → `{generatedFiles[], nextPageToken}`. Live: `200 {}` (empty project). Operation variant `generatedFiles/{id}/operations/{op}` (bogus ids → `400 INVALID_ARGUMENT "Request contains an invalid argument."`).4546## 5. Observed error shapes (2026-09-18)4748| Request | HTTP | `error.status` | `error.message` |49|---|---|---|---|50| `GET /v1beta/models/veo-3.1-lite-generate-preview/operations/bogus-op` | 403 | PERMISSION_DENIED | `You do not have permission to access the Operation with ID bogus-op or it may not exist.` |51| `GET /v1beta/models/veo-3.1-lite-generate-preview/operations` | 200 | — | `{}` |52| `GET /v1beta/generatedFiles/bogus/operations/bogus` | 400 | INVALID_ARGUMENT | `Request contains an invalid argument.` |53| `GET /v1beta/tunedModels/bogus-model/operations/bogus` | 400 | INVALID_ARGUMENT | same |54| `GET /v1beta/batches/bogus-batch` / `batches/123456789` | 400 | INVALID_ARGUMENT | `Could not parse the batch name` |55| `GET /v1beta/batches?pageSize=5` | 200 | — | `{}` |5657Note the asymmetry: an unknown **model operation** is a 403 (existence hidden), an unknown **batch** is a 400 parse error. All error bodies follow `{error: {code, message, status, details?}}`.58