Gemini generateContent Explained, Step by Step

Quem está na listaEN2026-10-25

Gemini generateContent is a request-response method: you send conversation content and receive generated output. Understanding its native structure makes requests easier to build and responses easier to debug. This walkthrough starts with a text prompt, then adds configuration, conversation history, and production checks. ([ai.google.dev](https://ai.google.dev/gemini-api/docs/generate-content/text-generation))

§ Step 1: Choose the native Gemini route

Vana API supports native Gemini requests under /v1beta. For this walkthrough, use Gemini 3.8 Flash and send an HTTP POST to /v1beta/models/gemini-3.8-flash:generateContent on your Vana API host. The model identifier belongs in the path, while the prompt belongs in the JSON body. Authenticate with your Vana API key in the x-goog-api-key header and set Content-Type: application/json. ([vanaapi.com](https://vanaapi.com/plug-in?locale=en))

Create a Vana API account to obtain a key and try the walkthrough. Keep that key in a server-side environment variable rather than browser code or a public repository. ([vanaapi.com](https://vanaapi.com/))

§ Step 2: Build the smallest useful request

The native request uses contents, not an OpenAI-style messages array. Each conversation turn contains parts, which hold its content. Start with one user turn and one text part: ([ai.google.dev](https://ai.google.dev/gemini-api/docs/generate-content/text-generation))

 1  {"contents":[{"role":"user","parts":[{"text":"Explain an HTTP timeout in two sentences for a junior developer."}]}]}

Use this deliberately narrow prompt for your first test. It gives you a simple acceptance check: the answer should explain the concept, match the audience, and stay within two sentences. Leave optional features out until this basic request works.

§ Step 3: Add instructions and output limits

Use the top-level systemInstruction field for reusable guidance, such as explaining technical concepts in plain English. Put generation settings inside generationConfig, including maxOutputTokens when you need an output budget. These fields sit alongside contents rather than inside the user's text part. ([ai.google.dev](https://ai.google.dev/api/generate-content))

Change one setting at a time and compare the result. Avoid copying configuration from another model without checking support. Thinking can increase latency and token consumption, so a short visible answer does not necessarily mean a small total token budget. ([ai.google.dev](https://ai.google.dev/gemini-api/docs/troubleshooting))

§ Step 4: Read the response defensively

Generated output appears in candidates. For the selected candidate, inspect content.parts and collect the text parts intended for display. Do not assume every response contains candidates or that every part contains text. Check promptFeedback when candidates are missing, and inspect finishReason before treating the answer as complete. ([ai.google.dev](https://ai.google.dev/api/generate-content?authuser=01&hl=en&utm_source=openai))

STOP: generation reached a normal stopping point.
MAX_TOKENS: generation reached its token limit; the answer may be incomplete.
Safety-related reasons: inspect the returned feedback instead of reporting an unexplained empty answer.

Keep these outcomes separate in your application logs and user interface. A successful HTTP response alone is not a sufficient completion check. ([ai.google.dev](https://ai.google.dev/api/generate-content))

§ Step 5: Continue with conversation history

For a follow-up such as “Now give a practical example,” send the relevant earlier turns again inside contents. Preserve the original user turn, append the returned model content with role model, then append the new user turn. A standalone generateContent request does not supply earlier conversation history automatically. ([ai.google.dev](https://ai.google.dev/api/generate-content))

Keep only history relevant to the task, and avoid silently rewriting model turns while debugging. First establish a reliable conversation flow; optimize context management afterward.

§ Step 6: Add streaming when needed

Once ordinary requests work, use :streamGenerateContent?alt=sse on the same model path for streaming. Process the incoming events incrementally rather than waiting for one complete JSON response. Streaming changes how you receive output, not the basic contents-and-parts request structure. ([vanaapi.com](https://vanaapi.com/plug-in?locale=en))

§ Step 7: Check failures and usage

For transient failures such as rate limits or temporary unavailability, use bounded exponential backoff with jitter. Fix invalid requests and authentication problems rather than retrying them unchanged. Record status codes, completion reasons, and available usage metadata without logging credentials. ([ai.google.dev](https://ai.google.dev/gemini-api/docs/troubleshooting))

Vana API bills requests on the tokens they use, and an HTTP 402 indicates an exhausted balance. Start with one working prompt, verify its response handling, and only then add more configuration or traffic. ([vanaapi.com](https://vanaapi.com/plug-in?locale=en))