Cómo usar claves de API de Gemini

Para usar la API de Gemini, necesitas una clave de API. En esta página, se describe cómo crear y administrar tus claves en Google AI Studio, así como configurar tu entorno para usarlas en tu código.

Claves de API

Una clave de API es una cadena encriptada que puedes usar cuando llamas a las APIs de Google Cloud. Puedes crear y administrar todas tus claves de la API de Gemini desde la página Claves de API de Google AI Studio.

Una vez que tengas una clave de API, tendrás las siguientes opciones para conectarte a la API de Gemini:

Para las pruebas iniciales, puedes codificar de forma rígida una clave de API, pero esto solo debe ser temporal, ya que no es seguro. Puedes encontrar ejemplos para codificar de forma rígida la clave de API en la sección Cómo proporcionar la clave de API de forma explícita.

Proyectos de Google Cloud

Los proyectos de Google Cloud son fundamentales para usar los servicios de Google Cloud (como la API de Gemini), administrar la facturación y controlar los colaboradores y los permisos. Google AI Studio proporciona una interfaz ligera para tus proyectos de Google Cloud.

Si aún no creaste ningún proyecto, debes crear uno nuevo o importar uno de Google Cloud a Google AI Studio. En la página Proyectos de Google AI Studio, se mostrarán todas las claves que tengan permiso suficiente para usar la API de Gemini. Consulta la sección Importa proyectos para obtener instrucciones.

Importa proyectos

Cada clave de la API de Gemini está asociada a un proyecto de Google Cloud. De forma predeterminada, Google AI Studio no muestra todos tus proyectos de Cloud. Para importar los proyectos que desees, busca el nombre o el ID del proyecto en el diálogo Import Projects. Para ver una lista completa de los proyectos a los que tienes acceso, visita Cloud Console.

Si aún no importaste ningún proyecto, sigue estos pasos para importar un proyecto de Google Cloud y crear una clave:

  1. Ve a Google AI Studio.
  2. Abre el Panel desde el panel lateral izquierdo.
  3. Selecciona Proyectos.
  4. Selecciona el botón Import projects en la página Projects.
  5. Busca y selecciona el proyecto de Google Cloud que deseas importar y, luego, selecciona el botón Importar.

Una vez que se importe un proyecto, ve a la página Claves de API desde el menú Panel y crea una clave de API en el proyecto que acabas de importar.

Limitaciones

A continuación, se indican las limitaciones de la administración de claves de API y proyectos de Google Cloud en Google AI Studio.

  • Puedes crear un máximo de 10 proyectos a la vez desde la página Projects de Google AI Studio.
  • Puedes asignar nombres a los proyectos y las claves, y cambiarlos.
  • En las páginas Claves de API y Proyectos, se muestran un máximo de 100 claves y 100 proyectos.
  • Solo se muestran las claves de API que no tienen restricciones o que están restringidas a la API de Generative Language.

Para obtener acceso administrativo adicional a tus proyectos, visita la consola de Google Cloud.

Cómo configurar la clave de API como una variable de entorno

Si configuras la variable de entorno GEMINI_API_KEY o GOOGLE_API_KEY, el cliente seleccionará automáticamente la clave de API cuando uses una de las bibliotecas de la API de Gemini. Te recomendamos que configures solo una de esas variables, pero, si configuras ambas, GOOGLE_API_KEY tiene prioridad.

Si usas la API de REST o JavaScript en el navegador, deberás proporcionar la clave de API de forma explícita.

A continuación, se explica cómo puedes establecer tu clave de API de forma local como la variable de entorno GEMINI_API_KEY con diferentes sistemas operativos.

Linux/macOS (Bash)

Bash es una configuración común de la terminal de Linux y macOS. Para verificar si tienes un archivo de configuración, ejecuta el siguiente comando:

~/.bashrc

Si la respuesta es "No existe ese archivo o directorio", deberás crear este archivo y abrirlo ejecutando los siguientes comandos o usar zsh:

touch ~/.bashrc
open ~/.bashrc

A continuación, debes establecer tu clave de API agregando el siguiente comando de exportación:

export GEMINI_API_KEY=<YOUR_API_KEY_HERE>

Después de guardar el archivo, aplica los cambios ejecutando el siguiente comando:

source ~/.bashrc

macOS - Zsh

Zsh es una configuración común de terminales de Linux y macOS. Para verificar si tienes un archivo de configuración, ejecuta el siguiente comando:

~/.zshrc

Si la respuesta es "No existe ese archivo o directorio", deberás crear este archivo y abrirlo ejecutando los siguientes comandos o usar bash:

touch ~/.zshrc
open ~/.zshrc

A continuación, debes establecer tu clave de API agregando el siguiente comando de exportación:

export GEMINI_API_KEY=<YOUR_API_KEY_HERE>

Después de guardar el archivo, aplica los cambios ejecutando el siguiente comando:

source ~/.zshrc

Windows

  1. Busca "Variables de entorno" en la barra de búsqueda.
  2. Elige modificar la Configuración del sistema. Es posible que debas confirmar que deseas hacerlo.
  3. En el diálogo de configuración del sistema, haz clic en el botón etiquetado como Variables de entorno.
  4. En User variables (para el usuario actual) o System variables (se aplica a todos los usuarios que usan la máquina), haz clic en New….
  5. Especifica el nombre de la variable como GEMINI_API_KEY. Especifica tu clave de API de Gemini como el valor de la variable.
  6. Haz clic en Aceptar para aplicar los cambios.
  7. Abre una sesión de terminal nueva (cmd o PowerShell) para obtener la variable nueva.

Cómo proporcionar la clave de API de forma explícita

En algunos casos, es posible que quieras proporcionar una clave de API de forma explícita. Por ejemplo:

  • Estás realizando una llamada a la API simple y prefieres codificar de forma rígida la clave de API.
  • Quieres tener un control explícito sin tener que depender del descubrimiento automático de las variables de entorno por parte de las bibliotecas de la API de Gemini.
  • Estás usando un entorno en el que no se admiten variables de entorno (p. ej., la Web) o estás realizando llamadas a la API de REST.

A continuación, se incluyen ejemplos de cómo puedes proporcionar una clave de API de forma explícita:

Python

from google import genai

client = genai.Client(api_key="YOUR_API_KEY")

response = client.models.generate_content(
    model="gemini-2.5-flash", contents="Explain how AI works in a few words"
)
print(response.text)

JavaScript

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

const ai = new GoogleGenAI({ apiKey: "YOUR_API_KEY" });

async function main() {
  const response = await ai.models.generateContent({
    model: "gemini-2.5-flash",
    contents: "Explain how AI works in a few words",
  });
  console.log(response.text);
}

main();

Go

package main

import (
    "context"
    "fmt"
    "log"
    "google.golang.org/genai"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, &genai.ClientConfig{
        APIKey:  "YOUR_API_KEY",
        Backend: genai.BackendGeminiAPI,
    })
    if err != nil {
        log.Fatal(err)
    }

    result, err := client.Models.GenerateContent(
        ctx,
        "gemini-2.5-flash",
        genai.Text("Explain how AI works in a few words"),
        nil,
    )
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println(result.Text())
}

Java

package com.example;

import com.google.genai.Client;
import com.google.genai.types.GenerateContentResponse;

public class GenerateTextFromTextInput {
  public static void main(String[] args) {
    Client client = Client.builder().apiKey("YOUR_API_KEY").build();

    GenerateContentResponse response =
        client.models.generateContent(
            "gemini-2.5-flash",
            "Explain how AI works in a few words",
            null);

    System.out.println(response.text());
  }
}

REST

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

Protege tu clave de API

Trata tu clave de API de Gemini como una contraseña. Si se ve comprometida, otras personas pueden usar la cuota de tu proyecto, incurrir en cargos (si la facturación está habilitada) y acceder a tus datos privados, como los archivos.

Reglas de seguridad críticas

  • Nunca confirmes las claves de API en el control de código fuente. No registres tu clave de API en sistemas de control de versión como Git.

  • Nunca expongas las claves de API en el cliente. No uses tu clave de API directamente en apps web o para dispositivos móviles en producción. Las claves en el código del cliente (incluidas nuestras bibliotecas de JavaScript/TypeScript y las llamadas a REST) se pueden extraer.

Prácticas recomendadas

  • Usa llamadas del servidor con claves de API. La forma más segura de usar tu clave de API es llamar a la API de Gemini desde una aplicación del servidor en la que la clave se pueda mantener confidencial.

  • Usa tokens efímeros para el acceso del cliente (solo para la API de Live): Para el acceso directo del cliente a la API de Live, puedes usar tokens efímeros. Tienen riesgos de seguridad más bajos y pueden ser adecuados para el uso en producción. Consulta la guía de tokens efímeros para obtener más información.

  • Considera agregar restricciones a tu clave: Puedes limitar los permisos de una clave agregando restricciones de clave de API. Esto minimiza el daño potencial si alguna vez se filtra la clave.

Para conocer algunas prácticas recomendadas generales, también puedes consultar este artículo de ayuda.