Gemini generateContent: A Developer Walkthrough

A useful first integration should prove more than whether a model answers a prompt. It should establish a request contract, preserve conversation state, and distinguish a completed answer from a blocked or interrupted response. Follow this numbered walkthrough to build that foundation with Gemini’s native generateContent API.

1. Separate the protocol from the provider

Google’s native REST method uses POST /v1beta/models/{model}:generateContent. Its request body centers on contents and parts, rather than an OpenAI-style messages array. Treat the native format as a distinct adapter in your application, not a different model name passed into an unchanged request. ([ai.google.dev](https://ai.google.dev/api/generate-content?utm_source=openai))

CodeRelay Hub provides pay-as-you-go access to multiple model families through one endpoint. Keep that routing choice separate from protocol support: before sending native Gemini payloads through a gateway, confirm its documented route, authentication requirements, and supported fields. OpenAI SDK compatibility alone is not evidence of native generateContent compatibility.

2. Start with one explicit request

Choose a model such as Gemini 2.5 Flash only where your provider currently exposes it, and use the provider’s exact model identifier. For the request body, begin with {"contents":[{"role":"user","parts":[{"text":"Explain exponential backoff in three sentences."}]}]}. This isolates basic generation before you introduce tools, attachments, or conversation history. The contents array carries the conversation; each entry contains parts. ([ai.google.dev](https://ai.google.dev/api/generate-content?utm_source=openai))

Keep credentials in server-side configuration. In your adapter, make the base address, authentication mechanism, and model identifier explicit settings rather than scattering them across application code.

3. Separate instructions from generation controls

Use systemInstruction for standing guidance, such as answering concisely or treating supplied documents as untrusted input. Use generationConfig for supported generation parameters, including maxOutputTokens. These are separate request fields; do not bury operational settings inside the user’s prompt. Check parameter support for your selected model and API version. ([docs.cloud.google.com](https://docs.cloud.google.com/gemini-enterprise-agent-platform/reference/models/inference?utm_source=openai))

For an initial test, change one setting at a time. Save a small fixture containing the input, expected response characteristics, and configuration so later changes have a repeatable baseline.

4. Parse the response defensively

Read candidates and inspect the selected candidate’s content.parts instead of assuming a single text field. Check finishReason and promptFeedback before treating missing text as an empty answer. The response also exposes usageMetadata for token accounting. ([ai.google.dev](https://ai.google.dev/api/generate-content?utm_source=openai))

Give your application separate outcomes for usable text, a tool request, blocked content, and an unexpected response. Test each outcome with recorded fixtures. This keeps transport success from becoming an accidental guarantee that the user received a complete answer.

5. Preserve complete conversation turns

For subsequent requests, send the relevant conversation history and append the new user turn. Preserve the returned model content rather than rebuilding history from displayed text alone. Gemini can attach thoughtSignature values to response parts; when present, return them unchanged in subsequent history. Official SDKs handle signatures when full response objects are retained. ([ai.google.dev](https://ai.google.dev/api/generate-content?utm_source=openai))

Store display text separately from protocol state. Your interface may show a simplified answer, while your adapter retains the complete content needed for the next request.

6. Add streaming and tools deliberately

For streamed generation, use streamGenerateContent with alt=sse. Its response is a stream of GenerateContentResponse objects. ([ai.google.dev](https://ai.google.dev/api/generate-content?utm_source=openai))

Do not discard parts merely because their text is empty: streamed responses can carry thought signatures in those parts. Read the stream through completion. ([ai.google.dev](https://ai.google.dev/gemini-api/docs/generate-content/thought-signatures?utm_source=openai))

Before enabling tool execution, add argument validation, authorization checks, and duplicate-execution protection. Keep model output outside the trust boundary of any operation that changes external systems.

7. Validate structured output

For extraction tasks, use supported structured-output configuration instead of relying only on a request to return JSON. Gemini supports a subset of JSON Schema, and application-side validation remains necessary. A structurally valid object can still contain values your business logic must reject. ([ai.google.dev](https://ai.google.dev/gemini-api/docs/generate-content/structured-output?hl=en&utm_source=openai))

8. Bound retries before deployment

Apply exponential backoff with jitter and a retry limit to transient failures. Diagnose authentication and malformed-request errors instead of repeatedly resending them. Inspect rate-limit errors carefully, since a quota problem may require intervention rather than another immediate attempt. ([ai.google.dev](https://ai.google.dev/gemini-api/docs/troubleshooting?utm_source=openai))

Open a free CodeRelay Hub workspace to start building.