Gemini API guide: Interactions and GenerateContent

Separate Google's recommendation from gateway compatibility

Google made Interactions API generally available in June 2026 and recommends it for all new projects. The original generateContent remains supported but is now Legacy. Endpoint support on this site still depends on gateway implementation; Google's publication of /v1beta/interactions does not make it callable here. The current published Gemini-native compatibility path is definitively GenerateContent.

Call GenerateContent through this site

This site recommends Authorization: Bearer; for Gemini-native client compatibility, /v1beta/models/... routes also accept the site key in x-goog-api-key. The model identifier is part of the URL and must come from the model marketplace. contents[].parts can combine text and supported multimodal input; do not send content types that the official model page does not list.

Copycurl "$BASE_URL/v1beta/models/MODEL_NAME:generateContent" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"contents":[{"role":"user","parts":[{"text":"Reply only: connected"}]}]}'

Direct Google Interactions shape

Direct Google calls use x-goog-api-key. Interactions posts to /v1beta/interactions with model and input in JSON. Its response contains id, status, usage, and typed steps[]. SDK output_text is convenient for simple final text, but clients must traverse steps by type when reasoning, tools, images, or audio are interleaved.

Multi-turn calls can use previous_interaction_id, but tools, system instructions, and generation configuration are not inherited and must be sent again. store=false supports stateless handling but cannot be combined with continuation from stored interactions.

The response and stream parsers are different

GenerateContent returns candidates, finishReason, promptFeedback, and safety information. Interactions streams typed events such as interaction.created, step.start/delta/stop, and interaction.completed. Function calls are typed steps in the new protocol rather than a function-response part. Errors can occur after HTTP 200, so tolerate unknown events and wait for an explicit completion event.

Errors and retry

Check authentication on 401, permission on 403, model or resource on 404, and rate or quota on 429. Read the error status and message before handling any 5xx: overload or a transient service fault can merit bounded backoff, but an oversized GenerateContent input or context can also surface as 500 or 504 and must be shortened instead of retried. Parameter, safety, and quota problems likewise need a request or account change. Preserve request IDs, error codes, status, and the final step; see API troubleshooting.

Migration boundaries to verify

Interactions does not yet cover every GenerateContent feature, including selected video metadata, Batch, explicit caching, and custom safety settings. Before migration, verify the model, /v1 or /v1beta version, files, tools, structured output, storage policy, and data controls, with separate contract tests for both formats. Do not change only the URL.