API Core

Referencia completa de la API Core de Gemini CLI y guía de uso

Referencia API30 min de lectura

Módulos API

Módulos y métodos API principales

GeminiClient

Clase cliente API Gemini principal

src/core/gemini.ts

constructor

constructor(config: GeminiConfig)

Crear instancia de cliente Gemini

Parámetros:
configGeminiConfig

Objeto de configuración del cliente

Ejemplo:
const client = new GeminiClient({
  apiKey: process.env.GEMINI_API_KEY,
  model: 'gemini-pro',
  temperature: 0.7
})

chat

async chat(message: string, context?: Context): Promise<ChatResponse>

Enviar mensaje de chat y obtener respuesta

Parámetros:
messagestring

Mensaje de entrada del usuario

contextContext

Información de contexto opcional

Retorna:
Promise<ChatResponse>

Objeto de respuesta de chat

Ejemplo:
const response = await client.chat('Hello, Gemini!', {
  files: ['src/index.ts'],
  history: previousMessages
})

stream

async stream(message: string, context?: Context): AsyncGenerator<string>

Respuesta de chat en streaming

Parámetros:
messagestring

Mensaje de entrada del usuario

contextContext

Información de contexto opcional

Retorna:
AsyncGenerator<string>

Generador de respuesta en streaming

Ejemplo:
for await (const chunk of client.stream('Explain this code')) {
  process.stdout.write(chunk)
}

SessionManager

Gestor de estado de sesión

src/core/session.ts

createSession

createSession(id?: string): Session

Crear nueva sesión

Parámetros:
idstring

ID de sesión opcional

Retorna:
Session

Objeto de sesión recién creado

Ejemplo:
const session = sessionManager.createSession('my-session')

getSession

getSession(id: string): Session | null

Obtener sesión especificada

Parámetros:
idstring

ID de sesión

Retorna:
Session | null

Objeto de sesión o null

Ejemplo:
const session = sessionManager.getSession('my-session')

saveSession

async saveSession(session: Session): Promise<void>

Guardar sesión en almacenamiento persistente

Parámetros:
sessionSession

Objeto de sesión a guardar

Ejemplo:
await sessionManager.saveSession(session)

ContextManager

Gestor de procesamiento de contexto

src/core/context.ts

addFile

async addFile(filePath: string): Promise<void>

Agregar archivo al contexto

Parámetros:
filePathstring

Ruta del archivo

Ejemplo:
await contextManager.addFile('src/utils/helper.ts')

addDirectory

async addDirectory(dirPath: string, options?: DirOptions): Promise<void>

Agregar directorio al contexto

Parámetros:
dirPathstring

Ruta del directorio

optionsDirOptions

Opciones de escaneo de directorio

Ejemplo:
await contextManager.addDirectory('src/', {
  exclude: ['*.test.ts'],
  maxDepth: 3
})

getContext

getContext(): Context

Obtener contexto actual

Retorna:
Context

Objeto de contexto actual

Ejemplo:
const context = contextManager.getContext()

Definiciones de Tipos

Definiciones de tipos TypeScript para la API Core

GeminiConfig

Interfaz de configuración del cliente Gemini

apiKeystring
requerido

Clave API de Google AI

modelstring

Nombre del modelo a usar, por defecto "gemini-pro"

temperaturenumber

Temperatura de generación, entre 0-1

maxTokensnumber

Número máximo de tokens

timeoutnumber

Tiempo de espera de solicitud en milisegundos

ChatResponse

Interfaz de respuesta de chat

contentstring
requerido

Contenido de respuesta

usageTokenUsage
requerido

Información de uso de tokens

modelstring
requerido

Modelo utilizado

finishReasonstring

Razón de finalización

Context

Interfaz de información de contexto

filesFileContext[]

Lista de contexto de archivos

historyMessage[]

Historial de mensajes

metadataRecord<string, any>

Metadatos

Session

Interfaz de sesión

idstring
requerido

Identificador único de sesión

messagesMessage[]
requerido

Historial de mensajes

contextContext

Contexto de sesión

createdAtDate
requerido

Tiempo de creación

updatedAtDate
requerido

Tiempo de actualización

Ejemplos de Uso

Escenarios comunes de uso de API y ejemplos de código

Chat Básico

Ejemplo de interacción de chat simple

import { GeminiClient } from '@gemini/core'

const client = new GeminiClient({
  apiKey: process.env.GEMINI_API_KEY,
  model: 'gemini-pro'
})

async function basicChat() {
  try {
    const response = await client.chat('Hello, how are you?')
    console.log('AI:', response.content)
  } catch (error) {
    console.error('Chat error:', error.message)
  }
}

Contexto de Archivo

Chat con contexto de archivo incluido

import { GeminiClient, ContextManager } from '@gemini/core'

const client = new GeminiClient({ apiKey: process.env.GEMINI_API_KEY })
const contextManager = new ContextManager()

async function chatWithFiles() {
  // Add files to context
  await contextManager.addFile('src/utils/helper.ts')
  await contextManager.addDirectory('src/components/')

  const context = contextManager.getContext()

  const response = await client.chat(
    'Explain the helper functions in this codebase',
    context
  )

  console.log(response.content)
}

Gestión de Sesión

Gestión de sesiones persistentes

import { SessionManager } from '@gemini/core'

const sessionManager = new SessionManager()

async function manageSessions() {
  // Create new session
  const session = sessionManager.createSession('project-review')

  // Add messages to session
  session.messages.push({
    role: 'user',
    content: 'Review this code for best practices'
  })

  // Save session
  await sessionManager.saveSession(session)

  // Restore session later
  const restored = sessionManager.getSession('project-review')
  console.log('Session messages:', restored?.messages.length)
}

Respuesta en Streaming

Salida de streaming en tiempo real

import { GeminiClient } from '@gemini/core'

const client = new GeminiClient({ apiKey: process.env.GEMINI_API_KEY })

async function streamingChat() {
  console.log('AI: ')

  for await (const chunk of client.stream('Write a short story')) {
    process.stdout.write(chunk)
  }

  console.log('\n\nStream completed!')
}

Manejo de Errores

Tipos de errores de API y métodos de manejo

AuthenticationError

Clave API inválida o expirada

GEMINI_AUTH_ERROR

Solución:

Verifique si la clave API está configurada correctamente, asegúrese de que la clave sea válida y no haya expirado

RateLimitError

La frecuencia de solicitudes excede los límites

GEMINI_RATE_LIMIT

Solución:

Implemente un mecanismo de reintento con backoff exponencial, o actualice a un plan de cuota superior

ContextTooLargeError

El contenido del contexto excede los límites del modelo

GEMINI_CONTEXT_TOO_LARGE

Solución:

Reduzca el número de archivos de contexto o use la función de resumen de archivos

NetworkError

Problemas de conexión de red

GEMINI_NETWORK_ERROR

Solución:

Verifique la conexión de red, configure los ajustes de proxy o aumente el tiempo de espera

Próximos Pasos

Continúa tu viaje de desarrollo con estos recursos

Configuración de DesarrolloEstructura del ProyectoVolver a la Documentación