Generate Content

generateContent is the most commonly used generation endpoint in Gemini's native REST API, suitable for text Q&A, multi-turn chat, structured output, and multimodal understanding.

Endpoint

POST https://hboom.ai/v1beta/models/{model}:generateContent

Example models:

• gemini-3-flash-preview
• gemini-3-pro-preview
• gemini-2.5-flash

Authentication

• Google's native examples use x-goog-api-key: $GEMINI_API_KEY
• When using the hboom relay, use the platform API key; examples below use the hboom gateway address

Minimal Request Example

curl "https://hboom.ai/v1beta/models/gemini-3-flash-preview:generateContent" \
  -H "Authorization: Bearer sk-xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{
    "contents": [
      {
        "parts": [
          {
            "text": "Explain how AI works in a few words"
          }
        ]
      }
    ]
  }'

Equivalent Google native request:

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3-flash-preview:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{
    "contents": [
      {
        "parts": [
          {
            "text": "Explain how AI works in a few words"
          }
        ]
      }
    ]
  }'

Common Request Fields

Field	Required	Description
contents	Yes	Array of conversation content (at least one message)
contents[].role	No	Role: user or model
contents[].parts	Yes	Array of message content parts
parts[].text	No	Text input
parts[].inlineData	No	Base64-encoded image, audio, video, etc.
parts[].fileData	No	Reference to an uploaded file
system_instruction	No	System prompt
generationConfig	No	Generation settings: temperature, output format, etc.
safetySettings	No	Safety filter config
tools	No	Tool definitions, e.g. Google Search, function calling

Request Body Examples

Plain Text

{
  "contents": [
    {
      "parts": [
        {
          "text": "Explain how AI works in a few words"
        }
      ]
    }
  ]
}

With System Prompt

{
  "system_instruction": {
    "parts": [
      {
        "text": "You are a concise assistant."
      }
    ]
  },
  "contents": [
    {
      "parts": [
        {
          "text": "Explain how AI works in a few words"
        }
      ]
    }
  ]
}

With Generation Config

{
  "contents": [
    {
      "parts": [
        {
          "text": "Explain how AI works in a few words"
        }
      ]
    }
  ],
  "generationConfig": {
    "temperature": 0.7,
    "topP": 0.8,
    "topK": 20,
    "maxOutputTokens": 256,
    "responseMimeType": "text/plain"
  }
}

Multi-turn Conversation

{
  "contents": [
    {
      "role": "user",
      "parts": [{ "text": "Hello" }]
    },
    {
      "role": "model",
      "parts": [{ "text": "Great to meet you. What would you like to know?" }]
    },
    {
      "role": "user",
      "parts": [{ "text": "Explain how AI works in a few words" }]
    }
  ]
}

Response Example

{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "text": "AI learns patterns from data and uses them to make predictions."
          }
        ],
        "role": "model"
      },
      "finishReason": "STOP",
      "avgLogprobs": -0.12
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 8,
    "candidatesTokenCount": 14,
    "totalTokenCount": 22
  },
  "modelVersion": "gemini-3-flash-preview"
}

Common Response Fields

Field	Description
candidates	Array of candidate results
candidates[].content.parts[].text	Model output text
candidates[].finishReason	Stop reason, e.g. STOP
usageMetadata	Token usage stats
modelVersion	Actual model version returned
promptFeedback	Prompt filter or block info

Streaming

For streaming output, use:

POST /v1beta/models/{model}:streamGenerateContent?alt=sse

Example:

curl "https://hboom.ai/v1beta/models/gemini-3-flash-preview:streamGenerateContent?alt=sse" \
  -H "Authorization: Bearer sk-xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  --no-buffer \
  -d '{
    "contents": [
      {
        "parts": [
          {
            "text": "Explain how AI works"
          }
        ]
      }
    ]
  }'

Use Cases

• Text Q&A
• Multi-turn chat
• Image + text understanding
• Audio, video, and PDF understanding with text output
• JSON structured output
• Tool calling and search augmentation

Notes

• generateContent is a synchronous endpoint that returns the result immediately
• For multimodal input (image, audio, video), the output is typically still text
• For video generation, use Veo 3.1 Fast Video instead
• For streaming text output, use streamGenerateContent

References

• Gemini Text Generation: https://ai.google.dev/gemini-api/docs/text-generation
• Gemini 3 Developer Guide: https://ai.google.dev/gemini-api/docs/gemini-3