Google Gemini Interactions API Request Workflow

Prepare the request boundary

Set GEMINI_API_KEY in the process environment or an approved secret manager, PROJECT42_GEMINI_MODEL to a reviewed model ID, and PROJECT42_GEMINI_API_VERSION to v1 or v1beta. Prefer v1 for generally available behavior and select v1beta only when a reviewed feature requires it. Never print, commit, or send the key as model input.

Choose state behavior deliberately. Interactions are stored by default for server-managed continuation; use store: false and preserve the required history when your retention policy calls for stateless operation. Define the purpose, permitted input, timeout, retention, expected response, and validation rule before calling.

Send a minimal interaction

This dependency-free Node.js example uses environment-only credentials and permits only the documented v1 and v1beta API versions. Replace the bracketed input at runtime with approved, non-secret content.

const apiKey = process.env.GEMINI_API_KEY;
const model = process.env.PROJECT42_GEMINI_MODEL;
const apiVersion = process.env.PROJECT42_GEMINI_API_VERSION ?? "v1";
if (!apiKey || !model) throw new Error("Missing GEMINI_API_KEY or PROJECT42_GEMINI_MODEL");
if (!new Set(["v1", "v1beta"]).has(apiVersion)) throw new Error("Unsupported Gemini API version");

const response = await fetch(`https://generativelanguage.googleapis.com/${apiVersion}/interactions`, {
  method: "POST",
  headers: { "content-type": "application/json", "x-goog-api-key": apiKey },
  body: JSON.stringify({ model, input: "[INPUT_TEXT]", store: false }),
  signal: AbortSignal.timeout(30_000),
});
const body = await response.json();
if (!response.ok) throw new Error(`Gemini request failed (${response.status}, ${body.error?.status ?? "unknown"})`);
const text = body.steps
  ?.flatMap((step) => step.type === "model_output" ? step.content ?? [] : [])
  .find((part) => part.type === "text")?.text;
if (body.status !== "completed" || typeof text !== "string") throw new Error("Unexpected interaction shape");
console.log({ interactionId: body.id, usage: body.usage, text });

Expected evidence and verification

Expected evidence is an HTTP success with an interaction ID, completed status, typed steps, a text model_output block, and usage. Verify status, step and content types, retained-state policy, length, citations when required, and application rules before displaying or storing output. Record the interaction ID, API version, model, latency, usage, and redacted result—not the key or sensitive input.

Correct authentication, permission, version, and invalid-request failures instead of retrying unchanged. Retry only classified transient 408, 429, and 5xx failures with bounded exponential backoff and jitter. This read-only example has no external side effect, so rollback means discarding the unaccepted interaction and restoring the last verified application state. Reconcile and compensate before retrying any downstream mutation.