The Gemini API answers a single prompt, but production use needs a retry when it returns a 503, a fallback across model versions when the outage is sticky, and one place to see what ran. Kestra wraps every ChatCompletion, StructuredOutputCompletion, and MultimodalCompletion call in that missing layer, using a direct API key rather than a GCP project, then chains the result into whatever runs next.
The plugin-gemini package calls Google's models directly with an API key: ChatCompletion, TextCompletion, MultimodalCompletion, StructuredOutputCompletion, and Veo video generation. None of that ships with a scheduler, a retry policy, or a queue. Kestra adds the trigger that starts the call, the retry and fallback chain that survives a provider outage, the concurrency cap that protects your quota, and one audit trail across the Gemini call and whatever it feeds next: a Slack alert, a BigQuery table, or a Git-versioned prompt. Teams standardized on Vertex AI for GCP-native model serving reach for this plugin instead when a flow just needs a Gemini API key and nothing else from Google Cloud.
Gemini answers a prompt with a single API key. Kestra decides what triggers the call, shapes the answer into typed JSON, reads images alongside text, fans out a queue at controlled throughput, and retries and falls back across model versions, all in one audit trail.
io.kestra.plugin.gemini.StructuredOutputCompletion forces the response into application/json shaped by a jsonResponseSchema you define, so a downstream If or database write gets typed fields instead of a string you regex out of a paragraph. Token counts are emitted as metrics on every call, and the same schema keeps every run's output shape identical.
plugin-gemini authenticates with a single apiKey secret against the public Gemini API: no service account, project ID, or IAM role to provision. Teams standardized on GCP IAM for model serving should look at Vertex AI instead; this plugin is for the API-key path most Gemini flows start on and many never leave.
A retry policy absorbs a transient 503 in a second; a chain of ChatCompletion tasks gated by runIf falls back to an older model version when the newest preview model stays down. A flow-level concurrency block caps simultaneous calls so a traffic spike never exceeds your own Gemini quota.
io.kestra.plugin.gemini.MultimodalCompletion sends mixed text and image parts, including file URIs pulled from Kestra storage, in one request and returns text plus any generated images, saved back to storage as URIs. No separate OCR or vision service to wire in.
Wrap StructuredOutputCompletion or TextCompletion in a ForEach with concurrencyLimit set, and a queue of hundreds of items to classify becomes a bounded, resumable batch instead of an unthrottled loop that trips your rate limit halfway through.
io.kestra.plugin.gemini.VideoGeneration creates a 1 to 60 second video with Google's Veo 3 model through the same API key. Pair it with a Pause task before anything publishes externally: unlike a routine classification call, a generated video going out under the brand is one of the few Gemini outputs teams genuinely want a person to look at first.
Patterns AI and platform teams run in production today. Each one shows the flow end to end, with the real plugin classes in play.
StructuredOutputCompletion answers in application/json shaped by a schema you define, so a boolean or numeric field drives an If branch directly. No regex against a paragraph, no brittle matching on the model's phrasing, just a notification and a calendar write when the JSON says to act.
The schema guarantees the same fields every time, so If never parses free text for an answer.
Actions fire only when the JSON verdict says so, not on every scheduled run regardless of outcome.
A disabled Schedule trigger runs the check every morning, no person involved.
Published as the ai-check-weather-gemini blueprint in the Kestra catalog.
MultimodalCompletion reads an uploaded image alongside a text prompt in one call. A second StructuredOutputCompletion pass reshapes that free-text read into a fixed JSON schema, so a folder of receipts, screenshots, or product photos becomes typed records a database can ingest directly.
One multimodal call reads the image directly; no dedicated vision or OCR pipeline to stand up.
One call reads the image, a second reshapes the answer, so each prompt stays simple and easy to debug.
A storage trigger polls the inbox, so nobody has to manually upload files to a processing tool.
Published as the gemini-multimodal-receipt-extraction blueprint in the Kestra catalog.
A retry absorbs a one-off 503. When the outage is sticky, a chain of ChatCompletion tasks gated by runIf falls back to an older stable model, and a flow-level concurrency queue keeps a traffic burst from exhausting the quota. Slack fires only when a fallback actually runs.
A one-second retry absorbs transient noise before the fallback chain ever fires.
A flow-level queue keeps a traffic spike from exceeding your own Gemini rate limit.
Slack fires only when a fallback model actually ran, not on every retry attempt.
Published as the gemini-model-fallback-resilience blueprint in the Kestra catalog.
A cheap classifier tags every prompt as coding, reasoning, search, or general, then a Switch sends it to the right provider: Gemini for reasoning, Claude for code, Perplexity for anything needing live web context. Stop paying frontier prices for simple questions and stop sending hard problems to a model not built for them.
A cheap classifier gates expensive models, so frontier pricing only applies where it earns its keep.
Swapping or adding a provider is a new Switch case, not a rewrite of the calling code.
Every classification decision and every provider's response is visible in one execution.
Published as the ai-model-router blueprint in the Kestra catalog.
ForEach with a concurrencyLimit wraps a StructuredOutputCompletion call, so hundreds of pending reviews get classified for toxicity and spam five at a time instead of all at once. Each verdict writes back to the source system immediately, so a failed run resumes without re-classifying what already succeeded.
A concurrency cap keeps throughput predictable no matter how large the queue grows.
Every review gets an approve, flag, or reject verdict plus a reason, not free text to parse.
A single notification per batch replaces one message per review.
Published as the gemini-batch-review-moderation blueprint in the Kestra catalog.
When Gemini 3.1 Pro returned a 503 'model is currently experiencing high demand' response in the middle of our issue triage, the flow didn't stop. It tried Gemini 3.0, then Gemini 2.5, set the fields the rest of the flow needed, and logged a single Slack message so we'd know it happened. The model provider had a bad minute. The workflow didn't.
| Capability | Python scripts + LangChain | |||
|---|---|---|---|---|
| Retry and fallback across model versions | Native retry policy plus a runIf-gated fallback chain | Hand-rolled try/except per call | No native model fallback, a custom Function node required | Durable execution retries the activity automatically |
| Structured JSON output enforcement | Native StructuredOutputCompletion with a jsonResponseSchema | Pydantic or JSON-mode parsing glued on top of the SDK | Manual JSON parsing inside a Function node | Application code owns schema validation |
| Batch fan-out with concurrency control | ForEach with a concurrencyLimit | asyncio.Semaphore or a queue library | Split In Batches node, no native rate limiting | Child workflows per item, more setup |
| Multimodal input (image plus text) | Native MultimodalCompletion | google-genai SDK called directly | HTTP Request node to the Gemini API | An activity wraps the same SDK call |
| Execution history and lineage | Full UI history per task, per attempt | Custom logging, no built-in UI | Execution log per node run | Built-in workflow history, code-first |
| Team already comfortable with | Declarative YAML, versioned in Git | Python and prompt engineering | Low-code, drag-and-drop | Go, Java, or Python SDK and durable-execution concepts |
Find answers to your questions right here, and don't hesitate to Contact Us if you couldn't find what you're looking for.
Running AI Workflows in Production: What We Learned When Gemini Went Down
A real Kestra flow that classifies GitHub issues with Gemini, and the retry, fallback, concurrency, and alerting patterns that kept it running through a provider outage.
The Kestra Plugin Ecosystem for AI: From LLM Providers to Vector Databases
Where plugin-gemini fits among Kestra's other LLM provider plugins, vector databases, and document ingestion tools.
What is an AI agent?
The building blocks of agentic systems, and where an orchestrator fits around a model call.
Gemini plugin reference
Every Gemini task, property, and parameter, with copy-ready YAML examples.
Add retries, model-version fallback, concurrency limits, and full execution history around every Gemini call, from a direct API key to whatever runs next.
