Document updated on Sep 17, 2025

Google Gemini integration

The Gemini interface allows KrakenD to use Gemini’s API without writing custom integration code, enabling intelligent automation, content generation, or any LLM-powered use case within your existing API infrastructure.

This component abstracts you from the Gemini API usage allowing the consumer to concentrate on the prompt only, as for each request to an endpoint, KrakenD will create the Gemini request with all the necessary elements in their API, and will return a unified response, so if you use other vendors you have a consitent use of LLM models.

In other words, the user sends the content, like “tell me a joke!”, and then KrakenD builds the API payload necessary to talk to Gemini.

This Gemini interface configures a backend within KrakenD that transparently forwards REST requests to Gemini’s API endpoints. It manages authentication, versioning, and payload formatting using its custom templating system. This way, you can easily call Gemini models without writing custom integration code.

A simple configuration looks like this:

{
  "endpoint": "/gemini",
  "method": "POST",
  "backend": [
    {
      "host": [
        "https://generativelanguage.googleapis.com"
      ],
      "url_pattern": "/v1beta/models/gemini-2.5-flash:generateContent",
      "method": "POST",
      "extra_config": {
        "ai/llm": {
          "gemini": {
            "v1beta": {
              "credentials": "XXX_YYY_ZZZ",
              "debug": true,
              "variables": {
                "candidates": 3
              }
            }
          }
        }
      }
    }
  ]
}

To interact with the LLM, the user can send in the request:

• instructions (optional): If you want to add a system prompt
• contents: The content you want to send to the template

Like this:

$curl -XPOST --json '{"instructions": "Act as a 1000 dollar consultant", "contents": "Tell me a consultant joke"}' http://localhost:8080/gemini

Configuration of Gemini

The configuration of Gemini requires you to add under your backend extra_config the ai/llm namespace with the Gemini vendor.

Customizing the payload sent and received from Gemini

As it happens with all LLM interfaces of KrakenD, you can completely replace the request and the response so you have a custom interaction with the LLM. While the default template should allow you to accomplish any day to day job, you might need to extend it using your own template.

You may override the input and output Go templates by specifying:

• input_template: Path to a custom template controlling how the request data is formatted before sending to Gemini.
• output_template: Path to a custom template to transform and extract the desired pieces from Gemini’s response.

See below how to change this interaction

Default input_template for Gemini v1beta

When you don’t set any input_template, KrakenD will create the JSON payload sent to Gemini using the following template:

{
	"generationConfig": {
		{{ $max_tokens := .variables.max_tokens }}{{ if ge $max_tokens 0 }}"maxOutputTokens": {{ $max_tokens }},{{ end }}
		{{ $temperature := .variables.temperature }}{{ if ge $temperature 0.0 }}"temperature": {{ $temperature }},{{ end }}
		{{ $top_p := .variables.top_p }}{{ if ge $top_p 0.0 }}"topP": {{ $top_p }},{{ end }}
		{{ $top_k := .variables.top_k }}{{ if ge $top_k 0 }}"topK": {{ $top_k }},{{ end }}
		"candidateCount": {{ .variables.candidate_count | toJson }},
		"stopSequences": {{ .variables.stop_sequences | toJson }}
	},
	{{- if hasKey .req_body "instructions" }}
	"system_instruction": {
		"parts": [
			{
				"text": {{ .req_body.instructions | toJson }}
			}
		]
	},
	{{ end }}
	"contents": [
		{
			"parts": [
				{
					"text": {{ .req_body.contents | toJson }}
				}
			]
		}
	]
}

Remember you can access your own variables declared in the configuration using {{ .variables.xxx }}.

Default output_template for Gemini v1

When you don’t declare an output_template, the response from the AI is transformed to have the following format:

{
	"ai_gateway_response":
	[
		{{ if gt (len .resp_body.candidates) 0 }}
		{
			"contents": [
			{{ range $ci, $candidate := .resp_body.candidates }}
				{{ range $index, $part := $candidate.content.parts }}
				{{ if $ci }},{{ end }}
				{{ $part.text | toJson }}
				{{ end }}
			{{ end }}
			]
		}
		{{ end }}
	],
	"usage": "{{ .resp_body.usageMetadata.totalTokenCount }}"
}