`vertex://`¶

Google Gemini via the public generativelanguage.googleapis.com endpoint, using Gemini's native generateContent shape (NOT OpenAI-compatible). Authentication is by API key passed as a ?key=... query parameter — not a header.

vertex:// and gemini:// are the same component — two registered schemes pointing at the same code in pkg/component/vertex/. Pick whichever name reads better in your route; the behaviour and parameters are identical except that the vertex.* / gemini.* response header namespace tracks the scheme used.

URI shape¶

vertex://chat?model=<id>&apiKey=<key>&temperature=<float>&maxTokens=<int>&baseURL=<url>

Operation defaults to chat if omitted; embeddings is not supported on this scheme.

Parameters¶

Param	Type	Default	Producer/Consumer/Both	Description
`model`	string	`gemini-2.0-flash`	Producer	Gemini model id. Common: `gemini-2.0-flash`, `gemini-2.0-pro`, `gemini-1.5-flash`, `gemini-1.5-pro`. See the Gemini model docs.
`apiKey`	string	(from constructor)	Producer	Google AI Studio API key — passed as `?key=<value>` on the request URL, not as a header.
`baseURL`	string	`https://generativelanguage.googleapis.com/v1beta`	Producer	Override the base. Use the Vertex AI regional endpoint for production.
`temperature`	float	`0.7`	Producer	Sampling temperature; emitted inside `generationConfig`.
`maxTokens`	int	`4096`	Producer	Sent as `generationConfig.maxOutputTokens`.

Producer-only.

Headers¶

Reads:

Header	Effect
`systemPrompt`	The Gemini API has no native system role on this endpoint, so the producer fakes one: prepends a user turn containing the system prompt followed by a `model` turn saying `"Understood."`. This is the same trick the Google SDK uses for older models.

Sets:

Header	Description
`vertex.model`	The model id used.
`vertex.finishReason`	`STOP`, `MAX_TOKENS`, `SAFETY`, `RECITATION`, etc.
`vertex.usage.promptTokens`	From `usageMetadata.promptTokenCount`.
`vertex.usage.completionTokens`	From `usageMetadata.candidatesTokenCount`.
`vertex.usage.totalTokens`	From `usageMetadata.totalTokenCount`.

When the route uses the gemini:// scheme instead, the header prefix becomes gemini.*.

Examples¶

Basic call:

- id: gemini-chat
  from: direct://question
  steps:
    - to: vertex://chat?model=gemini-2.0-flash&apiKey=${GOOGLE_API_KEY}

With a system prompt:

- setHeader:
    name: systemPrompt
    starlang: "%sl 2.0\noutput text/plain\n---\n\"Answer in haiku.\""
- to: vertex://chat?model=gemini-2.0-pro&apiKey=${GOOGLE_API_KEY}

Behavior notes¶

API key in the URL. The key is appended as ?key=<value> to the request URL — make sure logs/traces redact this. The Helix tracing layer scrubs apiKey parameters by default.
Endpoint URL pattern: {baseURL}/models/{model}:generateContent.
System prompts are emulated via a two-turn prefix; if you need true system instructions, use the Vertex AI v1 endpoint with system_instruction (override baseURL).
No embeddings, no streaming, no tool-use on this raw client — use the agent step with a Vertex LLM provider for those.
120s timeout. No retries.

Multimodal input¶

vertex://chat (and gemini://chat) accept images and remote files via Gemini's native inline_data and file_data part types. Use a Gemini vision model (gemini-2.0-flash, gemini-1.5-pro, etc.) — the default gemini-2.0-flash already supports vision.

Body	Headers	What gets sent
`string` or `[]byte` (non-image)	—	Text-only `{parts:[{text:"…"}]}`.
`[]byte` w/ image magic	`HelixLLMSystemPrompt`	`{parts:[{inline_data:{mime_type, data:"<base64>"}}]}` + system-prompt prefix.
Any text body	`HelixLLMImages` = `[]string` of URLs (incl. `gs://` GCS URIs)	`{parts:[{text:"…"}, {file_data:{file_uri:"…"}}]}` — Gemini fetches remote files server-side (supports GCS bucket URIs and public HTTPS).
`*exchange.MultipartContent`	—	Pass-through.

- to: vertex://chat?model=gemini-2.0-flash&apiKey=${env:GOOGLE_API_KEY}
  # body: PDF page rendered to PNG bytes

Source¶

pkg/component/vertex/vertex.go
pkg/component/vertex/vertex_test.go

vertex://¶