Sebastian Gomez

Feb 26, 2022

Updated: Jun 24, 2026

Implementando Google Cloud Vision en Node.js

Siguiendo con la temática de la Cloud Vision de Google, en este post vamos a implementarla en Node.js para detectar características sobre imágenes.

Lo primero que necesitamos entender es que el SDK de la Cloud Vision de Google debería operar sobre un servidor, y es allí donde surge la necesidad de usar Node.js. Si tienes algo de experiencia con Node.js, sabrás que en la mayoría de los casos se requiere de una librería para procesar las peticiones HTTP POST, GET y PUT. En este post usaremos Express, ya que es la librería más conocida para esta tarea. Si tienes dudas sobre las generalidades de la Cloud Vision de Google o sobre la capa gratuita, puedes revisarlas en el post introductorio de esta serie.

Nota: este post está actualizado a 2026. El SDK @google-cloud/vision va hoy por la v5.x y la forma de inicializar el cliente cambió respecto a las primeras versiones; abajo verás el patrón vigente.

En primer lugar vamos a revisar las características que nos ofrece la API de visión de Google para implementar con Node.js:

• Detección de rostros.
• Atributos de las imágenes.
• Anotación de etiquetas.
• Detección de contenido para adultos.
• Detección de logos.
• Encuadre de los elementos de la imagen.
• Reconocimiento óptico de caracteres.

La arquitectura

Revisemos las responsabilidades que tendría cada uno de los componentes de la arquitectura.

Client Browser:

• Presentar información.
• Tomar fotografías o videos.
• Preprocesar imágenes.
• Enviar las imágenes al servidor.

Express:

• Filtrar las peticiones del cliente.
• Recibir las imágenes y almacenarlas en el servidor.
• Enviar las respuestas al cliente.

*Google Vision SDK ():**

• Procesar las imágenes.
• Operaciones matemáticas.
• Detección de píxeles.
• Filtros.
• Transformaciones.
• Codificación de las imágenes.
• Preparación de las peticiones.

Google Vision API:

• Comparar las imágenes contra el conjunto de imágenes.
• Aplicar rutinas de machine learning con las imágenes como entrada.
• Conectarse con otras tecnologías como TensorFlow.
• Analizar los resultados y aumentar la base de conocimiento.

(*) Un SDK (Software Development Kit), o kit de desarrollo de software, es un conjunto de herramientas que ayudan a la programación de aplicaciones para un entorno tecnológico particular.

Obtener las credenciales

Antes de empezar necesitamos obtener una clave y las credenciales del proyecto para hacer uso de la API y del SDK. Esto lo podemos conseguir directamente en la consola: https://cloud.google.com/, siguiendo estos simples pasos:

1. Crear el proyecto en https://console.cloud.google.com/projectcreate.
2. Acceder al proyecto.
3. Seleccionar cuentas de servicio.
4. Crear una cuenta de servicio y completar la información.
5. Seleccionar suministrar una nueva clave privada en formato JSON.
6. Guardar el archivo JSON que se genera.

Nota sobre autenticación: descargar una clave JSON de cuenta de servicio sigue funcionando en 2026, y es el camino más simple para aprender. Sin embargo, Google hoy recomienda usar Application Default Credentials (ADC) o Workload Identity, y desaconseja descargar claves JSON de larga duración. Si despliegas en producción, considera ADC en lugar de un archivo de credenciales en disco.

Manos a la obra

Empecemos creando un proyecto en Node desde cero usando la línea de comandos.

# Crear un directorio
mkdir mi-directorio

# Inicializar git
git init

# Inicializar node
npm init

# Instalar las dependencias
npm install @google-cloud/vision
npm install express
npm install multer

Configuramos nuestro comando npm start en el package.json para que inicie nuestro servidor:

{
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1",
    "start": "node server.js"
  }
}

Esto nos creará la estructura base del proyecto y deberás añadir además algunos archivos. Los únicos archivos sobre los cuales escribiremos código son server.js, index.html y app.js.

¿Cómo tomar fotos con JavaScript?

Empecemos con una funcionalidad básica: tomar fotos desde la cámara del navegador. Puedes ver el ejemplo completo en este CodePen:

https://codepen.io/seagomezar/pen/QayorL

Como verás, simplemente creando un stream con getUserMedia y accediendo a los elementos del DOM es posible obtener la más sencilla funcionalidad de tomar imágenes desde la cámara de tu ordenador y pintarlas dentro de la etiqueta img.

Subir la imagen al servidor

Ahora veremos cómo subir la imagen que tomamos a nuestro servidor. Una vez que tomamos la imagen y la pintamos dentro del atributo src, necesitamos hacer una petición HTTP al servidor indicándole que allí va la imagen. Para esto abre tu archivo app.js y añade la función upload:

function upload() {
  const http = new XMLHttpRequest();
  const url = "upload";
  snap().then((blob) => {
    http.open("POST", url, true);
    http.setRequestHeader("X-Requested-With", "XMLHttpRequest");
    http.onreadystatechange = (data) => {
      // Llamamos a una función cuando cambie el estado.
      if (http.readyState == 4 && http.status == 200) {
        console.log(http.response);
      }
    };
    const formData = new FormData();
    formData.append("uploads", blob);
    http.send(formData);
  });
}

Como verás, en esta función invocamos a la función snap() que definimos para capturar imágenes desde la cámara del navegador, y enviamos el contenido de la imagen mediante una XMLHttpRequest. Luego necesitamos crear nuestro servidor para que sea capaz de recibir y procesar dicha imagen.

Nota: en 2026 lo idiomático sería usar fetch en lugar de XMLHttpRequest, pero dejamos el XMLHttpRequest para que el ejemplo siga siendo fácil de seguir. Es un buen ejercicio reescribirlo con fetch.

Es en este punto donde necesitamos crear y configurar un servidor básico con Express que soporte la opción de subir la imagen. Por tanto tu archivo server.js debe lucir así, en su parte inicial, con la función upload que procesará la imagen y la guardará en la carpeta uploads. Cada imagen se guarda con un número consecutivo relacionado con el momento actual, para evitar duplicidades.

const express = require("express");
const multer = require("multer");

const app = express();

// Guardamos cada archivo con un nombre único basado en el timestamp.
const storage = multer.diskStorage({
  destination: "uploads/",
  filename: (req, file, cb) => cb(null, `${Date.now()}-${file.originalname}`),
});

const upload = multer({ storage });

app.use(express.static("public"));

app.listen(3000, () => console.log("Server escuchando en el puerto 3000"));

Detectar características con Cloud Vision

Hasta este momento solo hemos creado funciones utilitarias en server.js para inicializar el servidor y para subir archivos, pero no hemos realizado ningún proceso sobre la imagen. Ahora vamos a aprender cómo detectar características sobre la imagen usando el SDK de Cloud Vision.

Primero inicializamos el cliente de Cloud Vision. Ten en cuenta el cambio clave respecto a versiones antiguas: el paquete ya no se invoca como una función (require('@google-cloud/vision')({...})), sino que exporta clases. Creamos una instancia de ImageAnnotatorClient:

const vision = require("@google-cloud/vision");

// Desde la v1.0 el paquete exporta clases, no un factory invocable.
// El projectId se infiere del archivo de credenciales, no hace falta declararlo.
const client = new vision.ImageAnnotatorClient({
  keyFilename: "./cloud-credentials.json",
});

Luego creamos con Express un endpoint que se encarga de recibir una imagen y obtener todas las etiquetas (labels) que se pueden extraer de dicha imagen, para retornarlas como respuesta de la petición y presentarlas en el frontend.

app.post("/labels", upload.single("uploads"), function (req, res) {
  // Para un archivo local basta con pasar la ruta. source.filename
  // es para URIs de Cloud Storage (gs://...), no para disco local.
  const currentFile = req.file.path;
  client
    .labelDetection(currentFile)
    .then((results) => {
      const labels = results[0].labelAnnotations;
      console.log("Labels:");
      labels.forEach((label) => console.log(label.description));
      res.send(labels);
    })
    .catch((err) => {
      console.error("ERROR:", err);
      res.send("BAD");
    });
});

Nota: en el SDK actual (@google-cloud/vision, cliente ImageAnnotatorClient) client.labelDetection(currentFile) acepta una ruta de archivo local. Si prefieres ser explícito, usa { image: { content: fs.readFileSync(currentFile) } }.

Finalmente podemos usar otra característica que nos permite hallar los rostros en una imagen, con su respectiva traza y la posición de cada elemento del rostro:

app.post("/faces", upload.single("uploads"), (req, res) => {
  const currentFile = req.file.path;
  client
    .faceDetection(currentFile)
    .then((results) => {
      const faces = results[0].faceAnnotations;
      res.send(faces);
    })
    .catch((err) => {
      console.error("ERROR:", err);
      res.send("BAD");
    });
});

Mostrar los resultados en el frontend

Una vez que tenemos nuestro archivo server.js completo, debemos modificar un poco nuestro index.html y app.js para mostrar nuestros hallazgos:

<!-- index.html -->
<button class="shutter" onclick="upload()">
  Tomar y subir una foto
</button>
<button class="shutter" onclick="sendToLabelDetection()">
  Analizar imagen
</button>
<button class="shutter" onclick="sendToFaceDetection()">
  Detectar rostros y características
</button>

<div>
  <h2>Características de la imagen</h2>
  <div id="labels"></div>
</div>

Poniendo todo lo anterior junto podrás ver las características (labels) de la imagen en la detección de características. Para la detección y extracción de rostros se implementa solo el log por consola, donde podrás ver un elemento del array por cada rostro detectado, y dentro de cada rostro las landmarks que delimitan exactamente cada uno de los elementos del rostro.

Puedes jugar con estas funciones para crear combinaciones de características únicas para tu aplicación o producto. En este repositorio podrás jugar con el código y usarlo para implementar tus propias funcionalidades; también encontrarás otras funciones, como por ejemplo detectar personas felices o tristes en una foto:

https://github.com/seagomezar/devfest vision

Nota: el código de ejemplo vive en el repositorio público seagomezar/devfest-vision y usa el cliente ImageAnnotatorClient de @google-cloud/vision.

Para consultar más información sobre las operaciones del SDK y de la API de Cloud Vision para Node.js, puedes ver el repositorio oficial de ejemplos:

https://github.com/googleapis/nodejs vision/tree/main/samples

Ejercicios propuestos

1. Reescribe la función upload del cliente usando fetch en lugar de XMLHttpRequest.
2. Añade un nuevo endpoint que use textDetection (OCR) para extraer texto de una imagen.
3. Cambia la autenticación por archivo JSON por Application Default Credentials y despliega el servidor en un entorno de Google Cloud.

Resumen en 3 puntos

1. El SDK de Cloud Vision corre en el servidor; con Express recibimos la imagen y con multer la guardamos antes de analizarla.
2. El cliente se inicializa con new vision.ImageAnnotatorClient(...); para archivos locales se pasa la ruta o un buffer, no source.filename.
3. Con labelDetection y faceDetection obtenemos etiquetas y rostros, y los devolvemos al frontend para mostrarlos.

Eso es todo, espero que este post te sea de utilidad y lo puedas aplicar a algún proyecto que tengas en mente. Déjame un comentario si lograste implementarlo, si quieres añadir alguna otra funcionalidad o si tienes alguna duda. Recuerda que si te gustó, también puedes compartirlo usando los links a las redes sociales aquí abajo.