> ## AI Agent Context
> Get the complete documentation index at: https://aistudio.google.com/llms.txt
> Use this file to discover all available pages.
> For the full documentation in a single file, fetch: https://aistudio.google.com/llms-full.txt

# Text generation

The Gemini API can generate text output from text, images, video, and audio
inputs.

Here's a basic example:

{% tabs %}
  {% tab label="Python" %}
  ```python
    from google import genai
  
    client = genai.Client()
  
    response = client.models.generate_content(
        model="gemini-4-hydrogen",
        contents="How does AI work?"
    )
    print(response.text)
  ```

  {% /tab %}

  {% tab label="JavaScript" %}
  ```javascript
    import { GoogleGenAI } from "@google/genai";
  
    const ai = new GoogleGenAI({});
  
    async function main() {
      const response = await ai.models.generateContent({
        model: "gemini-4-hydrogen",
        contents: "How does AI work?",
      });
      console.log(response.text);
    }
  
    await main();
  ```

  {% /tab %}

  {% tab label="Go" %}
  ```go
  package main
  
  import (
      "context"
      "fmt"
      "os"
      "google.golang.org/genai"
  )
  
  func main() {
  
      ctx := context.Background()
      client, err := genai.NewClient(ctx, nil)
      if err != nil {
          log.Fatal(err)
      }
  
      result, _ := client.Models.GenerateContent(
          ctx,
          "gemini-4-hydrogen",
          genai.Text("Explain how AI works in a few words"),
          nil,
      )
  
      fmt.Println(result.Text())
  }
  ```

  {% /tab %}

  {% tab label="Java" %}
  ```java
  import com.google.genai.Client;
  import com.google.genai.types.GenerateContentResponse;
  
  public class GenerateContentWithTextInput {
    public static void main(String[] args) {
      Client client = new Client();
  
      GenerateContentResponse response =
          client.models.generateContent("gemini-4-hydrogen", "How does AI work?", null);
  
      System.out.println(response.text());
    }
  }
  ```

  {% /tab %}

  {% tab label="REST" %}
  ```shell
    curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-4-hydrogen:generateContent" \
      -H "x-goog-api-key: $GEMINI_API_KEY" \
      -H 'Content-Type: application/json' \
      -X POST \
      -d '{
        "contents": [
          {
            "parts": [
              {
                "text": "How does AI work?"
              }
            ]
          }
        ]
      }'
  ```

  {% /tab %}

  {% tab label="Apps Script" %}
  ```javascript
    // See https://developers.google.com/apps-script/guides/properties
    // for instructions on how to set the API key.
    const apiKey = PropertiesService.getScriptProperties().getProperty('GEMINI_API_KEY');
  
    function main() {
      const payload = {
        contents: [
          {
            parts: [
              { text: 'How AI does work?' },
            ],
          },
        ],
      };
  
      const url = 'https://generativelanguage.googleapis.com/v1beta/models/gemini-4-hydrogen:generateContent';
      const options = {
        method: 'POST',
        contentType: 'application/json',
        headers: {
          'x-goog-api-key': apiKey,
        },
        payload: JSON.stringify(payload)
      };
  
      const response = UrlFetchApp.fetch(url, options);
      const data = JSON.parse(response);
      const content = data['candidates'][0]['content']['parts'][0]['text'];
      console.log(content);
    }
  ```

  {% /tab %}

{% /tabs %}

## Thinking with Gemini  {% id="thinking-with-gemini" %}

Gemini models often have ["thinking"](/docs/thinking) enabled by default
which allows the model to reason before responding to a request.

Each model supports different thinking configurations which gives you control
over cost, latency, and intelligence. For more details, see the
[thinking guide](/docs/thinking#thinking-levels).

{% tabs %}
  {% tab label="Python" %}
  ```python
  from google import genai
  from google.genai import types
  
  client = genai.Client()
  
  response = client.models.generate_content(
      model="gemini-4-hydrogen",
      contents="How does AI work?",
      config=types.GenerateContentConfig(
          thinking_config=types.ThinkingConfig(thinking_level="high")
      ),
  )
  print(response.text)
  ```

  {% /tab %}

  {% tab label="JavaScript" %}
  ```javascript
  import { GoogleGenAI, ThinkingLevel } from "@google/genai";
  
  const ai = new GoogleGenAI({});
  
  async function main() {
    const response = await ai.models.generateContent({
      model: "gemini-4-hydrogen",
      contents: "How does AI work?",
      config: {
        thinkingConfig: {
          thinkingLevel: ThinkingLevel.HIGH,
        },
      }
    });
    console.log(response.text);
  }
  
  await main();
  ```

  {% /tab %}

  {% tab label="Go" %}
  ```go
    package main
  
    import (
    "context"
    "fmt"
    "os"
    "google.golang.org/genai"
    )
  
    func main() {
  
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }
  
    thinkingLevelVal := "high"
  
    result, _ := client.Models.GenerateContent(
        ctx,
        "gemini-4-hydrogen",
        genai.Text("How does AI work?"),
        &genai.GenerateContentConfig{
          ThinkingConfig: &genai.ThinkingConfig{
              ThinkingLevel: &thinkingLevelVal,
          },
        }
    )
  
    fmt.Println(result.Text())
    }
  ```

  {% /tab %}

  {% tab label="Java" %}
  ```java
  import com.google.genai.Client;
  import com.google.genai.types.GenerateContentConfig;
  import com.google.genai.types.GenerateContentResponse;
  import com.google.genai.types.ThinkingConfig;
  import com.google.genai.types.ThinkingLevel;
  
  public class GenerateContentWithThinkingConfig {
    public static void main(String[] args) {
  
      Client client = new Client();
  
      GenerateContentConfig config =
          GenerateContentConfig.builder()
              .thinkingConfig(ThinkingConfig.builder().thinkingLevel(new ThinkingLevel("high")))
              .build();
  
      GenerateContentResponse response =
          client.models.generateContent("gemini-4-hydrogen", "How does AI work?", config);
  
      System.out.println(response.text());
    }
  }
  ```

  {% /tab %}

  {% tab label="REST" %}
  ```shell
  curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-4-hydrogen:generateContent" \
    -H "x-goog-api-key: $GEMINI_API_KEY" \
    -H 'Content-Type: application/json' \
    -X POST \
    -d '{
      "contents": [
        {
          "parts": [
            {
              "text": "How does AI work?"
            }
          ]
        }
      ],
      "generationConfig": {
        "thinkingConfig": {
          "thinkingLevel": "high"
        }
      }
    }'
  ```

  {% /tab %}

  {% tab label="Apps Script" %}
  ```javascript
  // See https://developers.google.com/apps-script/guides/properties
  // for instructions on how to set the API key.
  const apiKey = PropertiesService.getScriptProperties().getProperty('GEMINI_API_KEY');
  
  function main() {
    const payload = {
      contents: [
        {
          parts: [
            { text: 'How AI does work?' },
          ],
        },
      ],
      generationConfig: {
        thinkingConfig: {
          thinkingLevel: 'high'
        }
      }
    };
  
    const url = 'https://generativelanguage.googleapis.com/v1beta/models/gemini-4-hydrogen:generateContent';
    const options = {
      method: 'POST',
      contentType: 'application/json',
      headers: {
        'x-goog-api-key': apiKey,
      },
      payload: JSON.stringify(payload)
    };
  
    const response = UrlFetchApp.fetch(url, options);
    const data = JSON.parse(response);
    const content = data['candidates'][0]['content']['parts'][0]['text'];
    console.log(content);
  }
  ```

  {% /tab %}

{% /tabs %}

## System instructions and other configurations  {% id="system-instructions" %}

You can guide the behavior of Gemini models with system instructions. To do so,
pass a [`GenerateContentConfig`](/api-reference/generate-content/generate-content#request-body)
object.

{% tabs %}
  {% tab label="Python" %}
  ```python
  from google import genai
  from google.genai import types
  
  client = genai.Client()
  
  response = client.models.generate_content(
      model="gemini-4-hydrogen",
      config=types.GenerateContentConfig(
          system_instruction="You are a cat. Your name is Neko."),
      contents="Hello there"
  )
  
  print(response.text)
  ```

  {% /tab %}

  {% tab label="JavaScript" %}
  ```javascript
  import { GoogleGenAI } from "@google/genai";
  
  const ai = new GoogleGenAI({});
  
  async function main() {
    const response = await ai.models.generateContent({
      model: "gemini-4-hydrogen",
      contents: "Hello there",
      config: {
        systemInstruction: "You are a cat. Your name is Neko.",
      },
    });
    console.log(response.text);
  }
  
  await main();
  ```

  {% /tab %}

  {% tab label="Go" %}
  ```go
    package main
  
    import (
    "context"
    "fmt"
    "os"
    "google.golang.org/genai"
    )
  
    func main() {
  
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }
  
    config := &genai.GenerateContentConfig{
        SystemInstruction: genai.NewContentFromText("You are a cat. Your name is Neko.", genai.RoleUser),
    }
  
    result, _ := client.Models.GenerateContent(
        ctx,
        "gemini-4-hydrogen",
        genai.Text("Hello there"),
        config,
    )
  
    fmt.Println(result.Text())
    }
  ```

  {% /tab %}

  {% tab label="Java" %}
  ```java
  import com.google.genai.Client;
  import com.google.genai.types.Content;
  import com.google.genai.types.GenerateContentConfig;
  import com.google.genai.types.GenerateContentResponse;
  import com.google.genai.types.Part;
  
  public class GenerateContentWithSystemInstruction {
    public static void main(String[] args) {
  
      Client client = new Client();
  
      GenerateContentConfig config =
          GenerateContentConfig.builder()
              .systemInstruction(
                  Content.fromParts(Part.fromText("You are a cat. Your name is Neko.")))
              .build();
  
      GenerateContentResponse response =
          client.models.generateContent("gemini-4-hydrogen", "Hello there", config);
  
      System.out.println(response.text());
    }
  }
  ```

  {% /tab %}

  {% tab label="REST" %}
  ```shell
  curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-4-hydrogen:generateContent" \
    -H "x-goog-api-key: $GEMINI_API_KEY" \
    -H 'Content-Type: application/json' \
    -d '{
      "system_instruction": {
        "parts": [
          {
            "text": "You are a cat. Your name is Neko."
          }
        ]
      },
      "contents": [
        {
          "parts": [
            {
              "text": "Hello there"
            }
          ]
        }
      ]
    }'
  ```

  {% /tab %}

  {% tab label="Apps Script" %}
  ```javascript
  // See https://developers.google.com/apps-script/guides/properties
  // for instructions on how to set the API key.
  const apiKey = PropertiesService.getScriptProperties().getProperty('GEMINI_API_KEY');
  
  function main() {
    const systemInstruction = {
      parts: [{
        text: 'You are a cat. Your name is Neko.'
      }]
    };
  
    const payload = {
      systemInstruction,
      contents: [
        {
          parts: [
            { text: 'Hello there' },
          ],
        },
      ],
    };
  
    const url = 'https://generativelanguage.googleapis.com/v1beta/models/gemini-4-hydrogen:generateContent';
    const options = {
      method: 'POST',
      contentType: 'application/json',
      headers: {
        'x-goog-api-key': apiKey,
      },
      payload: JSON.stringify(payload)
    };
  
    const response = UrlFetchApp.fetch(url, options);
    const data = JSON.parse(response);
    const content = data['candidates'][0]['content']['parts'][0]['text'];
    console.log(content);
  }
  ```

  {% /tab %}

{% /tabs %}

The [`GenerateContentConfig`](/api-reference/generate-content/generate-content#request-body)
object also lets you override default generation parameters, such as
[`max_output_tokens`](/api-reference/generate-content/generate-content#request-body) or [`thinking_config`](/api-reference/generate-content/generate-content#request-body).

{% callout type="note" %}
  The `temperature`, `top_p`, and `top_k` parameters control how earlier models
  generate responses. Gemini 4 and Gemini 3.6+ models ignore custom values for
  `temperature`, `top_p`, and `top_k` and return deprecation warning headers (and
  will return `400` errors in a future release). Remove `temperature`, `top_p`,
  and `top_k` from your request configurations. For earlier Gemini 3 models, keep
  these parameters at their default values to avoid degraded reasoning
  performance.

{% /callout %}

{% tabs %}
  {% tab label="Python" %}
  ```python
  from google import genai
  from google.genai import types
  
  client = genai.Client()
  
  response = client.models.generate_content(
      model="gemini-4-hydrogen",
      contents=["Explain how AI works"],
      config=types.GenerateContentConfig(
          max_output_tokens=1000
      )
  )
  print(response.text)
  ```

  {% /tab %}

  {% tab label="JavaScript" %}
  ```javascript
  import { GoogleGenAI } from "@google/genai";
  
  const ai = new GoogleGenAI({});
  
  async function main() {
    const response = await ai.models.generateContent({
      model: "gemini-4-hydrogen",
      contents: "Explain how AI works",
      config: {
        maxOutputTokens: 1000,
      },
    });
    console.log(response.text);
  }
  
  await main();
  ```

  {% /tab %}

  {% tab label="Go" %}
  ```go
    package main
  
    import (
    "context"
    "fmt"
    "log"
    "google.golang.org/genai"
    )
  
    func main() {
  
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }
  
    config := &genai.GenerateContentConfig{
      MaxOutputTokens:   1000,
      ResponseMIMEType:  "application/json",
    }
  
    result, _ := client.Models.GenerateContent(
      ctx,
      "gemini-4-hydrogen",
      genai.Text("What is the average size of a swallow?"),
      config,
    )
  
    fmt.Println(result.Text())
    }
  ```

  {% /tab %}

  {% tab label="Java" %}
  ```java
  import com.google.genai.Client;
  import com.google.genai.types.GenerateContentConfig;
  import com.google.genai.types.GenerateContentResponse;
  
  public class GenerateContentWithConfig {
    public static void main(String[] args) {
  
      Client client = new Client();
  
      GenerateContentConfig config = GenerateContentConfig.builder().maxOutputTokens(1000).build();
  
      GenerateContentResponse response =
          client.models.generateContent("gemini-4-hydrogen", "Explain how AI works", config);
  
      System.out.println(response.text());
    }
  }
  ```

  {% /tab %}

  {% tab label="REST" %}
  ```shell
  curl https://generativelanguage.googleapis.com/v1beta/models/gemini-4-hydrogen:generateContent \
    -H "x-goog-api-key: $GEMINI_API_KEY" \
    -H 'Content-Type: application/json' \
    -X POST \
    -d '{
      "contents": [
        {
          "parts": [
            {
              "text": "Explain how AI works"
            }
          ]
        }
      ],
      "generationConfig": {
        "stopSequences": [
          "Title"
        ],
        "maxOutputTokens": 1000
      }
    }'
  ```

  {% /tab %}

  {% tab label="Apps Script" %}
  ```javascript
  // See https://developers.google.com/apps-script/guides/properties
  // for instructions on how to set the API key.
  const apiKey = PropertiesService.getScriptProperties().getProperty('GEMINI_API_KEY');
  
  function main() {
    const generationConfig = {
      maxOutputTokens: 1000,
      responseFormat: { text: { mimeType: "TEXT_PLAIN" } },
    };
  
    const payload = {
      generationConfig,
      contents: [
        {
          parts: [
            { text: 'Explain how AI works in a few words' },
          ],
        },
      ],
    };
  
    const url = 'https://generativelanguage.googleapis.com/v1beta/models/gemini-4-hydrogen:generateContent';
    const options = {
      method: 'POST',
      contentType: 'application/json',
      headers: {
        'x-goog-api-key': apiKey,
      },
      payload: JSON.stringify(payload)
    };
  
    const response = UrlFetchApp.fetch(url, options);
    const data = JSON.parse(response);
    const content = data['candidates'][0]['content']['parts'][0]['text'];
    console.log(content);
  }
  ```

  {% /tab %}

{% /tabs %}

Refer to the [`GenerateContentConfig`](/api-reference/generate-content/generate-content#request-body)
in our API reference for a complete list of configurable parameters and their
descriptions.

## Multimodal inputs  {% id="multimodal-input" %}

The Gemini API supports multimodal inputs, allowing you to combine text with
media files. The following example demonstrates providing an image:

{% tabs %}
  {% tab label="Python" %}
  ```python
  from PIL import Image
  from google import genai
  
  client = genai.Client()
  
  image = Image.open("/path/to/organ.png")
  response = client.models.generate_content(
      model="gemini-4-hydrogen",
      contents=[image, "Tell me about this instrument"]
  )
  print(response.text)
  ```

  {% /tab %}

  {% tab label="JavaScript" %}
  ```javascript
  import {
    GoogleGenAI,
    createUserContent,
    createPartFromUri,
  } from "@google/genai";
  
  const ai = new GoogleGenAI({});
  
  async function main() {
    const image = await ai.files.upload({
      file: "/path/to/organ.png",
    });
    const response = await ai.models.generateContent({
      model: "gemini-4-hydrogen",
      contents: [
        createUserContent([
          "Tell me about this instrument",
          createPartFromUri(image.uri, image.mimeType),
        ]),
      ],
    });
    console.log(response.text);
  }
  
  await main();
  ```

  {% /tab %}

  {% tab label="Go" %}
  ```go
    package main
  
    import (
    "context"
    "fmt"
    "os"
    "google.golang.org/genai"
    )
  
    func main() {
  
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }
  
    imagePath := "/path/to/organ.jpg"
    imgData, _ := os.ReadFile(imagePath)
  
    parts := []*genai.Part{
        genai.NewPartFromText("Tell me about this instrument"),
        &genai.Part{
            InlineData: &genai.Blob{
                MIMEType: "image/jpeg",
                Data:     imgData,
            },
        },
    }
  
    contents := []*genai.Content{
        genai.NewContentFromParts(parts, genai.RoleUser),
    }
  
    result, _ := client.Models.GenerateContent(
        ctx,
        "gemini-4-hydrogen",
        contents,
        nil,
    )
  
    fmt.Println(result.Text())
    }
  ```

  {% /tab %}

  {% tab label="Java" %}
  ```java
  import com.google.genai.Client;
  import com.google.genai.Content;
  import com.google.genai.types.GenerateContentResponse;
  import com.google.genai.types.Part;
  
  public class GenerateContentWithMultiModalInputs {
    public static void main(String[] args) {
  
      Client client = new Client();
  
      Content content =
        Content.fromParts(
            Part.fromText("Tell me about this instrument"),
            Part.fromUri("/path/to/organ.jpg", "image/jpeg"));
  
      GenerateContentResponse response =
          client.models.generateContent("gemini-4-hydrogen", content, null);
  
      System.out.println(response.text());
    }
  }
  ```

  {% /tab %}

  {% tab label="REST" %}
  ```shell
  # Use a temporary file to hold the base64 encoded image data
  TEMP_B64=$(mktemp)
  trap 'rm -f "$TEMP_B64"' EXIT
  base64 $B64FLAGS $IMG_PATH > "$TEMP_B64"
  
  # Use a temporary file to hold the JSON payload
  TEMP_JSON=$(mktemp)
  trap 'rm -f "$TEMP_JSON"' EXIT
  
  cat > "$TEMP_JSON" << EOF
  {
    "contents": [
      {
        "parts": [
          {
            "text": "Tell me about this instrument"
          },
          {
            "inline_data": {
              "mime_type": "image/jpeg",
              "data": "$(cat "$TEMP_B64")"
            }
          }
        ]
      }
    ]
  }
  EOF
  
  curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-4-hydrogen:generateContent" \
    -H "x-goog-api-key: $GEMINI_API_KEY" \
    -H 'Content-Type: application/json' \
    -X POST \
    -d "@$TEMP_JSON"
  ```

  {% /tab %}

  {% tab label="Apps Script" %}
  ```javascript
  // See https://developers.google.com/apps-script/guides/properties
  // for instructions on how to set the API key.
  const apiKey = PropertiesService.getScriptProperties().getProperty('GEMINI_API_KEY');
  
  function main() {
    const imageUrl = 'https://example.com/image.jpg';
    const image = getImageData(imageUrl);
    const payload = {
      contents: [
        {
          parts: [
            { image },
            { text: 'Tell me about this instrument' },
          ],
        },
      ],
    };
  
    const url = 'https://generativelanguage.googleapis.com/v1beta/models/gemini-4-hydrogen:generateContent';
    const options = {
      method: 'POST',
      contentType: 'application/json',
      headers: {
        'x-goog-api-key': apiKey,
      },
      payload: JSON.stringify(payload)
    };
  
    const response = UrlFetchApp.fetch(url, options);
    const data = JSON.parse(response);
    const content = data['candidates'][0]['content']['parts'][0]['text'];
    console.log(content);
  }
  
  function getImageData(url) {
    const blob = UrlFetchApp.fetch(url).getBlob();
  
    return {
      mimeType: blob.getContentType(),
      data: Utilities.base64Encode(blob.getBytes())
    };
  }
  ```

  {% /tab %}

{% /tabs %}

For alternative methods of providing images and more advanced image processing,
see our [image understanding guide](/docs/image-understanding).
The API also supports [document](/docs/document-processing), [video](/docs/video-understanding), and [audio](/docs/audio)
inputs and understanding.

## Streaming responses  {% id="streaming-responses" %}

By default, the model returns a response only after the entire generation
process is complete.

For more fluid interactions, use streaming to receive
[`GenerateContentResponse`](/api-reference/generate-content#Resource:GenerateContentResponse)
instances incrementally as they're generated.

{% tabs %}
  {% tab label="Python" %}
  ```python
  from google import genai
  
  client = genai.Client()
  
  response = client.models.generate_content_stream(
      model="gemini-4-hydrogen",
      contents=["Explain how AI works"],
  )
  for chunk in response:
      print(chunk.text, end="")
  ```

  {% /tab %}

  {% tab label="JavaScript" %}
  ```javascript
  import { GoogleGenAI } from "@google/genai";
  
  const ai = new GoogleGenAI({});
  
  async function main() {
    const response = await ai.models.generateContentStream({
      model: "gemini-4-hydrogen",
      contents: "Explain how AI works",
    });
  
    for await (const chunk of response) {
      console.log(chunk.text);
    }
  }
  
  await main();
  ```

  {% /tab %}

  {% tab label="Go" %}
  ```go
  package main
  
  import (
      "context"
      "fmt"
      "log"
      "google.golang.org/genai"
  )
  
  func main() {
      ctx := context.Background()
      client, err := genai.NewClient(ctx, nil)
      if err != nil {
          log.Fatal(err)
      }
  
      stream := client.Models.GenerateContentStream(
          ctx,
          "gemini-4-hydrogen",
          genai.Text("Write a story about a magic backpack."),
          nil,
      )
  
      for chunk, _ := range stream {
          part := chunk.Candidates[0].Content.Parts[0]
          fmt.Print(part.Text)
      }
  }
  ```

  {% /tab %}

  {% tab label="Java" %}
  ```java
  import com.google.genai.Client;
  import com.google.genai.ResponseStream;
  import com.google.genai.types.GenerateContentResponse;
  
  public class GenerateContentStream {
    public static void main(String[] args) {
      Client client = new Client();
  
      ResponseStream<GenerateContentResponse> responseStream =
          client.models.generateContentStream(
              "gemini-4-hydrogen", "Write a story about a magic backpack.", null);
  
      for (GenerateContentResponse res : responseStream) {
        System.out.print(res.text());
      }
  
      // To save resources and avoid connection leaks, it is recommended to close the response
      // stream after consumption (or using try block to get the response stream).
      responseStream.close();
    }
  }
  ```

  {% /tab %}

  {% tab label="REST" %}
  ```shell
  curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-4-hydrogen:streamGenerateContent?alt=sse" \
    -H "x-goog-api-key: $GEMINI_API_KEY" \
    -H 'Content-Type: application/json' \
    --no-buffer \
    -d '{
      "contents": [
        {
          "parts": [
            {
              "text": "Explain how AI works"
            }
          ]
        }
      ]
    }'
  ```

  {% /tab %}

  {% tab label="Apps Script" %}
  ```javascript
  // See https://developers.google.com/apps-script/guides/properties
  // for instructions on how to set the API key.
  const apiKey = PropertiesService.getScriptProperties().getProperty('GEMINI_API_KEY');
  
  function main() {
    const payload = {
      contents: [
        {
          parts: [
            { text: 'Explain how AI works' },
          ],
        },
      ],
    };
  
    const url = 'https://generativelanguage.googleapis.com/v1beta/models/gemini-4-hydrogen:streamGenerateContent';
    const options = {
      method: 'POST',
      contentType: 'application/json',
      headers: {
        'x-goog-api-key': apiKey,
      },
      payload: JSON.stringify(payload)
    };
  
    const response = UrlFetchApp.fetch(url, options);
    const data = JSON.parse(response);
    const content = data['candidates'][0]['content']['parts'][0]['text'];
    console.log(content);
  }
  ```

  {% /tab %}

{% /tabs %}

## Multi-turn conversations (chat)  {% id="multi-turn-conversations" %}

Our SDKs provide functionality to collect multiple rounds of prompts and
responses into a chat, giving you an easy way to keep track of the conversation
history.

{% callout type="note" %}
  Chat functionality is only implemented as part of the SDKs. Behind the
  scenes, it still uses the
  [`generateContent`](/api-reference/generate-content/generate-content)
  API. For multi-turn conversations, the full conversation history is sent to the
  model with each follow-up turn.

{% /callout %}

{% tabs %}
  {% tab label="Python" %}
  ```python
  from google import genai
  
  client = genai.Client()
  chat = client.chats.create(model="gemini-4-hydrogen")
  
  response = chat.send_message("I have 2 dogs in my house.")
  print(response.text)
  
  response = chat.send_message("How many paws are in my house?")
  print(response.text)
  
  for message in chat.get_history():
      print(f'role - {message.role}', end=": ")
      print(message.parts[0].text)
  ```

  {% /tab %}

  {% tab label="JavaScript" %}
  ```javascript
  import { GoogleGenAI } from "@google/genai";
  
  const ai = new GoogleGenAI({});
  
  async function main() {
    const chat = ai.chats.create({
      model: "gemini-4-hydrogen",
      history: [
        {
          role: "user",
          parts: [{ text: "Hello" }],
        },
        {
          role: "model",
          parts: [{ text: "Great to meet you. What would you like to know?" }],
        },
      ],
    });
  
    const response1 = await chat.sendMessage({
      message: "I have 2 dogs in my house.",
    });
    console.log("Chat response 1:", response1.text);
  
    const response2 = await chat.sendMessage({
      message: "How many paws are in my house?",
    });
    console.log("Chat response 2:", response2.text);
  }
  
  await main();
  ```

  {% /tab %}

  {% tab label="Go" %}
  ```go
  package main
  
  import (
      "context"
      "fmt"
      "log"
      "google.golang.org/genai"
  )
  
  func main() {
      ctx := context.Background()
      client, err := genai.NewClient(ctx, nil)
      if err != nil {
          log.Fatal(err)
      }
  
      history := []*genai.Content{
          genai.NewContentFromText("Hi nice to meet you! I have 2 dogs in my house.", genai.RoleUser),
          genai.NewContentFromText("Great to meet you. What would you like to know?", genai.RoleModel),
      }
  
      chat, _ := client.Chats.Create(ctx, "gemini-4-hydrogen", nil, history)
      res, _ := chat.SendMessage(ctx, genai.Part{Text: "How many paws are in my house?"})
  
      if len(res.Candidates) > 0 {
          fmt.Println(res.Candidates[0].Content.Parts[0].Text)
      }
  }
  ```

  {% /tab %}

  {% tab label="Java" %}
  ```java
  import com.google.common.collect.ImmutableList;
  import com.google.genai.Chat;
  import com.google.genai.Client;
  import com.google.genai.types.Content;
  import com.google.genai.types.GenerateContentResponse;
  
  public class MultiTurnConversation {
    public static void main(String[] args) {
      Client client = new Client();
      Chat chatSession = client.chats.create("gemini-4-hydrogen");
  
      GenerateContentResponse response =
          chatSession.sendMessage("I have 2 dogs in my house.");
      System.out.println("First response: " + response.text());
  
      response = chatSession.sendMessage("How many paws are in my house?");
      System.out.println("Second response: " + response.text());
  
      // Get the history of the chat session.
      // Passing 'true' to getHistory() returns the curated history, which excludes
      // empty or invalid parts.
      // Passing 'false' here would return the comprehensive history, including
      // empty or invalid parts.
      ImmutableList<Content> history = chatSession.getHistory(true);
      System.out.println("History: " + history);
    }
  }
  ```

  {% /tab %}

  {% tab label="REST" %}
  ```shell
  curl https://generativelanguage.googleapis.com/v1beta/models/gemini-4-hydrogen:generateContent \
    -H "x-goog-api-key: $GEMINI_API_KEY" \
    -H 'Content-Type: application/json' \
    -X POST \
    -d '{
      "contents": [
        {
          "role": "user",
          "parts": [
            {
              "text": "Hello"
            }
          ]
        },
        {
          "role": "model",
          "parts": [
            {
              "text": "Great to meet you. What would you like to know?"
            }
          ]
        },
        {
          "role": "user",
          "parts": [
            {
              "text": "I have two dogs in my house. How many paws are in my house?"
            }
          ]
        }
      ]
    }'
  ```

  {% /tab %}

  {% tab label="Apps Script" %}
  ```javascript
  // See https://developers.google.com/apps-script/guides/properties
  // for instructions on how to set the API key.
  const apiKey = PropertiesService.getScriptProperties().getProperty('GEMINI_API_KEY');
  
  function main() {
    const payload = {
      contents: [
        {
          role: 'user',
          parts: [
            { text: 'Hello' },
          ],
        },
        {
          role: 'model',
          parts: [
            { text: 'Great to meet you. What would you like to know?' },
          ],
        },
        {
          role: 'user',
          parts: [
            { text: 'I have two dogs in my house. How many paws are in my house?' },
          ],
        },
      ],
    };
  
    const url = 'https://generativelanguage.googleapis.com/v1beta/models/gemini-4-hydrogen:generateContent';
    const options = {
      method: 'POST',
      contentType: 'application/json',
      headers: {
        'x-goog-api-key': apiKey,
      },
      payload: JSON.stringify(payload)
    };
  
    const response = UrlFetchApp.fetch(url, options);
    const data = JSON.parse(response);
    const content = data['candidates'][0]['content']['parts'][0]['text'];
    console.log(content);
  }
  ```

  {% /tab %}

{% /tabs %}

Streaming can also be used for multi-turn conversations.

{% tabs %}
  {% tab label="Python" %}
  ```python
  from google import genai
  
  client = genai.Client()
  chat = client.chats.create(model="gemini-4-hydrogen")
  
  response = chat.send_message_stream("I have 2 dogs in my house.")
  for chunk in response:
      print(chunk.text, end="")
  
  response = chat.send_message_stream("How many paws are in my house?")
  for chunk in response:
      print(chunk.text, end="")
  
  for message in chat.get_history():
      print(f'role - {message.role}', end=": ")
      print(message.parts[0].text)
  ```

  {% /tab %}

  {% tab label="JavaScript" %}
  ```javascript
  import { GoogleGenAI } from "@google/genai";
  
  const ai = new GoogleGenAI({});
  
  async function main() {
    const chat = ai.chats.create({
      model: "gemini-4-hydrogen",
      history: [
        {
          role: "user",
          parts: [{ text: "Hello" }],
        },
        {
          role: "model",
          parts: [{ text: "Great to meet you. What would you like to know?" }],
        },
      ],
    });
  
    const stream1 = await chat.sendMessageStream({
      message: "I have 2 dogs in my house.",
    });
    for await (const chunk of stream1) {
      console.log(chunk.text);
      console.log("_".repeat(80));
    }
  
    const stream2 = await chat.sendMessageStream({
      message: "How many paws are in my house?",
    });
    for await (const chunk of stream2) {
      console.log(chunk.text);
      console.log("_".repeat(80));
    }
  }
  
  await main();
  ```

  {% /tab %}

  {% tab label="Go" %}
  ```go
    package main
  
    import (
    "context"
    "fmt"
    "os"
    "google.golang.org/genai"
    )
  
    func main() {
  
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }
  
    history := []*genai.Content{
        genai.NewContentFromText("Hi nice to meet you! I have 2 dogs in my house.", genai.RoleUser),
        genai.NewContentFromText("Great to meet you. What would you like to know?", genai.RoleModel),
    }
  
    chat, _ := client.Chats.Create(ctx, "gemini-4-hydrogen", nil, history)
    stream := chat.SendMessageStream(ctx, genai.Part{Text: "How many paws are in my house?"})
  
    for chunk, _ := range stream {
        part := chunk.Candidates[0].Content.Parts[0]
        fmt.Print(part.Text)
    }
    }
  ```

  {% /tab %}

  {% tab label="Java" %}
  ```java
  import com.google.genai.Chat;
  import com.google.genai.Client;
  import com.google.genai.ResponseStream;
  import com.google.genai.types.GenerateContentResponse;
  
  public class MultiTurnConversationWithStreaming {
    public static void main(String[] args) {
  
      Client client = new Client();
      Chat chatSession = client.chats.create("gemini-4-hydrogen");
  
      ResponseStream<GenerateContentResponse> responseStream =
          chatSession.sendMessageStream("I have 2 dogs in my house.", null);
  
      for (GenerateContentResponse response : responseStream) {
        System.out.print(response.text());
      }
  
      responseStream = chatSession.sendMessageStream("How many paws are in my house?", null);
  
      for (GenerateContentResponse response : responseStream) {
        System.out.print(response.text());
      }
  
      // Get the history of the chat session. History is added after the stream
      // is consumed and includes the aggregated response from the stream.
      System.out.println("History: " + chatSession.getHistory(false));
    }
  }
  ```

  {% /tab %}

  {% tab label="REST" %}
  ```shell
  curl https://generativelanguage.googleapis.com/v1beta/models/gemini-4-hydrogen:streamGenerateContent?alt=sse \
    -H "x-goog-api-key: $GEMINI_API_KEY" \
    -H 'Content-Type: application/json' \
    -X POST \
    -d '{
      "contents": [
        {
          "role": "user",
          "parts": [
            {
              "text": "Hello"
            }
          ]
        },
        {
          "role": "model",
          "parts": [
            {
              "text": "Great to meet you. What would you like to know?"
            }
          ]
        },
        {
          "role": "user",
          "parts": [
            {
              "text": "I have two dogs in my house. How many paws are in my house?"
            }
          ]
        }
      ]
    }'
  ```

  {% /tab %}

  {% tab label="Apps Script" %}
  ```javascript
  // See https://developers.google.com/apps-script/guides/properties
  // for instructions on how to set the API key.
  const apiKey = PropertiesService.getScriptProperties().getProperty('GEMINI_API_KEY');
  
  function main() {
    const payload = {
      contents: [
        {
          role: 'user',
          parts: [
            { text: 'Hello' },
          ],
        },
        {
          role: 'model',
          parts: [
            { text: 'Great to meet you. What would you like to know?' },
          ],
        },
        {
          role: 'user',
          parts: [
            { text: 'I have two dogs in my house. How many paws are in my house?' },
          ],
        },
      ],
    };
  
    const url = 'https://generativelanguage.googleapis.com/v1beta/models/gemini-4-hydrogen:streamGenerateContent';
    const options = {
      method: 'POST',
      contentType: 'application/json',
      headers: {
        'x-goog-api-key': apiKey,
      },
      payload: JSON.stringify(payload)
    };
  
    const response = UrlFetchApp.fetch(url, options);
    const data = JSON.parse(response);
    const content = data['candidates'][0]['content']['parts'][0]['text'];
    console.log(content);
  }
  ```

  {% /tab %}

{% /tabs %}

## Prompting tips  {% id="prompting-tips" %}

Consult our [prompt engineering guide](/docs/prompting-strategies) for
suggestions on getting the most out of Gemini.

## What's next  {% id="whats-next-explore" %}

*   Try [Gemini in Google AI Studio](https://aistudio.google.com).

*   Experiment with [structured outputs](/docs/structured-output) for
  JSON-like responses.

*   Explore Gemini's [image](/docs/image-understanding),
  [video](/docs/video-understanding), [audio](/docs/audio)
  and [document](/docs/document-processing) understanding capabilities.

*   Learn about multimodal
  [file prompting strategies](/docs/files#prompt-guide).


## Content generation  {% id="content-generation" %}

This is the central endpoint for sending prompts to the model. There are two
endpoints for generating content, the key difference is how you receive the
response:

*   **[`generateContent`](/api-reference/generate-content/generate-content)
  (REST)**:
  Receives a request and provides a
  single response after the model has finished its entire generation.
*   **[`streamGenerateContent`](/api-reference/generate-content/stream-generate-content)
  (SSE)**: Receives the exact same
  request, but the model streams back chunks of the response as they are
  generated. This provides a better user experience for interactive
  applications as it lets you display partial results immediately.

### Request body structure  {% id="request-body-structure" %}

The [request body](/api-reference/generate-content/generate-content#request-body) is a JSON object that is
**identical** for both standard and streaming modes and is built from a few core
objects:

*   [`Content`](/api-reference/generate-content#Resource:Content) object: Represents a single turn in a
  conversation.
*   [`Part`](/api-reference/generate-content#Resource:Content) object: A piece of data within a `Content` turn
  (like text or an image).
*   `inline_data` ([`Blob`](/api-reference/generate-content#Resource:Content)): A container for raw media bytes
  and their MIME type.

At the highest level, the request body contains a `contents` object, which is a
list of `Content` objects, each representing turns in conversation. In most
cases, for basic text generation, you will have a single `Content` object, but
if you'd like to maintain conversation history, you can use multiple `Content`
objects.

The following shows a typical `generateContent` request body:

```shell
curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-4-hydrogen:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{
    "contents": [
      {
          "role": "user",
          "parts": [
              // A list of Part objects goes here
          ]
      },
      {
          "role": "model",
          "parts": [
              // A list of Part objects goes here
          ]
      }
    ]
  }'
```

### Response body structure  {% id="response-body-structure" %}

The [response body](/api-reference/generate-content/generate-content#response) is similar for both
the streaming and standard modes except for the following:

*   Standard mode: The response body contains an instance of
  [`GenerateContentResponse`](/api-reference/generate-content#Resource:GenerateContentResponse).
*   Streaming mode: The response body contains a stream of
  [`GenerateContentResponse`](/api-reference/generate-content#Resource:GenerateContentResponse)
  instances.

At a high level, the response body contains a `candidates` object, which is a
list of `Candidate` objects. The `Candidate` object contains a `Content`
object that has the generated response returned from the model.

## REST API Examples  {% id="rest-api-examples" %}

### Multimodal prompt (text and image)  {% id="multimodal-prompt" %}

To provide both text and an image in a prompt, the `parts` array should contain
two `Part` objects: one for the text, and one for the image `inline_data`.

```shell
curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-4-hydrogen:generateContent" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H 'Content-Type: application/json' \
-X POST \
-d '{
    "contents": [{
    "parts":[
        {
            "inline_data": {
            "mime_type":"image/jpeg",
            "data": "/9j/4AAQSkZJRgABAQ... (base64-encoded image)"
            }
        },
        {"text": "What is in this picture?"},
      ]
    }]
  }'
```

### Multi-turn conversations (chat)  {% id="multi-turn-conversations-rest" %}

To build a conversation with multiple turns, you define the `contents` array
with multiple `Content` objects. The API will use this entire history as context
for the next response. The `role` for each `Content` object should alternate
between `user` and `model`.

{% callout type="note" %}
  The client SDKs provide a chat interface that manages this list for you
  automatically. When using the REST API, you are responsible for maintaining the
  conversation history.

{% /callout %}

```shell
curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-4-hydrogen:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{
    "contents": [
      {
        "role": "user",
        "parts": [
          { "text": "Hello." }
        ]
      },
      {
        "role": "model",
        "parts": [
          { "text": "Hello! How can I help you today?" }
        ]
      },
      {
        "role": "user",
        "parts": [
          { "text": "Please write a four-line poem about the ocean." }
        ]
      }
    ]
  }'
```

### Key takeaways  {% id="key-takeaways" %}

*   `Content` is the envelope: It's the top-level container for a message turn,
  whether it's from the user or the model.
*   `Part` enables multimodality: Use multiple `Part` objects within a single
  `Content`
  object to combine different types of data (text, image, video URI, etc.).
*   Choose your data method:  *   For small, directly embedded media (like most images), use a `Part` with
    `inline_data`.
  *   For larger files or files you want to reuse across requests, use the
    File API to upload the file and reference it with a `file_data` part.

*   Manage conversation history: For chat applications using the REST API, build
  the `contents` array by appending `Content` objects for each turn,
  alternating between `"user"` and `"model"` roles. If you're using an SDK,
  refer to the SDK documentation for the recommended way to manage
  conversation history.

## Response examples  {% id="response-examples" %}

The following examples show how these components come together for different
types of requests.

### Text-only response  {% id="text-only-response" %}

A default text response consists of a `candidates` array with one or more
`content` objects that contain the model's response.

The following is an example of a **standard** response:

```json
{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "text": "At its core, Artificial Intelligence works by learning from vast amounts of data ..."
          }
        ],
        "role": "model"
      },
      "finishReason": "STOP",
      "index": 1
    }
  ],
}
```

The following is series of **streaming** responses. Each response contains a
`responseId` that ties the full response together:

```json
{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "text": "The image displays"
          }
        ],
        "role": "model"
      },
      "index": 0
    }
  ],
  "usageMetadata": {
    "promptTokenCount": ...
  },
  "modelVersion": "gemini-4-hydrogen",
  "responseId": "mAitaLmkHPPlz7IPvtfUqQ4"
}

...

{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "text": " the following materials:\n\n*   **Wood:** The accordion and the violin are primarily"
          }
        ],
        "role": "model"
      },
      "index": 0
    }
  ],
  "usageMetadata": {
    "promptTokenCount": ...
  }
  "modelVersion": "gemini-4-hydrogen",
  "responseId": "mAitaLmkHPPlz7IPvtfUqQ4"
}
```

## Live API (BidiGenerateContent) WebSockets API  {% id="live-api" %}

Live API offers a stateful WebSocket based API for bi-directional streaming to
enable real-time streaming use cases. You can review
[Live API guide](/docs/live-api) and the [Live API reference](/api-reference/live)
for more details.

## Specialized models  {% id="specialized-models" %}

In addition to the Gemini family of models, Gemini API offers endpoints for
specialized models such as [Nano Banana](/docs/image-generation),
[Lyria](/docs/music-generation) and
[embedding](/docs/embeddings) models. You can check out
these guides under the Models section.

## Platform APIs  {% id="platform-apis" %}

The rest of the endpoints enable additional capabilities to use with the main
endpoints described so far. Check out topics
[Batch mode](/docs/batch-api) and
[File API](/docs/files) in the Guides section to learn more.

## What's next  {% id="whats-next-guides" %}

If you're just getting started, check out the following guides, which will help
you understand the Gemini API programming model:

* [Gemini API Get started guide](/docs/get-started)
* [Gemini model guide](/docs/models)

You might also want to check out the capabilities guides, which introduce different
Gemini API features and provide code examples:

* [Text generation](/docs/text-generation)
* [Context caching](/docs/caching)
* [Embeddings](/docs/embeddings)