Gemini API Dev

Gemini API development

Use this skill when building an ordinary Gemini API application rather than a long-lived Live API session or an agent workflow that specifically belongs on the Interactions API.

Start with current documentation

Treat model IDs, SDK imports, method names, response fields, supported modalities, preview labels, and pricing or quota behavior as version-sensitive. Before writing code, use the Gemini Docs MCP if it is connected. Search the official Gemini documentation for the exact task, model, language, and API surface. If the MCP is unavailable, use the official documentation index at https://ai.google.dev/gemini-api/docs/llms.txt and follow links to the relevant page.

Do not guess from generic OpenAI examples or old google-generativeai snippets. Prefer the current Google GenAI SDK and confirm the installed package version and language-specific import path. Keep the API key on a trusted server or backend; do not put it in browser bundles, mobile binaries, committed files, logs, or client-visible prompts.

Choose the API surface

Make the API choice explicit before implementation.

Do not migrate APIs merely to make an example look newer. Match the API to the product’s latency, state, tool, and deployment requirements.

Implement the smallest correct path

1. Confirm the language, package version, model, API surface, input modalities, output modality, and deployment boundary.
2. Create the SDK client using the current official quickstart for that language. Load credentials from the runtime environment or a secret manager.
3. Make one minimal request and inspect the actual response shape before adding streaming, tools, retries, caching, or orchestration.
4. Add multimodal inputs using the documented content and MIME-type conventions. Do not infer media support from a model name.
5. Add structured output only when the application needs machine-readable data. Define a small schema, validate the result, and handle refusal, truncation, invalid JSON, and safety blocks.
6. Add function calling only with explicit tool schemas, server-side validation, authorization checks, timeouts, idempotency, and a clear loop for returning tool results.
7. Add retries and observability around network errors, rate limits, transient server errors, and model refusals. Do not blindly retry non-idempotent side effects.
8. Write a focused smoke test that proves authentication, one representative request, parsing, and the important failure path.

Function calling guardrails

Treat model-generated function calls as untrusted input. Validate every argument against the server’s schema and business rules. The model must never decide authorization, tenant boundaries, payment amounts, file paths, SQL fragments, or irreversible actions by itself. Keep tool execution in application code, return only the minimum result needed by the model, and request user confirmation for consequential operations.

Keep the tool loop observable. Log a request ID, tool name, validated argument summary, duration, and outcome without logging API keys or sensitive payloads. Add loop limits and duplicate-call protection so a malformed model response cannot create an unbounded execution cycle.

Streaming and multimodal behavior

Use the exact streaming API documented for the selected API surface. Accumulate text deltas in order, handle finalization and errors, and expose cancellation to the user. For audio or video, document the accepted encoding, sample rate, frame cadence, MIME type, size limits, and buffering policy rather than assuming them. Preserve the distinction between model output text, inline data, citations, tool calls, and usage metadata.

Google Cloud deployment context

When the Gemini application runs on Google Cloud, read docs/google-cloud-deployment.md in the repository as a deployment review companion. Separate Gemini API correctness from cloud concerns such as runtime identity, secret storage, networking, observability, quotas, rollout, and recovery. Use the current Google Cloud Well-Architected Framework and service documentation for the target product; do not assume Cloud Run, GKE, BigQuery, Firebase, or a fixed IAM pattern is always the right choice.

Production checklist

Common failure modes

When code fails, classify the failure before changing the API: authentication, unsupported model capability, malformed request, content or safety block, quota/rate limit, transport failure, timeout, response parsing, or tool execution. Search the current error and method names in the Gemini Docs MCP. Do not fix a 404 by inventing a different model name, and do not fix a schema error by removing validation without understanding the response contract.

If an SDK example and runtime behavior disagree, inspect the installed package version, the official API reference, and the changelog or deprecations page. Keep a compatible fallback only when the product genuinely supports multiple API surfaces.

Current documentation

Use these as starting points, not as substitutes for task-time verification:

• Gemini API overview: https://ai.google.dev/gemini-api/docs
• Get started: https://ai.google.dev/gemini-api/docs/get-started
• Models: https://ai.google.dev/gemini-api/docs/models
• Text generation: https://ai.google.dev/gemini-api/docs/text-generation
• Multimodal input: https://ai.google.dev/gemini-api/docs/image-understanding
• Function calling: https://ai.google.dev/gemini-api/docs/function-calling
• Structured output: https://ai.google.dev/gemini-api/docs/structured-output
• Image generation: https://ai.google.dev/gemini-api/docs/image-generation
• Tools: https://ai.google.dev/gemini-api/docs/tools
• Troubleshooting: https://ai.google.dev/gemini-api/docs/troubleshooting
• Deprecations: https://ai.google.dev/gemini-api/docs/deprecations