docs: clarify Gemini free tier image generation requirements

Author: HavenDV

README.md

@@ -400,6 +400,17 @@ await foreach (var message in session.ReadEventsAsync())
 
 </details>
 
+### Free Tier and Image Generation
+
+Gemini API access is model-specific. A Free Tier key can use many text and multimodal Gemini models, but native image output models are currently different.
+
+- `GenerateImageAsync`, `EditImageAsync`, and `GenerateImageWithReferencesAsync` default to `gemini-2.5-flash-image`.
+- Google's Gemini API pricing page currently lists `gemini-2.5-flash-image` and `imagen-*` models as Paid Tier only.
+- There is no SDK flag that enables free native image generation. To use the image helpers in this SDK, create your API key from a Paid Tier Google AI Studio project with billing enabled.
+- Google AI Studio itself can still be free to use, but using a paid API key for paid features is billed by Google.
+
+For setup details, see the `Free Tier and Image Generation` guide in the docs and Google's official docs for [pricing](https://ai.google.dev/gemini-api/docs/pricing), [billing](https://ai.google.dev/gemini-api/docs/billing), [rate limits](https://ai.google.dev/gemini-api/docs/rate-limits), and [available regions](https://ai.google.dev/gemini-api/docs/available-regions).
+
 <!-- EXAMPLES:START -->
 ### Chat Client Five Random Words Streaming
 ```csharp
@@ -694,6 +705,8 @@ using var client = new GeminiClient(apiKey);
 
 try
 {
+    // This example uses native image output and therefore requires
+    // a Paid Tier Gemini API project and API key.
     // First generate an image to edit
     var original = await client.GenerateImageAsync(
         prompt: "A plain white background",
@@ -866,6 +879,8 @@ using var client = new GeminiClient(apiKey);
 
 try
 {
+    // Native image output models such as gemini-2.5-flash-image currently
+    // require a Paid Tier Gemini API project and API key.
     var result = await client.GenerateImageAsync(
         prompt: "A simple red circle on a white background",
         imageSize: "1K");
@@ -882,6 +897,8 @@ using var client = new GeminiClient(apiKey);
 
 try
 {
+    // Native image output models such as gemini-2.5-flash-image currently
+    // require a Paid Tier Gemini API project and API key.
     var result = await client.GenerateImageAsync(
         prompt: "A landscape with mountains",
         imageSize: "1K",
@@ -899,6 +916,8 @@ using var client = new GeminiClient(apiKey);
 
 try
 {
+    // This example uses native image output and therefore requires
+    // a Paid Tier Gemini API project and API key.
     // First generate a reference image
     var reference = await client.GenerateImageAsync(
         prompt: "A simple red square",
@@ -940,6 +959,8 @@ using var client = new GeminiClient(apiKey);
 
 try
 {
+    // This example first creates a source image, so it also requires
+    // a Paid Tier Gemini API project and API key.
     var image = await client.GenerateImageAsync(
         prompt: "A still landscape with mountains and a lake",
         imageSize: "1K");
@@ -964,6 +985,8 @@ using var client = new GeminiClient(apiKey);
 
 try
 {
+    // This example first creates source images, so it also requires
+    // a Paid Tier Gemini API project and API key.
     var startFrame = await client.GenerateImageAsync(
         prompt: "A red circle on a white background",
         imageSize: "1K");

docs/examples/edit-image-simple-edit.md

@@ -9,6 +9,8 @@ using var client = new GeminiClient(apiKey);
 
 try
 {
+    // This example uses native image output and therefore requires
+    // a Paid Tier Gemini API project and API key.
     // First generate an image to edit
     var original = await client.GenerateImageAsync(
         prompt: "A plain white background",

docs/examples/generate-image-simple-prompt.md

@@ -9,6 +9,8 @@ using var client = new GeminiClient(apiKey);
 
 try
 {
+    // Native image output models such as gemini-2.5-flash-image currently
+    // require a Paid Tier Gemini API project and API key.
     var result = await client.GenerateImageAsync(
         prompt: "A simple red circle on a white background",
         imageSize: "1K");

docs/examples/generate-image-with-aspect-ratio.md

@@ -9,6 +9,8 @@ using var client = new GeminiClient(apiKey);
 
 try
 {
+    // Native image output models such as gemini-2.5-flash-image currently
+    // require a Paid Tier Gemini API project and API key.
     var result = await client.GenerateImageAsync(
         prompt: "A landscape with mountains",
         imageSize: "1K",

docs/examples/generate-image-with-references-single-reference.md

@@ -9,6 +9,8 @@ using var client = new GeminiClient(apiKey);
 
 try
 {
+    // This example uses native image output and therefore requires
+    // a Paid Tier Gemini API project and API key.
     // First generate a reference image
     var reference = await client.GenerateImageAsync(
         prompt: "A simple red square",

docs/examples/generate-video-from-image-simple-animation.md

@@ -9,6 +9,8 @@ using var client = new GeminiClient(apiKey);
 
 try
 {
+    // This example first creates a source image, so it also requires
+    // a Paid Tier Gemini API project and API key.
     var image = await client.GenerateImageAsync(
         prompt: "A still landscape with mountains and a lake",
         imageSize: "1K");

docs/examples/interpolate-frames-two-images.md

@@ -9,6 +9,8 @@ using var client = new GeminiClient(apiKey);
 
 try
 {
+    // This example first creates source images, so it also requires
+    // a Paid Tier Gemini API project and API key.
     var startFrame = await client.GenerateImageAsync(
         prompt: "A red circle on a white background",
         imageSize: "1K");

docs/guides/free-tier-and-image-generation.md

@@ -0,0 +1,63 @@
+# Free Tier and Image Generation
+
+This SDK works with both Free Tier and Paid Tier Gemini API projects, but Google enables features per model, not per SDK method.
+
+## Free Tier vs Paid Tier
+
+- Free Tier is available only for selected Gemini API models and comes with lower quota limits.
+- Paid Tier requires upgrading a Google AI Studio project to billing.
+- Google currently documents Paid Tier setup as linking billing in AI Studio and, for many accounts, adding a minimum prepaid balance.
+
+## Native Image Generation Is Not Currently Free Tier
+
+The image helper methods in this SDK default to native image output models:
+
+- `GenerateImageAsync()`
+- `EditImageAsync()`
+- `GenerateImageWithReferencesAsync()`
+
+By default they use `gemini-2.5-flash-image`.
+
+Google's Gemini API pricing page currently marks these native image generation options as not available on the Free Tier:
+
+- `gemini-2.5-flash-image`
+- `imagen-*` models such as `imagen-4.0-generate-001`
+
+That means there is currently no SDK-side switch that "turns on" free native image generation. If your project stays on the Gemini API Free Tier, these image output helpers should be treated as Paid Tier features.
+
+## What You Need For Image Generation In This SDK
+
+To call `GenerateImageAsync()`, `EditImageAsync()`, or `GenerateImageWithReferencesAsync()` successfully, make sure you have:
+
+1. A Google AI Studio project in a supported region.
+2. Billing enabled for that project.
+3. A valid paid billing state for that project, such as a positive prepaid balance when Google requires prepay for your account.
+4. An API key created from that Paid Tier project.
+5. A model that supports native image output, such as `gemini-2.5-flash-image`.
+
+## Common Confusion
+
+- Google AI Studio usage can be free even though some Gemini API models are Paid Tier only.
+- A Free Tier key can still use multimodal models that accept image input, such as vision-style prompts with `gemini-2.5-flash`.
+- Accepting image input is not the same as returning generated image output.
+
+## Example
+
+```csharp
+using Google.Gemini;
+
+using var client = new GeminiClient(apiKey);
+
+// The API key must come from a Paid Tier AI Studio project for native image output.
+var result = await client.GenerateImageAsync(
+    prompt: "A watercolor fox reading a map",
+    imageSize: "1K");
+```
+
+## Official Google References
+
+- [Gemini API pricing](https://ai.google.dev/gemini-api/docs/pricing)
+- [Gemini API billing](https://ai.google.dev/gemini-api/docs/billing)
+- [Gemini API rate limits](https://ai.google.dev/gemini-api/docs/rate-limits)
+- [Available regions for Google AI Studio and Gemini API](https://ai.google.dev/gemini-api/docs/available-regions)
+- [Gemini image generation docs](https://ai.google.dev/gemini-api/docs/image-generation)

docs/index.md

@@ -400,6 +400,17 @@ await foreach (var message in session.ReadEventsAsync())
 
 </details>
 
+### Free Tier and Image Generation
+
+Gemini API access is model-specific. A Free Tier key can use many text and multimodal Gemini models, but native image output models are currently different.
+
+- `GenerateImageAsync`, `EditImageAsync`, and `GenerateImageWithReferencesAsync` default to `gemini-2.5-flash-image`.
+- Google's Gemini API pricing page currently lists `gemini-2.5-flash-image` and `imagen-*` models as Paid Tier only.
+- There is no SDK flag that enables free native image generation. To use the image helpers in this SDK, create your API key from a Paid Tier Google AI Studio project with billing enabled.
+- Google AI Studio itself can still be free to use, but using a paid API key for paid features is billed by Google.
+
+For setup details, see the `Free Tier and Image Generation` guide in the docs and Google's official docs for [pricing](https://ai.google.dev/gemini-api/docs/pricing), [billing](https://ai.google.dev/gemini-api/docs/billing), [rate limits](https://ai.google.dev/gemini-api/docs/rate-limits), and [available regions](https://ai.google.dev/gemini-api/docs/available-regions).
+
 <!-- EXAMPLES:START -->
 ### Chat Client Five Random Words Streaming
 ```csharp
@@ -694,6 +705,8 @@ using var client = new GeminiClient(apiKey);
 
 try
 {
+    // This example uses native image output and therefore requires
+    // a Paid Tier Gemini API project and API key.
     // First generate an image to edit
     var original = await client.GenerateImageAsync(
         prompt: "A plain white background",
@@ -866,6 +879,8 @@ using var client = new GeminiClient(apiKey);
 
 try
 {
+    // Native image output models such as gemini-2.5-flash-image currently
+    // require a Paid Tier Gemini API project and API key.
     var result = await client.GenerateImageAsync(
         prompt: "A simple red circle on a white background",
         imageSize: "1K");
@@ -882,6 +897,8 @@ using var client = new GeminiClient(apiKey);
 
 try
 {
+    // Native image output models such as gemini-2.5-flash-image currently
+    // require a Paid Tier Gemini API project and API key.
     var result = await client.GenerateImageAsync(
         prompt: "A landscape with mountains",
         imageSize: "1K",
@@ -899,6 +916,8 @@ using var client = new GeminiClient(apiKey);
 
 try
 {
+    // This example uses native image output and therefore requires
+    // a Paid Tier Gemini API project and API key.
     // First generate a reference image
     var reference = await client.GenerateImageAsync(
         prompt: "A simple red square",
@@ -940,6 +959,8 @@ using var client = new GeminiClient(apiKey);
 
 try
 {
+    // This example first creates a source image, so it also requires
+    // a Paid Tier Gemini API project and API key.
     var image = await client.GenerateImageAsync(
         prompt: "A still landscape with mountains and a lake",
         imageSize: "1K");
@@ -964,6 +985,8 @@ using var client = new GeminiClient(apiKey);
 
 try
 {
+    // This example first creates source images, so it also requires
+    // a Paid Tier Gemini API project and API key.
     var startFrame = await client.GenerateImageAsync(
         prompt: "A red circle on a white background",
         imageSize: "1K");

mkdocs.yml

@@ -2,6 +2,7 @@ site_name: Google.Gemini .NET Documentation
 nav:
 - Overview: index.md
 - Guides:
+  - Free Tier and Image Generation: guides/free-tier-and-image-generation.md
   - Live API (Real-time Voice/Video): guides/live-api.md
   - Microsoft.Extensions.AI: guides/meai.md
 # EXAMPLES:START
@@ -113,4 +114,4 @@ markdown_extensions:
       custom_checkbox: true
   - pymdownx.tilde
   - pymdownx.tabbed:
-      alternate_style: true
+      alternate_style: true