Content Generation

/**
 * Generate content from a model
 * @param params - Generation parameters
 * @returns Promise resolving to generation response
 */
function generateContent(
  params: GenerateContentParameters
): Promise<GenerateContentResponse>;

interface GenerateContentParameters {
  /** Model name (e.g., 'gemini-2.0-flash', 'models/gemini-2.0-flash', 'tunedModels/{id}') */
  model: string;
  /** Input content(s) - flexible string, Part, or Content input */
  contents: ContentListUnion;
  /** Generation configuration */
  config?: GenerateContentConfig;
}

interface GenerateContentResponse {
  /** Response candidates */
  candidates?: Candidate[];
  /** Helper property for first candidate text */
  text?: string;
  /** Function calls to execute */
  functionCalls?: FunctionCall[];
  /** Token usage information */
  usageMetadata?: UsageMetadata;
  /** Prompt evaluation feedback */
  promptFeedback?: PromptFeedback;
  /** Model version used */
  modelVersion?: string;
  /** Automatic function calling history */
  automaticFunctionCallingHistory?: Content[];
  /** HTTP response metadata */
  sdkHttpResponse?: HttpResponse;
}

import { GoogleGenAI } from '@google/genai';

const client = new GoogleGenAI({ apiKey: 'YOUR_API_KEY' });

// Simple text generation
const response = await client.models.generateContent({
  model: 'gemini-2.0-flash',
  contents: 'Explain quantum computing in simple terms'
});

console.log(response.text);

// With generation config
const configuredResponse = await client.models.generateContent({
  model: 'gemini-2.0-flash',
  contents: 'Write a creative story',
  config: {
    temperature: 1.0,
    maxOutputTokens: 2048,
    topP: 0.95
  }
});

// Multimodal input
const multimodalResponse = await client.models.generateContent({
  model: 'gemini-2.0-flash',
  contents: [
    { role: 'user', parts: [
      { text: 'What is in this image?' },
      { fileData: {
        fileUri: 'gs://bucket/image.jpg',
        mimeType: 'image/jpeg'
      }}
    ]}
  ]
});

// With system instruction
const instructedResponse = await client.models.generateContent({
  model: 'gemini-2.0-flash',
  contents: 'Tell me about dogs',
  config: {
    systemInstruction: 'You are a veterinarian. Always provide medical context.'
  }
});

/**
 * Stream content generation
 * @param params - Generation parameters
 * @returns Promise resolving to async generator of response chunks
 */
function generateContentStream(
  params: GenerateContentParameters
): Promise<AsyncGenerator<GenerateContentResponse>>;

// Stream text generation
const stream = await client.models.generateContentStream({
  model: 'gemini-2.0-flash',
  contents: 'Write a long article about artificial intelligence'
});

for await (const chunk of stream) {
  process.stdout.write(chunk.text || '');
}

// Stream with progress tracking
const streamWithProgress = await client.models.generateContentStream({
  model: 'gemini-2.0-flash',
  contents: 'Explain machine learning concepts',
  config: {
    maxOutputTokens: 4096
  }
});

let totalTokens = 0;
for await (const chunk of streamWithProgress) {
  if (chunk.text) {
    console.log(chunk.text);
  }
  if (chunk.usageMetadata) {
    totalTokens = chunk.usageMetadata.totalTokenCount || 0;
  }
}
console.log(`Total tokens used: ${totalTokens}`);

/**
 * Count tokens in content
 * @param params - Token counting parameters
 * @returns Promise resolving to token count
 */
function countTokens(
  params: CountTokensParameters
): Promise<CountTokensResponse>;

interface CountTokensParameters {
  /** Model name */
  model: string;
  /** Content to count tokens for */
  contents: ContentListUnion;
}

interface CountTokensResponse {
  /** Total token count */
  totalTokens?: number;
}

// Count tokens in a prompt
const tokenCount = await client.models.countTokens({
  model: 'gemini-2.0-flash',
  contents: 'What is the capital of France?'
});

console.log(`Tokens: ${tokenCount.totalTokens}`);

// Count tokens with multimodal content
const multimodalCount = await client.models.countTokens({
  model: 'gemini-2.0-flash',
  contents: [
    { role: 'user', parts: [
      { text: 'Describe this image' },
      { fileData: {
        fileUri: 'gs://bucket/image.jpg',
        mimeType: 'image/jpeg'
      }}
    ]}
  ]
});

/**
 * Get detailed token information
 * @param params - Token computation parameters
 * @returns Promise resolving to detailed token information
 */
function computeTokens(
  params: ComputeTokensParameters
): Promise<ComputeTokensResponse>;

interface ComputeTokensParameters {
  /** Model name */
  model: string;
  /** Content to analyze */
  contents: ContentListUnion;
}

interface ComputeTokensResponse {
  /** Total billable characters */
  totalBillableCharacters?: number;
  /** Total token count */
  totalTokens?: number;
  /** Token metadata for each content part */
  tokensMetadataPerPart?: TokensMetadata[];
}

interface TokensMetadata {
  /** Token IDs */
  tokenIds?: number[];
  /** Role of the content */
  role?: string;
}

// Get detailed token information (Vertex AI)
const vertexClient = new GoogleGenAI({
  vertexai: true,
  project: 'my-project',
  location: 'us-central1'
});

const tokenInfo = await vertexClient.models.computeTokens({
  model: 'gemini-2.0-flash',
  contents: 'What is machine learning?'
});

console.log(`Total tokens: ${tokenInfo.totalTokens}`);
console.log(`Billable characters: ${tokenInfo.totalBillableCharacters}`);

interface GenerateContentConfig {
  /** Randomness in generation (0.0-2.0) */
  temperature?: number;
  /** Nucleus sampling threshold (0.0-1.0) */
  topP?: number;
  /** Top-k sampling parameter */
  topK?: number;
  /** Number of response candidates */
  candidateCount?: number;
  /** Maximum output tokens */
  maxOutputTokens?: number;
  /** Stop sequences to end generation */
  stopSequences?: string[];
  /** Presence penalty (-2.0 to 2.0) */
  presencePenalty?: number;
  /** Frequency penalty (-2.0 to 2.0) */
  frequencyPenalty?: number;
  /** Output modalities (TEXT, AUDIO, IMAGE) */
  responseModalities?: Modality[];
  /** System instructions for the model */
  systemInstruction?: Content | string;
  /** Tools/functions available to model */
  tools?: ToolListUnion;
  /** Tool configuration */
  toolConfig?: ToolConfig;
  /** Safety filter settings */
  safetySettings?: SafetySetting[];
  /** Cached content reference */
  cachedContent?: string;
  /** Automatic function calling configuration */
  automaticFunctionCalling?: AutomaticFunctionCallingConfig;
  /** Thinking configuration for extended reasoning */
  thinkingConfig?: ThinkingConfig;
  /** Schema for structured output */
  responseSchema?: Schema;
  /** JSON schema for structured output */
  responseJsonSchema?: unknown;
  /** Response MIME type (e.g., 'application/json') */
  responseMimeType?: string;
  /** HTTP options */
  httpOptions?: HttpOptions;
  /** Abort signal for cancellation */
  abortSignal?: AbortSignal;
}

interface Candidate {
  /** Generated content */
  content?: Content;
  /** Reason generation stopped */
  finishReason?: FinishReason;
  /** Safety ratings */
  safetyRatings?: SafetyRating[];
  /** Citation metadata */
  citationMetadata?: CitationMetadata;
  /** Token count */
  tokenCount?: number;
  /** Candidate index */
  index?: number;
}

interface PromptFeedback {
  /** Block reason if prompt was blocked */
  blockReason?: BlockedReason;
  /** Safety ratings for prompt */
  safetyRatings?: SafetyRating[];
}

interface UsageMetadata {
  /** Prompt token count */
  promptTokenCount?: number;
  /** Response candidates token count */
  candidatesTokenCount?: number;
  /** Total token count */
  totalTokenCount?: number;
  /** Cached content token count */
  cachedContentTokenCount?: number;
}

interface Content {
  /** List of content parts */
  parts?: Part[];
  /** Role ('user' or 'model') */
  role?: string;
}

interface Part {
  /** Text content */
  text?: string;
  /** Inline binary data (base64) */
  inlineData?: Blob;
  /** URI reference to file */
  fileData?: FileData;
  /** Function call from model */
  functionCall?: FunctionCall;
  /** Function response from user */
  functionResponse?: FunctionResponse;
  /** Video-specific metadata */
  videoMetadata?: VideoMetadata;
  /** Executable code */
  executableCode?: ExecutableCode;
  /** Code execution result */
  codeExecutionResult?: CodeExecutionResult;
  /** Whether part is model's internal thought */
  thought?: boolean;
  /** Media tokenization settings */
  mediaResolution?: PartMediaResolution;
}

interface Blob {
  /** MIME type */
  mimeType?: string;
  /** Base64-encoded data */
  data?: string;
}

interface FileData {
  /** File URI (e.g., 'gs://bucket/file.jpg' or Gemini file URI) */
  fileUri?: string;
  /** MIME type */
  mimeType?: string;
}

interface VideoMetadata {
  /** Video duration (e.g., '3.5s') */
  videoDuration?: string;
}

/** Part or string */
type PartUnion = Part | string;

/** Array or single Part/string */
type PartListUnion = PartUnion[] | PartUnion;

/** Content, Part array, or Part/string */
type ContentUnion = Content | PartUnion[] | PartUnion;

/** Content array or any PartUnion combination */
type ContentListUnion = Content | Content[] | PartUnion | PartUnion[];

interface SafetySetting {
  /** Harm category to filter */
  category?: HarmCategory;
  /** Blocking threshold level */
  threshold?: HarmBlockThreshold;
  /** Blocking method */
  method?: HarmBlockMethod;
}

interface SafetyRating {
  /** Harm category */
  category?: HarmCategory;
  /** Harm probability */
  probability?: HarmProbability;
  /** Whether content was blocked */
  blocked?: boolean;
  /** Probability score (0.0-1.0) */
  probabilityScore?: number;
  /** Harm severity */
  severity?: HarmSeverity;
  /** Severity score */
  severityScore?: number;
}

enum HarmCategory {
  HARM_CATEGORY_UNSPECIFIED = 'HARM_CATEGORY_UNSPECIFIED',
  HARM_CATEGORY_HATE_SPEECH = 'HARM_CATEGORY_HATE_SPEECH',
  HARM_CATEGORY_SEXUALLY_EXPLICIT = 'HARM_CATEGORY_SEXUALLY_EXPLICIT',
  HARM_CATEGORY_HARASSMENT = 'HARM_CATEGORY_HARASSMENT',
  HARM_CATEGORY_DANGEROUS_CONTENT = 'HARM_CATEGORY_DANGEROUS_CONTENT',
  HARM_CATEGORY_CIVIC_INTEGRITY = 'HARM_CATEGORY_CIVIC_INTEGRITY'
}

enum HarmBlockThreshold {
  HARM_BLOCK_THRESHOLD_UNSPECIFIED = 'HARM_BLOCK_THRESHOLD_UNSPECIFIED',
  BLOCK_LOW_AND_ABOVE = 'BLOCK_LOW_AND_ABOVE',
  BLOCK_MEDIUM_AND_ABOVE = 'BLOCK_MEDIUM_AND_ABOVE',
  BLOCK_ONLY_HIGH = 'BLOCK_ONLY_HIGH',
  BLOCK_NONE = 'BLOCK_NONE',
  OFF = 'OFF'
}

enum HarmProbability {
  HARM_PROBABILITY_UNSPECIFIED = 'HARM_PROBABILITY_UNSPECIFIED',
  NEGLIGIBLE = 'NEGLIGIBLE',
  LOW = 'LOW',
  MEDIUM = 'MEDIUM',
  HIGH = 'HIGH'
}

interface AutomaticFunctionCallingConfig {
  /** Disable automatic function calling */
  disable?: boolean;
  /** Maximum number of remote calls (default: 10) */
  maximumRemoteCalls?: number;
  /** Include AFC history in response */
  shouldAppendHistory?: boolean;
}

interface ThinkingConfig {
  /** Whether to include thinking process in response */
  includeThoughts?: boolean;
}

enum FinishReason {
  FINISH_REASON_UNSPECIFIED = 'FINISH_REASON_UNSPECIFIED',
  STOP = 'STOP',
  MAX_TOKENS = 'MAX_TOKENS',
  SAFETY = 'SAFETY',
  RECITATION = 'RECITATION',
  OTHER = 'OTHER',
  BLOCKLIST = 'BLOCKLIST',
  PROHIBITED_CONTENT = 'PROHIBITED_CONTENT',
  SPII = 'SPII',
  MALFORMED_FUNCTION_CALL = 'MALFORMED_FUNCTION_CALL'
}

enum BlockedReason {
  BLOCKED_REASON_UNSPECIFIED = 'BLOCKED_REASON_UNSPECIFIED',
  SAFETY = 'SAFETY',
  OTHER = 'OTHER',
  BLOCKLIST = 'BLOCKLIST',
  PROHIBITED_CONTENT = 'PROHIBITED_CONTENT'
}

enum Modality {
  TEXT = 'TEXT',
  IMAGE = 'IMAGE',
  AUDIO = 'AUDIO'
}

// Generate structured output
const structuredResponse = await client.models.generateContent({
  model: 'gemini-2.0-flash',
  contents: 'List three popular programming languages',
  config: {
    responseMimeType: 'application/json',
    responseSchema: {
      type: Type.OBJECT,
      properties: {
        languages: {
          type: Type.ARRAY,
          items: {
            type: Type.OBJECT,
            properties: {
              name: { type: Type.STRING },
              yearCreated: { type: Type.INTEGER },
              paradigm: { type: Type.STRING }
            },
            required: ['name', 'yearCreated']
          }
        }
      },
      required: ['languages']
    }
  }
});

const data = JSON.parse(structuredResponse.text || '{}');
console.log(data.languages);

// Multi-turn conversation without chat session
const response1 = await client.models.generateContent({
  model: 'gemini-2.0-flash',
  contents: [
    { role: 'user', parts: [{ text: 'What is the capital of France?' }] }
  ]
});

const response2 = await client.models.generateContent({
  model: 'gemini-2.0-flash',
  contents: [
    { role: 'user', parts: [{ text: 'What is the capital of France?' }] },
    { role: 'model', parts: [{ text: response1.text || '' }] },
    { role: 'user', parts: [{ text: 'What is its population?' }] }
  ]
});

// Custom safety settings
const safeResponse = await client.models.generateContent({
  model: 'gemini-2.0-flash',
  contents: 'Write a story about adventure',
  config: {
    safetySettings: [
      {
        category: HarmCategory.HARM_CATEGORY_DANGEROUS_CONTENT,
        threshold: HarmBlockThreshold.BLOCK_LOW_AND_ABOVE
      },
      {
        category: HarmCategory.HARM_CATEGORY_HATE_SPEECH,
        threshold: HarmBlockThreshold.BLOCK_MEDIUM_AND_ABOVE
      }
    ]
  }
});

// Check if response was blocked
if (safeResponse.promptFeedback?.blockReason) {
  console.log('Prompt was blocked:', safeResponse.promptFeedback.blockReason);
}

// Cancel generation after timeout
const controller = new AbortController();

setTimeout(() => {
  controller.abort();
}, 5000); // Abort after 5 seconds

try {
  const response = await client.models.generateContent({
    model: 'gemini-2.0-flash',
    contents: 'Write a very long essay',
    config: {
      abortSignal: controller.signal
    }
  });
} catch (error) {
  if (error.name === 'AbortError') {
    console.log('Generation was aborted');
  }
}

// Create cache first
const cache = await client.caches.create({
  model: 'gemini-2.0-flash',
  contents: [
    { role: 'user', parts: [{ text: 'Large context document...' }] }
  ],
  config: {
    ttl: '3600s'
  }
});

// Use cached content in generation
const cachedResponse = await client.models.generateContent({
  model: 'gemini-2.0-flash',
  contents: 'Summarize the document',
  config: {
    cachedContent: cache.name
  }
});