gemini-api（Gemini API 文档）

Gemini API Patterns

SDK Setup

Use the @google/genai package with Expo Constants for API key management:

import { GoogleGenAI } from '@google/genai';
import Constants from 'expo-constants';

const genAI = new GoogleGenAI({
  apiKey: Constants.expoConfig?.extra?.geminiApiKey as string
});

Available Models

All models support 1M input tokens and 65K output tokens.

Basic Text Generation

const response = await genAI.models.generateContent({
  model: 'gemini-3-flash-preview',
  contents: 'Your prompt here',
});
const text = response.text ?? '';

Structured Content Format

For multi-turn or complex inputs, use the full contents structure:

const response = await genAI.models.generateContent({
  model: 'gemini-3-flash-preview',
  contents: [
    { role: 'user', parts: [{ text: 'First message' }] },
    { role: 'model', parts: [{ text: 'Assistant response' }] },
    { role: 'user', parts: [{ text: 'Follow-up question' }] },
  ],
});

System Instructions

Guide model behavior with system instructions in the config:

const response = await genAI.models.generateContent({
  model: 'gemini-3-flash-preview',
  contents: [{ role: 'user', parts: [{ text: userMessage }] }],
  config: {
    systemInstruction: 'You are a helpful language tutor. Respond in a friendly, encouraging tone.',
  },
});

JSON Mode (Structured Output)

Request JSON responses for type-safe parsing:

async function generateJSON<T>(prompt: string, model: string): Promise<T> {
  const result = await genAI.models.generateContent({
    model,
    contents: [{ role: 'user', parts: [{ text: prompt }] }],
    config: {
      responseMimeType: 'application/json',
    },
  });
  return JSON.parse(result.text ?? '') as T;
}

With JSON Schema (Zod)

For strict schema validation:

import { z } from 'zod';

const CorrectionSchema = z.object({
  correction: z.string(),
  feedback: z.string(),
});

const result = await genAI.models.generateContent({
  model: 'gemini-3-flash-preview',
  contents: prompt,
  config: {
    responseMimeType: 'application/json',
    responseSchema: CorrectionSchema,
  },
});

Configuration Options

const response = await genAI.models.generateContent({
  model: 'gemini-3-flash-preview',
  contents: prompt,
  config: {
    temperature: 1.0,              // Randomness (keep at 1.0 for Gemini 3)
    topP: 0.95,                    // Nucleus sampling
    topK: 40,                      // Top-k sampling
    maxOutputTokens: 8192,         // Limit response length
    stopSequences: ['END'],        // Stop generation triggers
    systemInstruction: '...',      // System prompt
    responseMimeType: 'application/json',  // Force JSON output
  },
});

Temperature Warning

For Gemini 3 models, keep temperature at 1.0 (the default). Lowering it can cause:

• Response looping
• Degraded performance on complex tasks
• Unexpected behavior in reasoning

Error Handling Pattern

async function generateText(prompt: string, model: string): Promise<string> {
  try {
    const response = await genAI.models.generateContent({
      model,
      contents: prompt,
    });
    if (!response) {
      throw new Error('No response from Gemini');
    }
    return response.text ?? '';
  } catch (error) {
    console.error('Error generating text:', error);
    return '';
  }
}

Multi-Turn Chat

Maintain conversation history:

async function chat(
  systemPrompt: string,
  messages: Array<{ role: 'user' | 'model'; text: string }>,
  model: string
): Promise<string> {
  const contents = messages.map((msg) => ({
    role: msg.role,
    parts: [{ text: msg.text }],
  }));

  const result = await genAI.models.generateContent({
    model,
    contents,
    config: {
      systemInstruction: systemPrompt,
    },
  });
  return result.text ?? '';
}

Best Practices

1. Always handle null/undefined: Use response.text?? '' for safe access
2. Type your JSON responses: Use generics with JSON.parse() result
3. Use system instructions: Define persona and behavior expectations
4. Keep Gemini 3 temperature at 1.0: Avoid performance degradation
5. Validate JSON output: Structured format doesn't guarantee semantic correctness
6. Choose appropriate model: Use Flash for speed, Pro for complex reasoning

Common Mistakes to Avoid

• Don't lower temperature below 1.0 for Gemini 3 models
• Don't assume JSON responses are semantically valid - always validate
• Don't forget to handle the case where response.text is undefined
• Don't use raw string concatenation for multi-turn - use proper contents array