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.

Cómo crear o ver una clave de API de Gemini

Claves de API

Puedes crear y administrar todas tus claves de 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:

• Establecer tu clave de API como una variable de entorno
• Proporcionar tu clave de API de forma explícita

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 Proporciona 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 permisos suficientes para usar la API de Gemini. Consulta la sección Importar proyectos para obtener instrucciones.

Proyecto predeterminado

Para los usuarios nuevos, después de aceptar las Condiciones del Servicio, Google AI Studio crea un proyecto de Google Cloud y una clave de API predeterminados para facilitar el uso. Para cambiar el nombre de este proyecto en Google AI Studio, navega a la vista Proyectos en el Panel, haz clic en el botón de configuración de 3 puntos junto a un proyecto y elige Cambiar nombre del proyecto. Los usuarios existentes o los que ya tienen cuentas de Google Cloud no tendrán un proyecto predeterminado creado.

Importar proyectos

Cada clave de API de Gemini está asociada a un proyecto de Google Cloud. De forma predeterminada, Google AI Studio no muestra todos tus proyectos de Cloud. Debes importar los proyectos que desees buscando el nombre o el ID del proyecto en el diálogo Importar proyectos. 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 Importar proyectos en la página Proyectos.
5. Busca y selecciona el proyecto de Google Cloud que deseas importar y 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

Las siguientes son 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 Proyectos de Google AI Studio.
• Puedes asignar nombres a proyectos y claves, y cambiarles el nombre.
• En las páginas Claves de API y Proyectos , se muestran un máximo de 100 claves y 50 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 de administración adicional a tus proyectos, lo que incluye modificar y restringir claves de API, visita la página de credenciales de la consola de Google Cloud. En Cloud Console, puedes seleccionar tu proyecto, hacer clic en una clave de API existente y, luego, restringirla a la API de Generative Language.

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

Si estableces la variable de entorno GEMINI_API_KEY o GOOGLE_API_KEY, la clave de API se recuperará automáticamente por el cliente cuando uses una de las bibliotecas de la API de Gemini. Te recomendamos que establezcas solo una de esas variables, pero, si se establecen 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.

~/.bashrc

touch ~/.bashrc
open ~/.bashrc

export GEMINI_API_KEY=<YOUR_API_KEY_HERE>

source ~/.bashrc

~/.zshrc

touch ~/.zshrc
open ~/.zshrc

export GEMINI_API_KEY=<YOUR_API_KEY_HERE>

source ~/.zshrc

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

En algunos casos, es posible que desees 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 un control explícito sin tener que depender de la detección automática de variables de entorno por parte de las bibliotecas de la API de Gemini.
• Usas un entorno en el que no se admiten variables de entorno (p. ej., la Web) o realizas llamadas a REST.

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

from google import genai

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

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

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

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

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

main();

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-3-flash-preview",
        genai.Text("Explain how AI works in a few words"),
        nil,
    )
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println(result.Text())
}

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-3-flash-preview",
            "Explain how AI works in a few words",
            null);

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

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3-flash-preview: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 vulnera, otras personas pueden usar la cuota de tu proyecto, generar cargos (si la facturación está habilitada) y acceder a tus datos privados, como archivos.

Reglas de seguridad críticas

• Mantén la confidencialidad de las claves: Las claves de API de Gemini pueden acceder a datos sensibles de los que depende tu aplicación.

  • Nunca confirmes las claves de API en el control de versiones. No registres tu clave de API en sistemas de control de versiones 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. Se pueden extraer claves en el código del cliente (incluidas nuestras bibliotecas de JavaScript/TypeScript y las llamadas a REST).

• Restringe el acceso: Cuando sea posible, restringe el uso de la clave de API a direcciones IP, URLs de referencia HTTP o apps para Android o iOS específicas.

• Restringe el uso: Habilita solo las APIs necesarias para cada clave.

• Realiza auditorías periódicas: Audita tus claves de API con regularidad y rótalas de forma periódica.

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 API en vivo): Para el acceso directo del cliente a la API en vivo, 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 la clave se filtra.

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

Solución de problemas de creación de claves de API

En Google AI Studio, es posible que el botón Crear clave de API no esté disponible y aparezca el mensaje: "No tienes permiso para crear una clave en este proyecto".

Esto ocurre cuando no tienes los permisos necesarios en el proyecto para generar una clave nueva:

• resourcemanager.projects.get: Permite que AI Studio verifique la existencia del proyecto.
• apikeys.keys.create: Permite la generación de la clave de API.
• serviceusage.services.enable: Es necesario para garantizar que la API de Gemini esté activa en el proyecto.

Para corregir tus permisos, pídele al administrador del proyecto o al administrador de tu organización (si el proyecto pertenece a una organización) que te otorgue un rol con los permisos mencionados anteriormente (como Editor del proyecto o un rol personalizado).

Si no tienes acceso administrativo a un proyecto, puedes crear uno nuevo que no esté asociado con una organización para generar tus claves.