Si estás construyendo aplicaciones web modernas en JavaScript, es casi seguro que tarde o temprano te tocará conectar tu proyecto con una API de Inteligencia Artificial como OpenAI, Claude o Gemini. Ya sea para armar un chatbot de atención al cliente, generar descripciones de productos o resumir textos, la integración de Inteligencia Artificial se ha vuelto una habilidad muy cotizada.

Sin embargo, al dar tus primeros pasos consumiendo estas APIs, aparece un término que al principio suena confuso y que se cobra en tu tarjeta de crédito: los tokens. Te aparecen en los errores de las peticiones (context_length_exceeded), en las tablas de precios y en la documentación técnica.

En este artículo vamos a desmitificar qué son los tokens, por qué a ti como desarrollador web te debe importar este concepto y cómo puedes gestionarlos con JavaScript para evitar sorpresas desagradables en la factura.

¿Qué carajos es un Token en Inteligencia Artificial?

Para entender qué es un token, imagina que los modelos de lenguaje (LLMs) no leen el texto como lo hacemos los humanos (palabra por palabra), ni tampoco ven simples caracteres individuales. En lugar de eso, dividen el texto en pequeñas piezas llamadas tokens.

Un token puede ser:

  • Una palabra completa (en palabras cortas como “sol” o “code”).
  • Una parte de una palabra (como “des-a-rro-lla-dor”).
  • Un solo carácter o espacio en blanco.
  • Un símbolo o signo de puntuación.

Como regla general en idioma inglés, 1 token equivale aproximadamente a 4 caracteres o 0.75 palabras. Sin embargo, en español la historia cambia un poco.

El “impuesto” del idioma español

Dado que la mayoría de los modelos fueron entrenados principalmente con texto en inglés, el tokenizador está optimizado para ese idioma. Cuando procesa texto en español, tiende a romper las palabras en más pedazos debido a los acentos, la morfología y las conjugaciones.

Por ejemplo:

  • En inglés: "Developer" $\rightarrow$ 1 token (Developer)
  • En español: "Desarrollador" $\rightarrow$ 3 tokens (Des, arroll, ador)

Esto significa que una misma consulta redactada en español puede consumir entre un 20% y 50% más tokens que su versión en inglés. ¡Ojo ahí con tu presupuesto!

¿Por qué deben importarte los Tokens como desarrollador JavaScript?

Existen tres razones fundamentales por las cuales debes dominar el manejo de tokens en tu código:

  1. Costo de operación: Las empresas de IA no te cobran por segundo de uso ni por número de peticiones HTTP, sino por la cantidad de tokens que procesan (tokens de entrada / input) y los que generan (tokens de salida / output).
  2. Límites de contexto (Context Window): Cada modelo tiene un límite máximo de tokens que puede recordar en una sola sesión (por ejemplo, 8,192 tokens o 128,000 tokens). Si te pasas, tu backend lanzará un error 400.
  3. Latencia y velocidad: Entre más tokens de salida tenga que generar la IA, más tiempo tardará en responderle a tu usuario final en la interfaz web.

Paso a paso: Contando y gestionando tokens en JavaScript

Para evitar exceder los límites o calcular el costo aproximado de una petición antes de enviarla a la API, podemos usar librerías de tokenización directamente en Node.js o en el navegador.

Una de las librerías más populares para proyectos con el ecosistema de OpenAI es @dqbd/tiktoken (o js-tiktoken).

Paso 1: Instalación de la dependencia

Si estás trabajando en un proyecto de Node.js, abre tu terminal y ejecuta:

npm install js-tiktoken

Paso 2: Crear una función para medir tokens

Vamos a crear un módulo simple que tome un texto de entrada y nos diga cuántos tokens consumirá antes de realizar la petición HTTP a la IA.

// tokenCounter.js
import { encodingForModel } from "js-tiktoken";

/**
 * Función que calcula cuántos tokens ocupa un texto para un modelo específico.
 * @param {string} text - El texto a analizar.
 * @param {string} modelName - Nombre del modelo (ej. 'gpt-4o', 'gpt-3.5-turbo').
 * @returns {number} Número total de tokens.
 */
export function contarTokens(text, modelName = "gpt-3.5-turbo") {
  try {
    // Obtenemos el codificador adecuado para el modelo
    const encoder = encodingForModel(modelName);
    
    // Convertimos el texto en una lista de IDs de tokens
    const tokens = encoder.encode(text);
    
    // Es importante liberar la memoria si usas tiktoken intensivamente
    encoder.free();
    
    return tokens.length;
  } catch (error) {
    console.error("Error al contar los tokens:", error);
    // Si falla, hacemos un cálculo aproximado de respaldo (1 token ≈ 3.5 caracteres en ES)
    return Math.ceil(text.length / 3.5);
  }
}

// Ejemplo de uso
const mensajeUsuario = "¡Hola 8devmx! ¿Cómo puedo optimizar mis peticiones de JavaScript a la API de OpenAI?";
const totalTokens = contarTokens(mensajeUsuario);

console.log(`El mensaje tiene ${mensajeUsuario.length} caracteres.`);
console.log(`Consumo estimado: ${totalTokens} tokens.`);

Integración real: Validar el límite antes de enviar la petición

Imagina que tienes un formulario web donde tus usuarios pegan un artículo largo para resumir. Si el usuario pega un texto de 50,000 palabras, tu servidor colapsará si el modelo no soporta tanto contexto.

Aquí tienes un ejemplo práctico usando fetch en Node.js para validar la longitud:

import { contarTokens } from "./tokenCounter.js";

const MAX_TOKENS_PERMITIDOS = 2000;

async function resumirTexto(promptUsuario) {
  const tokensPrompt = contarTokens(promptUsuario);

  // Validación previa en tu servidor
  if (tokensPrompt > MAX_TOKENS_PERMITIDOS) {
    throw new Error(`Tu texto es muy largo (${tokensPrompt} tokens). El máximo permitido es ${MAX_TOKENS_PERMITIDOS}.`);
  }

  console.log("Enviando petición a la API...");
  
  const response = await fetch("https://api.openai.com/v1/chat/completions", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "Authorization": `Bearer ${process.env.OPENAI_API_KEY}`
    },
    body: JSON.stringify({
      model: "gpt-3.5-turbo",
      messages: [
        { role: "system", content: "Eres un asistente útil que resume textos en español mexicanizado." },
        { role: "user", content: promptUsuario }
      ],
      max_tokens: 300 // Limitamos la respuesta de la IA
    })
  });

  const data = await response.json();
  return data.choices[0].message.content;
}

Errores comunes al trabajar con Tokens

  1. Asumir que 1 palabra = 1 token: Es el error clásico de principiante. Pensar que 500 palabras son 500 tokens provocará que te quedes corto en tus presupuestos o sobrepases los límites de contexto.
  2. Olvidar los tokens del system prompt: Cuando usas la API de Chat, el mensaje de configuración del sistema (system) también consume tokens en cada llamada. Si tu prompt del sistema mide 1,000 tokens, los pagarás en cada petición de cada usuario.
  3. No controlar el parámetro max_tokens: Si no defines cuántos tokens de salida le permites generar al modelo, una respuesta infinita o en bucle podría gastarte tus créditos en minutos.
  4. No considerar la puntuación y el código: El código fuente (JSON, HTML, JS) contiene llaves {}, comillas "", punto y coma ; y espacios que generan muchos más tokens por línea que el texto plano.

Buenas prácticas para desarrolladores Web

  • Limita los prompts de entrada: Recorta el historial de chat anterior (chat history). En lugar de enviar los últimos 50 mensajes de una conversación, envía solo los últimos 4 o 5.
  • Trunca texto dinámicamente: Si el usuario ingresa más contenido de la cuenta, corta el texto al token máximo permitido antes de llamar a la API.
  • Usa modelos adecuados: Para tareas sencillas (como clasificar un correo o traducir una palabra), usa modelos más pequeños y económicos (como GPT-3.5 o Claude Haiku) en lugar de modelos pesados como GPT-4o o Claude Opus.
  • Aprovecha el almacenamiento en caché: Si varios usuarios hacen la misma pregunta, guarda la respuesta en MySQL o Redis en lugar de volver a pedirle a la IA que consuma tokens.

Ejercicio práctico

Reto: Escribe una función en JavaScript llamada calcularCostoAproximado que reciba el número de caracteres de un texto y devuelva el costo estimado en dólares.

Datos para el ejercicio:

  • Supón que 1 token = 3.8 caracteres en español.
  • El precio del modelo es de $0.0015 USD por cada 1,000 tokens de entrada.

Solución sugerida:

function calcularCostoAproximado(caracteres) {
  const ESTIMACION_TOKENS_ESPANOL = 3.8;
  const PRECIO_POR_1000_TOKENS = 0.0015;

  const totalTokens = Math.ceil(caracteres / ESTIMACION_TOKENS_ESPANOL);
  const costoTotal = (totalTokens / 1000) * PRECIO_POR_1000_TOKENS;

  return {
    tokensEstimados: totalTokens,
    costoUSD: costoTotal.toFixed(6)
  };
}

// Prueba tu solución
console.log(calcularCostoAproximado(15000)); 
// Resultado esperado: ~3948 tokens, Costo: ~$0.005922 USD

Fuente original e inspiración

Este contenido fue adaptado e inspirado conceptualmente en el artículo en inglés “What Are AI Tokens and Why Should Developers Care?” publicado por Anoop Kumar en DEV Community.