Google Gemini API

Making the first call

You send a model name and your content; you get back a response containing generated text. The text is not at the top level of that response, and knowing where it sits saves an hour on the first day: it comes back inside a candidate, in a content structure with parts, and the SDKs offer a convenience accessor for the common case.

Reach for the accessor for prose, and read the structure when you need anything else, because the same structure carries the reason generation stopped and the safety information below.

Attaching media to a request

Media is part of the same request rather than a separate endpoint, and there are two ways in.

Inline for small files, sent with the request.

Uploaded through the Files API for anything substantial, where you upload once and reference the result. This is the one to reach for in a conversation, because inlining means re-sending the file with every turn and paying for it each time.

Media is billed as tokens and shares the context window with your text. Google Gemini covers the rates, which differ enough between audio and video to change what you send.

Configuring generation

Generation settings live in their own configuration object rather than as top-level parameters: the sampling controls, an output token cap, stop sequences, and response format options when you want structured output.

The sampling names differ from other providers, which is the usual trap when porting code. The ideas are the same, and sampling parameters covers them. Check this provider's names rather than assuming the ones you know.

Set the output cap deliberately. A default left alone is how you get answers that stop mid-sentence.

Safety settings: four categories, five thresholds

This is the part of the API most specific to this provider, and the defaults are not what people assume.

Four adjustable categories: harassment, hate speech, sexually explicit, and dangerous. Alongside them are built-in protections against core harms, such as content endangering child safety, which cannot be modified. Both halves matter: some filtering is yours to configure, and some is not.

Five thresholds, adjustable per request:

The default for current model generations is OFF. The adjustable filters are disabled unless you configure them.

That catches people in both directions. A developer who assumed filtering was on ships without it. A developer who hits a block assumes a strict default when they are seeing the built-in protections instead. Configure the categories you care about rather than inheriting whatever the default is this year, and treat the setting as part of your product policy the way moderation thresholds are.

Reading a blocked response

Blocking is reported in fields, not exceptions, which is the same lesson the finish reason teaches elsewhere.

If the response was blocked, finishReason is SAFETY, and safetyRatings carries the per-category detail.

If the prompt was blocked, nothing was generated at all, and promptFeedback.blockReason says why.

Handle both. Code that reads the text accessor without checking either will either throw on an empty response or silently store an empty string as an answer. Check the finish reason on every response, the way you would for truncation, and branch on it: a safety block is a different product decision from a normal completion, and the user deserves a different message.

Further reading

• Google, Safety settings: the categories, thresholds, defaults, and blocked-response fields.
• Google, Gemini API: the current surface and the Files API.
• Google Gemini: the models, and the token cost of media.