DOMINICODE

Tag: Claude API

  • Cómo Funciona el Watermarking de Claude a Nivel de API

    Cómo Funciona el Watermarking de Claude a Nivel de API

    La primera vez que alguien escucha que Claude mete una marca de agua en el texto que genera, se imagina un truco barato de esteganografía.

    Un espacio de ancho cero entre dos palabras. Un carácter Unicode invisible (\u200B). Un patrón binario escondido en los saltos de línea.

    Si fuera eso, un script de Python de dos líneas con un .replace('\u200b', '') o un regex básico destruiría la marca en tres milisegundos.

    Anthropic no ha implementado un truco de caracteres. Desde agosto de 2026, todos los modelos nuevos de Claude integran un watermarking a nivel de API de naturaleza puramente estadística. No hay caracteres ocultos, viaja en el texto plano al copiar y pegar, y no existe ningún parámetro o flag en la API para desactivarla.

    Si tu producto llama a la API de Claude, tus usuarios ya están recibiendo texto marcado, lo sepas o no. Aquí te explico el algoritmo que hay detrás, cómo se diferencia de los metadatos en archivos y qué implica de verdad si construyes sobre esa API — no como usuario ocasional de Claude Code, sino como quien tiene que responder por ello ante sus propios clientes.

    Cómo genera texto un LLM (el paso previo imprescindible)

    Para entender cómo se inserta una señal en un texto sin alterar una sola letra, primero hay que recordar qué hace el modelo en cada ciclo de inferencia.

    Un LLM no "elige una frase completa". Trabaja token a token. Cuando Claude va a generar la siguiente palabra, calcula una distribución de probabilidad sobre su vocabulario completo (los llamados logits, normalizados con una función softmax):

    software      → 28%
aplicaciones  → 21%
productos     → 17%
sistemas      → 14%
herramientas  → 11%
otros...      →  9%

    En un muestreo normal con cierta temperatura, el modelo elige uno de los tokens más probables. El texto resultante es fluido, coherente y suena natural.

    Aquí es exactamente donde entra el algoritmo de watermarking.

    El algoritmo de Kirchenbauer: listas verdes y sesgo de logits

    Anthropic no ha publicado el mecanismo exacto que usa Claude. Lo único que confirma oficialmente es el principio: la marca usa una clave y las palabras previas para decidir qué palabra elige el modelo entre varias opciones semánticamente equivalentes, sin tocar la calidad del texto. Cita como referencias el paper de Kirchenbauer et al. y SynthID-Text de Google DeepMind, así que lo más razonable —y lo que asume la mayoría del análisis externo— es que Claude use una variante de esa familia de técnicas. Lo que sigue es cómo funciona ese enfoque en general, no una confirmación línea por línea de la implementación interna de Anthropic.

    La técnica estándar en la industria para marcar texto en LLMs no toca el texto después de generarlo. Modifica la probabilidad antes de muestrear.

    El proceso sigue, a grandes rasgos, estos pasos:

    Token anterior (t-1) 
       │
       ▼
[ Hash + Clave Secreta de Anthropic ]
       │
       ▼
Partición pseudo-aleatoria del vocabulario
  ├── Lista Verde (Green List) ~ 50%
  └── Lista Roja (Red List)    ~ 50%
       │
       ▼
Se suma un delta (+δ) a los logits de la Lista Verde
       │
       ▼
Muestreo del siguiente token (favorece sutilmente el verde)
    1. Generación de semilla: Al momento de predecir el siguiente token, el sistema calcula un hash criptográfico del token anterior (o de una ventana de los últimos tokens) combinado con una clave secreta que solo posee Anthropic.
    2. Partición del vocabulario: Ese hash divide pseudo-aleatoriamente todo el diccionario de tokens en dos grupos: una Lista Verde y una Lista Roja, típicamente al 50% cada una.
    3. Sesgo de logits (Logit Biasing): A los logits de los tokens que caen en la Lista Verde se les suma un valor constante positivo.
    4. Muestreo: El modelo muestrea el siguiente token aplicando la distribución con los logits alterados.

    ¿Qué ve un humano vs. qué ve un detector?

    • Un humano lee el texto y no nota nada extraño. Como el sesgo es moderado, el modelo sigue seleccionando palabras de alta probabilidad semántica. El significado, el estilo y la calidad no cambian.
    • Un detector con la clave (hoy, solo Anthropic; han anunciado que van a liberar una API de detección pero todavía no está disponible públicamente) tomaría el texto generado, reconstruiría para cada palabra si pertenecía a la Lista Verde o a la Lista Roja, y contaría cuántos tokens verdes aparecen.

    En un texto escrito por un humano o por un modelo sin marca, la probabilidad de que un token caiga en la lista verde es de alrededor del 50% (puro azar).

    En un texto marcado con este tipo de técnica, esa proporción sube de forma sistemática por encima del azar. Anthropic no ha publicado la cifra exacta para Claude; en la literatura académica sobre KGW/SynthID-Text el desplazamiento suele ser notable con relativamente pocos tokens.

    Con un párrafo de varios cientos de palabras, la probabilidad de que esa acumulación de tokens verdes ocurra por puro azar cae drásticamente. Esa es la base estadística del método, aunque los números concretos que aplica Anthropic a Claude no son públicos.

    Por qué en código fuente la marca es mucho más débil

    Aquí hay un detalle técnico crítico que casi nadie en redes sociales ha mencionado: el watermarking estadístico necesita entropía.

    La entropía mide la cantidad de opciones válidas que tiene el modelo para continuar una frase.

    • En prosa libre (alta entropía): Para decir "construimos sistemas robustos", el modelo puede elegir entre sistemas, aplicaciones, plataformas, soluciones o arquitecturas. Tiene margen de sobra para elegir un token de la Lista Verde sin romper la frase.
    • En código de programación (baja entropía): Si estás escribiendo TypeScript y tienes for (const item of, el siguiente token sintácticamente válido es casi con total seguridad el identificador del array o una estructura iterable. Si fuerzas un token de la lista verde que no encaja sintácticamente, el código no compila.
    // En sintaxis estricta, el espacio de tokens válidos es minúsculo:
export interface UserSession {
  id: string;
  createdAt: Date;
}

    Si el modelo reduce la temperatura o la sintaxis impone un único token válido, el sesgo de la lista verde no puede aplicarse sin destruir la corrección del programa.

    Por eso, en archivos de código (.ts, .py, .rs) la marca estadística es inherentemente más débil o casi indetectable en fragmentos cortos, mientras que en documentación, emails o artículos es donde más fuerte se fija. Y precisamente porque no puedes apoyarte en el watermark para saber si un fragmento de código viene de un agente, la validación real sigue siendo la de siempre: TDD potenciado por IA, validar el código antes de mergear.

    Esta es la misma disciplina de control y contexto que enseñamos en el curso Construye con IA: De la Idea al Producto con Claude y Specs: cuando entiendes cómo procesan los modelos la probabilidad de los tokens, dejas de tratar a los agentes como cajas mágicas y empiezas a diseñar sistemas predecibles.

    Texto vs. Archivos: la diferencia entre Watermark y C2PA

    Existe una confusión generalizada entre la marca en el texto y la marca en archivos multimedia. Anthropic usa dos tecnologías completamente distintas según el tipo de output:

    Característica Marca de agua en Texto Metadatos en Archivos (.png, .svg)
    Mecanismo Sesgo estadístico en logits (Kirchenbauer / SynthID) Estándar C2PA (Content Authenticity Initiative)
    Dónde vive En la frecuencia y secuencia de las palabras En la cabecera / bloque de metadatos del archivo
    Copiar y pegar Sobrevive (es el texto mismo) No aplica (es un archivo binario)
    Edición / Conversión Se degrada progresivamente si reescribes Se pierde si re-guardas o conviertes el archivo
    Verificación hoy Privada (solo Anthropic tiene la clave) Pública y verificable hoy con c2patool

    Cómo inspeccionar C2PA en tus archivos hoy mismo

    Si generas diagramas SVG o imágenes con Claude y las sirves desde tu backend, puedes auditar los metadatos C2PA en tu propia máquina con la herramienta oficial de la Content Authenticity Initiative:

    # Instalación del cli oficial de C2PA
brew install c2patool
# O descargar el binario desde github.com/contentauth/c2pa-rs/releases

# Inspeccionar el manifiesto completo en JSON
c2patool imagen.png

# Ver solo el resumen de procedencia
c2patool imagen.png --info

    Si el archivo proviene directamente de Claude, el manifiesto C2PA mostrará la firma criptográfica de emisión. Si lo abres en Photoshop, lo recortas y lo guardas como WebP, el contenedor C2PA desaparece a menos que tu software lo re-firme.

    Detector de IA ≠ Detector de Watermark

    Esta distinción te va a ahorrar dolores de cabeza con clientes y product managers cuando te pidan "añadir detección de IA":

    1. Un detector de IA tradicional (heurístico): Analiza perplejidad y ráfagas (burstiness). Intenta adivinar si el estilo parece robótico. Es impreciso, produce falsos positivos atroces con no-nativos en inglés y no sirve como prueba legal.
    2. Un detector de marca de agua: No evalúa estilo ni perplejidad. Aplica una clave criptográfica sobre la secuencia de tokens y comprueba una hipótesis matemática de probabilidad binomial.

    Hoy por hoy, no existe un detector público de watermark para Claude. Si ves una web que afirma "Pega tu texto y te digo si tiene la marca de Claude", es un detector heurístico genérico, no un verificador del watermark de Anthropic.

    Además, publicar un detector abierto crea un problema de seguridad: actúa como un oráculo de optimización. Cualquier usuario podría pasar su texto por un script que altere palabras una a una hasta que el verificador dé negativo, destruyendo la marca con el mínimo esfuerzo.

    Qué significa el watermarking de Claude si construyes sobre la API

    Si integras Claude en tu SaaS o en pipelines de desarrollo interno —repasa lo básico en Claude API: Crash Course para developers con TypeScript si aún no la usas a diario— hay cuatro realidades que debes asumir:

    1. No hay opt-out: No existe un header x-anthropic-disable-watermark: true. La directiva de la Unión Europea (EU AI Act, artículo 50) exige que los proveedores marquen las salidas de IA generativa.
    2. La marca demuestra procesamiento, no autoría única: Si un humano escribe un borrador y le pide a Claude que corrija la puntuación, el texto resultante puede quedar marcado. Anthropic lo aclara en su documentación: la marca indica que el texto pasó por el modelo, no que el humano no intervino.
    3. No prometas a tus clientes outputs "indetectables": Cualquier modelo de negocio basado en vender "artículos indetectables para SEO" o "ensayos indetectables" está técnicamente muerto a medio plazo frente a esquemas de marca estadística.
    4. La paráfrasis profunda degrada la señal: Anthropic mismo lo advierte: una edición ligera probablemente no elimina la marca, pero reescribir el texto a fondo —traducirlo, reordenarlo intensamente o editarlo a mano de forma sustancial— sí la destruye, porque rompe la alineación entre los tokens y la clave con la que se generaron.

    Para patrones avanzados de integración con LLMs y arquitecturas robustas en producción, en Dominicode Labs analizamos continuamente los cambios de la API de Anthropic y cómo adaptar nuestros proyectos.

    Preguntas frecuentes

    ¿Puedo desactivar la marca de agua en la API de Claude?

    No. Anthropic ha desplegado el sistema de watermarking a nivel de inferencia sin ningún parámetro de exclusión en la API ni en las cuentas Enterprise, alineándose con las normativas internacionales como el EU AI Act.

    ¿La marca de agua ralentiza la generación o encarece el coste de tokens?

    Anthropic no ha reportado ningún impacto. Por diseño, este tipo de watermarking solo sesga qué token se elige dentro de la misma distribución de probabilidad que el modelo ya calculaba: no añade tokens extra ni pasadas adicionales de inferencia, así que el coste computacional adicional es marginal.

    ¿Un detector de watermark puede acusarme falsamente de usar IA?

    Con textos largos, la probabilidad matemática de un falso positivo en un test de hipótesis tipo Kirchenbauer es extremadamente baja — es la base estadística del método, aunque Anthropic no ha publicado la tasa exacta para Claude. Aun así, es un mecanismo mucho más fiable que los detectores heurísticos habituales, que fallan con frecuencia.

    ¿Qué pasa si traduzco el texto generado por Claude a otro idioma?

    Si traduces el texto mediante otra herramienta o manualmente, la alineación de los tokens con la clave pseudo-aleatoria original se destruye y la marca de agua estadística deja de ser detectable.

    Por Bezael Pérez — Developer senior con más de 15 años de experiencia y fundador de Dominicode.

  • Tokens en español: por qué cuestan un 26 % más que en inglés

    Tokens en español: por qué cuestan un 26 % más que en inglés

    Hace unas semanas revisé el consumo de API de un agente de soporte. Sonnet, 25.000 conversaciones al mes, prompts cortos, nada exótico. El equipo había estimado el coste a mano antes de lanzar y la factura llegó cerca de un 26 % por encima.

    Estuvimos media hora buscando la llamada duplicada. No había llamada duplicada.

    El problema eran los tokens en español. No porque un token en español cueste más —el precio por token es idéntico—, sino porque necesitas más tokens para decir exactamente lo mismo.

    Y la parte incómoda es por qué necesitas más. La respuesta cómoda es "el español es más largo". Esa respuesta no llega a explicar ni la mitad de lo que pasa.

    Lo medí.

    La respuesta corta: el español consume un 26,0 % más de tokens que el inglés para transmitir el mismo mensaje, medido sobre cinco pares de textos paralelos con o200k_base (GPT-4o / GPT-5). Unos 10 puntos vienen de que el español usa más palabras; el resto, de que el tokenizador parte cada palabra española en más trozos. El precio por token es idéntico en los dos idiomas: lo que cambia es cuántos necesitas.

    Medí los tokens en español de cinco textos reales

    Cogí cinco textos del tipo que de verdad mandas a un modelo en producción y escribí la versión española y la inglesa de cada uno, con el mismo significado y el mismo registro. Nada de traducciones infladas: pares paralelos.

    Luego los pasé en local por o200k_base, el tokenizador de la familia GPT-4o / GPT-5.

    Tabla 1 — Sobrecoste de tokens del español frente al inglés en cinco pares de textos paralelos, medidos con o200k_base. Medición propia de Dominicode, julio de 2026.

    Tipo de texto Tokens EN Tokens ES Sobrecoste ES vs EN
    System prompt de agente 74 86 +16,2 %
    Documentación técnica 62 85 +37,1 %
    Mensaje de un usuario (soporte) 65 73 +12,3 %
    Fragmento de base de conocimiento (RAG) 67 93 +38,8 %
    Prompt de tarea de desarrollo 55 70 +27,3 %
    Total 323 407 +26,0 %

    El español consume un 26,0 % más de tokens que el inglés para decir exactamente lo mismo. No es una anécdota: es un multiplicador que se aplica a cada llamada de tu aplicación, todos los días.

    Y fíjate en la dispersión, porque ahí está la parte accionable: el mensaje de un usuario se hincha un 12,3 %; un fragmento de base de conocimiento, un 38,8 %. Tres veces más de castigo según el tipo de texto.

    No es que hables más. Es que te parten peor.

    Descompongo ese +26 % en sus dos factores:

    • Palabras: 290 en inglés → 319 en español = +10,0 %
    • Tokens por palabra: 1,114 en inglés → 1,276 en español = +14,5 %. O sin decimales, por si se lee mejor: 111 tokens por cada 100 palabras inglesas frente a 128 por cada 100 españolas.

    Y los dos factores se multiplican, no se suman: 1,10 × 1,145 = 1,26. Ahí está el +26 % completo.

    Traducido: de los 26 puntos de sobrecoste, solo unos 10 vienen de que el español use más palabras. El resto viene de que cada palabra española se rompe en más trozos.

    Esto no es una queja sobre el idioma, es ingeniería. El vocabulario de un tokenizador BPE se construye por estadística sobre un corpus mayoritariamente inglés, así que las secuencias frecuentes en inglés se quedan con las plazas buenas: una palabra inglesa común entra entera en un token y su equivalente española entra a trozos. Súmale que el español conjuga y deriva mucho más, y cada variante es una cadena distinta que el tokenizador no tiene memorizada.

    Eso explica también la dispersión de la tabla. Los dos que menos se inflan son el mensaje de usuario (+12,3 %) y el system prompt (+16,2 %): frases cortas, vocabulario común y terminología técnica que el tokenizador reconoce igual en los dos idiomas. Los que más se inflan son la documentación (+37,1 %) y los fragmentos de RAG (+38,8 %), que llevan prosa española de verdad, con subordinadas y nominalizaciones largas de las de "-ción" y "-miento". La regla práctica: cuanta más prosa explicativa, más sobrecoste.

    El sobrecoste del español baja de +44 % a +26 %

    Pasé los mismos cinco pares por cl100k_base, el tokenizador antiguo de GPT-3.5 y GPT-4: 323 tokens en inglés y 465 en español. Un +44,0 %.

    De +44 % a +26 % en una generación de tokenizador. El vocabulario de o200k_base es más grande y menos anglocéntrico. Pero son dos medidas, no una ley: bajó una vez, no des por hecho que baje siempre. Lo que sí puedes dar por hecho es que si en 2023 tomaste una decisión de arquitectura basada en lo que costaba el español, ese número está caduco.

    Metodología y límites de la medición

    Medición hecha por Bezael Pérez (Dominicode) en julio de 2026: cinco pares de textos paralelos español/inglés —system prompt de agente, documentación técnica, mensaje de soporte, fragmento de RAG y prompt de tarea de desarrollo—, tokenizados en local con o200k_base y cl100k_base. Totales: 323 tokens en inglés frente a 407 en español con o200k_base, y 465 con cl100k_base.

    Cada proveedor usa su propio tokenizador. Anthropic no publica el suyo: la única fuente fiable para contar tokens de Claude es su endpoint count_tokens — y Anthropic la llama estimación, no medida exacta.

    Así que los porcentajes de arriba son de la familia OpenAI (o200k_base), no de Claude. La dirección del efecto es la misma en todos los modelos comerciales, pero el número exacto varía según proveedor y tipo de texto. Anthropic lo admite en su propia página de precios: un token son "aproximadamente 4 caracteres o 0,75 palabras en inglés", y el recuento exacto "varía según el idioma".

    Con Claude hay además un detalle que cambia los números absolutos, avisado en esa misma página: los modelos de la generación 4.7 en adelante —Opus 5 y Sonnet 5 incluidos— usan un tokenizador nuevo que produce alrededor de un 30 % más de tokens que los anteriores para el mismo texto. Se nota en sus estimaciones: el millón de tokens de Opus 5 son ~555.000 palabras en inglés, y en Opus 4.6 eran ~750.000.

    Así que no copies la cifra de este post. Mídela. Es gratis y te cuento cómo abajo.

    Dónde se paga el sobrecoste de tokens en español: factura, contexto y latencia

    1. La factura: cuánto cuesta el sobrecoste al mes

    Tabla 2 — Precios oficiales de la API de Anthropic por millón de tokens, en USD (consultados el 30 de julio de 2026).

    Modelo Entrada ($/M tokens) Salida ($/M tokens)
    Claude Opus 5 $5 $25
    Claude Sonnet 5 $3 $15
    Claude Haiku 4.5 $1 $5

    Ojo a la fecha con Sonnet 5: los $3 / $15 son la tarifa estándar que entra el 1 de septiembre de 2026; hasta el 31 de agosto rige el lanzamiento de $2 / $10, un tercio más barato. Calculo con la estándar porque es la que pagarás cuando esto lleve unos meses en producción.

    Vuelvo al agente del principio: Sonnet 5 a tarifa estándar, 25.000 conversaciones al mes, 1.500 tokens de entrada y 300 de salida por conversación. El modelo responde en el idioma en el que le escriben, así que cuando el usuario escribe en español la salida también se hincha un 26 %.

    • En inglés: entrada 37,5 M × $3 = $112,50 · salida 7,5 M × $15 = $112,50 → $225/mes
    • En español (+26 % en entrada y en salida): entrada 47,25 M × $3 = $141,75 · salida 9,45 M × $15 = $141,75 → $283,50/mes

    Diferencia: $58,50 al mes. $702 al año. Por escribir en el idioma de tus usuarios. El +26 % va aquí como aproximación, por lo que ya expliqué: el tokenizador de Claude no es público.

    A esta escala es asumible. Multiplícalo por diez y ya es una decisión de producto.

    2. La ventana de contexto

    Opus 5 y Sonnet 5 tienen 1 millón de tokens de ventana de contexto. Y ojo con la cuenta, porque aquí el 26 % se da la vuelta: si cada texto te cuesta un 26 % más de tokens, en ese millón te cabe un 21 % menos de contenido (1 ÷ 1,26 = 0,79). Con fragmentos de base de conocimiento, que se hinchan un 38,8 %, la pérdida sube al 28 %.

    En un RAG eso no es una curiosidad académica: es recall —y si todavía estás decidiendo entre RAG y fine-tuning, el idioma entra en la ecuación de coste. Con el mismo presupuesto de contexto inyectas menos fragmentos por consulta.

    Menos evidencia recuperada para la misma pregunta es exactamente la situación en la que un modelo empieza a rellenar huecos, que es el mecanismo que expliqué en por qué la IA se inventa cosas.

    Y antes de que la solución sea "pues meto más": llenar la ventana tampoco es gratis en calidad. Va de eso la regla del 60 % en gestión de contexto.

    3. La latencia

    Un modelo emite los tokens de salida de uno en uno, a un ritmo más o menos fijo. Si tu respuesta en español necesita un 26 % más de tokens, tarda un 26 % más en terminar.

    Ojo con dónde lo notas, porque es fácil confundirse: si haces streaming, el primer token llega igual de rápido —eso lo manda el prefill de la entrada, no la longitud de la salida—, y lo que se alarga es la respuesta completa. Sin streaming, el usuario se come el 26 % entero mirando el cursor parpadear. Y si detrás hay un agente que encadena cinco llamadas, ese 26 % se acumula en cada paso.

    Qué hacer con esto (sin escribir peor español)

    Mide, no estimes. El endpoint count_tokens de Anthropic es gratis. Solo lo limitan las peticiones por minuto de tu tier: 2.000 en Start, 4.000 en Build, 8.000 en Scale.

    import Anthropic from "@anthropic-ai/sdk"

const client = new Anthropic()

const systemEs = "Eres un agente de soporte…"   // tu system prompt real
const systemEn = "You are a support agent…"     // el mismo, en inglés

async function contar(system: string) {
  const res = await client.messages.countTokens({
    model: "claude-opus-5",
    system,
    messages: [{ role: "user", content: "ping" }],
  })
  return res.input_tokens
}

console.log(await contar(systemEs), await contar(systemEn))

    El "ping" está ahí porque messages es obligatorio; al ser idéntico en las dos llamadas, la diferencia sale limpia. Quince minutos y dejas de discutir con estimaciones.

    El system prompt en inglés, el contenido del usuario en español. El system prompt se repite en cada llamada y tu usuario nunca lo lee. Traducirlo al inglés te quita tokens de encima en todas.

    Pero pon el número antes de comprar la idea. Mi system prompt de prueba baja de 86 a 74 tokens: por 25.000 conversaciones al mes son $0,90 con Sonnet 5. Con un system prompt realista de 2.000 tokens, unos $21 al mes. Con caché, una décima parte de eso. Es una optimización real, pero es de un dígito o dos de dólares — no la vendas como el arreglo.

    Y no es gratis. Si lo traduces, fija el idioma de salida de forma explícita —"Always respond in Spanish, regardless of the language of these instructions"— en vez de dejar que el modelo lo infiera del mensaje. Si dentro tienes few-shots, cuidado: los ejemplos arrastran el idioma de salida tanto como la instrucción. Y deja en español cualquier texto que el modelo tenga que devolver literal —mensajes fijos, disclaimers, nombres de producto—, o te lo traducirá a su manera. Después de tocar el system prompt, vuelve a pasar tus evals.

    Prompt caching. Esta es la palanca de verdad. Si el system prompt y el contexto fijo se repiten entre llamadas, cachéalos: una lectura de caché cuesta 0,1× el precio de entrada, un 90 % menos. Ataca justo la parte repetida, la que paga el 26 % una y otra vez sin cambiar una coma, y por eso rinde un orden de magnitud más que traducir nada. Lo desarrollé entero en prompt caching con la API de Claude. Orden de prioridades: primero cachea, después piensa en el idioma.

    Vigila lo que inyectas en cada consulta. Los fragmentos de base de conocimiento son lo que más se hincha (+38,8 %) y van en cada petición; la documentación técnica le sigue (+37,1 %). Si trabajas con specs, esto te toca de lleno: una spec es documentación técnica que entra en el contexto en cada iteración. Una razón más para escribirlas cortas y estructuradas, como insisto en el libro de Spec-Driven Development.

    Lo que NO debes hacer: escribir peor español para ahorrar tokens. Nada de abreviar, quitar tildes o telegrafiar los prompts como un SMS de 2004. El ahorro es de céntimos, y transliterar o mutilar el texto es justo lo contrario de lo que recomiendan los propios proveedores, que piden enviarlo en su escritura nativa. Si necesitas gastar menos: cachea, elige un modelo más pequeño para la tarea, reduce el número de llamadas o mueve la carga a un modelo local, donde el sobrecoste del español deja de facturarse por token y pasa a ser tiempo de GPU.

    Cómo medir tus tokens en español hoy mismo

    Abre tu system prompt de producción. El real, el que ya está desplegado.

    1. Copia tu system prompt tal cual está desplegado.
    2. Pásalo por count_tokens y anota input_tokens.
    3. Traduce ese mismo prompt al inglés sin recortar contenido.
    4. Pásalo otra vez y anota el segundo número.
    5. Resta, divide por el valor en inglés y multiplica por tus llamadas mensuales y por el precio de entrada de tu modelo.

    En quince minutos tienes tu número, no el mío.

    La mayoría descubre que su problema no era el idioma: era que no estaban cacheando nada. Ese diagnóstico solo aparece cuando mides.

    Si quieres el flujo completo para llevar una idea a producto con Claude Code —y salir con instrumentación, no con intuiciones—, es lo que trabajo en Construye con IA: de la idea al producto con Claude Code. Y si prefieres verlo sobre proyectos reales, con gente peleándose con las mismas facturas, eso pasa cada semana en Dominicode Labs.

    Preguntas frecuentes sobre los tokens en español

    ¿Cuánto más cuesta escribir prompts en español que en inglés?

    En mi medición con o200k_base sobre cinco pares de textos paralelos, un 26,0 % más de tokens para decir lo mismo: 323 en inglés frente a 407 en español.

    El rango va de +12,3 % (mensaje de un usuario) a +38,8 % (fragmento de RAG): el tipo de texto importa tanto como el idioma.

    ¿Es porque el español es más largo?

    Solo en parte, y los dos factores se multiplican, no se suman: un +10,0 % de palabras (290 → 319) por un +14,5 % de tokens por palabra (1,114 → 1,276) sale 1,10 × 1,145 = 1,26. El factor grande es el segundo.

    La causa es el tokenizador, no la verborrea: su vocabulario se entrenó sobre un corpus mayoritariamente inglés, y lo que no está bien representado ahí se fragmenta.

    ¿Cuántos tokens es una palabra en español?

    1,276 tokens por palabra de media en mi medición con o200k_base, frente a 1,114 en inglés. O sin decimales: unos 128 tokens por cada 100 palabras españolas y 111 por cada 100 inglesas.

    Es una media sobre texto real de producción: sube en prosa explicativa y baja en textos cargados de terminología inglesa, que el tokenizador ya conoce.

    ¿Qué tipo de texto se encarece más al escribirlo en español?

    Los fragmentos de base de conocimiento para RAG (+38,8 %) y la documentación técnica (+37,1 %). El que menos, los mensajes que escriben los propios usuarios (+12,3 %).

    La diferencia está en la densidad de jerga inglesa: cuanto más técnico es el texto, más tokens comparte el español con el inglés y menos se infla.

    ¿Cómo cuento los tokens en español que consume Claude?

    Con el endpoint count_tokens de la API de Anthropic, disponible en el SDK oficial como client.messages.countTokens(). Es gratis y solo lo limitan las peticiones por minuto de tu tier: 2.000 en Start, 4.000 en Build, 8.000 en Scale.

    Es además la única fuente oficial, porque Anthropic no publica su tokenizador. Ni siquiera ella es exacta: Anthropic advierte de que el conteo es una estimación y puede desviarse ligeramente del consumo real. Cualquier cifra calculada con o200k_base o cl100k_base es una aproximación de otro proveedor.

    ¿Debo escribir mis prompts en inglés para ahorrar dinero?

    El system prompt puedes traducirlo: se repite en cada llamada, nadie lo lee y los modelos responden en español perfectamente aunque las instrucciones estén en inglés. Pero mide el ahorro antes de moverlo, porque suele ser de un dígito o dos de dólares al mes, y desaparece casi entero si ya estás cacheando.

    El contenido del usuario, no lo toques. Y no traduzcas tu base de conocimiento al inglés solo por coste sin medir antes qué le pasa a la calidad de las respuestas. Antes de eso activa prompt caching: ahorra un 90 % en la parte repetida y no cambia nada de tu producto.

    ¿Este sobrecoste va a desaparecer?

    Se está reduciendo: los mismos cinco pares dan +44,0 % con cl100k_base (GPT-3.5 / GPT-4) y +26,0 % con o200k_base (GPT-4o / GPT-5), porque los vocabularios nuevos son más grandes y menos anglocéntricos.

    Pero no lo tomes como una tendencia garantizada. Son dos medidas, no una ley, y hay contraejemplos: los modelos Claude de la generación 4.7 en adelante usan un tokenizador nuevo que produce alrededor de un 30 % más de tokens que los anteriores para el mismo texto. Vuelve a medir cada vez que cambies de modelo.

    ¿Afecta el idioma a la ventana de contexto?

    Sí, y es el coste que menos se vigila. Cuidado con la cuenta, porque el porcentaje se invierte: en 1 millón de tokens —el que traen Opus 5 y Sonnet 5— cabe un 21 % menos de contenido si está en español, porque un +26 % de tokens por texto equivale a 1 ÷ 1,26 de contenido por ventana. Con fragmentos de RAG (+38,8 %) la pérdida es del 28 %.

    En un RAG eso significa menos fragmentos recuperados por consulta con el mismo presupuesto de contexto.

    Por Bezael Pérez — Developer senior con más de 15 años de experiencia y fundador de Dominicode.

  • Qué es un modelo multimodal: tu imagen también son tokens

    Qué es un modelo multimodal: tu imagen también son tokens

    Hace unas semanas metí un pantallazo de un dashboard de facturación en una llamada a la API y le pedí al modelo el total del mes.

    Me devolvió una cifra. Redonda, con su símbolo de euro, con toda la seguridad del mundo.

    Estaba mal. No un poco mal: mal de otro trimestre.

    Mi primer reflejo fue culpar al OCR. Craso error, porque ahí no había ningún OCR. Y ese fue el momento en el que entendí que llevaba meses usando un modelo multimodal sin tener ni idea de lo que pasaba entre mi fetch y la respuesta.

    El modelo no leyó mi dashboard. Lo convirtió en tokens y predijo qué números encajaban ahí.

    Qué es un modelo multimodal

    Un modelo multimodal es un modelo de IA que acepta más de un tipo de entrada —texto, imagen, audio o vídeo— porque convierte todas esas entradas a vectores del mismo espacio y las procesa con un único transformer. No hay un "módulo de visión" que mira y luego le cuenta al modelo lo que hay: todo acaba siendo la misma sopa de números, y el modelo sigue haciendo lo único que sabe hacer, predecir el siguiente token.

    Lo esencial, antes de entrar en detalle:

    • Entrada no es salida. Que un modelo acepte imágenes no significa que las genere. Claude entiende imágenes; no las produce ni las edita.
    • Se factura por parches. Claude trocea la imagen en bloques de 28×28 px y cobra cada bloque como un visual token.
    • El coste es de prompt. Una captura de 1000×1000 px son 1.296 tokens de entrada antes de que el modelo escriba una palabra.
    • El conteo es aproximado. La documentación de Anthropic lo admite: los conteos de objetos y las coordenadas no son exactos.

    Cómo funciona: tu imagen no entra como imagen, entra como tokens

    Un modelo multimodal procesa una imagen en tres pasos: un encoder la trocea en parches y convierte cada parche en un vector, una capa de proyección lleva esos vectores a la misma dimensionalidad que los embeddings de texto, y el transformer los mezcla con los tokens de tu prompt como si fueran palabras. Si ya tienes claro que la IA no piensa, predice, es una extensión bastante elegante de la misma idea.

    Un LLM de texto tiene un tokenizador: parte tu string en trozos y a cada trozo le asigna un vector de N dimensiones. Ese vector es lo que come el transformer.

    Un modelo multimodal añade una pieza delante: un encoder por cada modalidad. Para imagen suele ser un Vision Transformer que trocea el bitmap en parches cuadrados y convierte cada parche en un vector. Para audio, algo equivalente sobre el espectrograma.

    Después viene el truco de todo esto: una capa de proyección que traduce esos vectores a la misma dimensionalidad que los embeddings de texto. Pasada esa capa, el transformer los procesa con la misma maquinaria: no hay una ruta especial para lo visual. El vector del parche 47 de tu JPEG y el de la palabra "factura" son vecinos en el mismo espacio, aunque el modelo sepa perfectamente cuál vino de dónde.

    Anthropic lo documenta de forma literal: Claude ve las imágenes en parches de 28×28 píxeles y a cada parche lo llama visual token. No es una metáfora divulgativa, es la unidad de facturación.

    El detalle que rompe la intuición: la secuencia final es una lista plana donde los tokens de la imagen y los de tu prompt están mezclados, atendiéndose unos a otros con el mismo mecanismo de atención de siempre.

    No hay un ojo. Hay una secuencia más larga.

    Y ojo con la confusión que cuesta dinero en reuniones de producto: que un modelo acepte imágenes no significa que las genere. Claude entiende imágenes, no las produce ni las edita. Gemini y la familia GPT sí generan, con endpoints y precios propios. Cuando alguien proponga "usar IA multimodal", pregunta si habla de entrada o de salida.

    El código: mandar una imagen de verdad

    Así se envía una imagen a Claude con el SDK oficial de TypeScript. Fíjate en el orden: la imagen antes del texto, porque la propia documentación de Anthropic recomienda esa estructura.

    import Anthropic from "@anthropic-ai/sdk";
import { readFile } from "node:fs/promises";

const anthropic = new Anthropic(); // lee ANTHROPIC_API_KEY del entorno

const imageData = (await readFile("factura.jpg")).toString("base64");

const message = await anthropic.messages.create({
  model: "claude-opus-5",
  max_tokens: 16000, // el thinking va dentro de este tope: no lo dejes corto
  messages: [
    {
      role: "user",
      content: [
        {
          type: "image",
          source: {
            type: "base64",
            media_type: "image/jpeg",
            data: imageData,
          },
        },
        {
          type: "text",
          text: "Extrae total, fecha y NIF. Devuelve JSON. Si un campo no es legible, null.",
        },
      ],
    },
  ],
});

console.log(message.usage.input_tokens); // aquí está la factura de verdad

    Si la imagen ya vive en una URL pública, te ahorras el base64:

    // sustituye el bloque de imagen del array content por este
const imageBlock: Anthropic.ImageBlockParam = {
  type: "image",
  source: { type: "url", url: "https://ejemplo.com/factura.jpg" },
};

    Loguea usage.input_tokens desde el primer día. Es la diferencia entre una demo bonita y saber lo que te va a costar en producción.

    Y ese null del prompt no es adorno: cuando el modelo te devuelve JSON extraído de un píxel borroso, necesitas un esquema que valide antes de que ese dato toque tu base de datos. Es el patrón que trabajo en el curso de Zod: el modelo propone, el schema dispone.

    Cuánto cuesta una imagen en un modelo multimodal

    Una imagen cuesta ⌈ancho / 28⌉ × ⌈alto / 28⌉ visual tokens en la API de Claude. Es aritmética pública y simple, y aun así aquí es donde se tuercen la mayoría de los proyectos multimodales: nadie hace la cuenta antes.

    Los modelos de Claude 4.7 en adelante están en el tier de alta resolución (borde largo máximo 2576 px, tope de 4.784 visual tokens); los anteriores, en el estándar (1568 px, 1.568 tokens). Si te pasas, la imagen se reescala antes de procesarse.

    Estas son las cifras que publica la documentación oficial de visión de Anthropic:

    Imagen Tier estándar Tier alta resolución
    200×200 px 64 tokens 64 tokens
    1000×1000 px 1.296 tokens 1.296 tokens
    1920×1080 px 1.560 tokens (reescalada a 1456×819) 2.691 tokens
    3840×2160 px (4K) 1.560 tokens (reescalada) 4.784 tokens (reescalada a 2576×1449)

    Traduce eso a dinero. Con Opus 5 a 5 $ por millón de tokens de entrada (precios de julio de 2026), mil capturas de 1000×1000 salen por unos 6,48 $ y mil capturas en 4K por unos 23,92 $. La cuenta la puedes rehacer tú: 1.296 × 5 / 1.000.000 × 1.000.

    Parece barato hasta que lo multiplicas por un agente que itera catorce veces sobre la misma pantalla.

    Con audio pasa lo mismo en otra escala. Gemini documenta 32 tokens por segundo, o sea 1.920 tokens por minuto. Una reunión de una hora son unos 115.000 tokens de entrada antes de que el modelo escriba una sola palabra.

    Tres consecuencias prácticas:

    1. Redimensiona antes de subir. Mandar un 4K cuando el texto se lee perfectamente a 1200 px es tirar tokens y latencia a la basura.
    2. En conversaciones de varios turnos, usa la Files API. Con base64 el payload entero viaja otra vez en cada turno, porque el historial se reenvía completo. Con file_id subes una vez y referencias. Ojo: hoy va por anthropic.beta.files.upload y hay que pasar betas: ["files-api-2025-04-14"].
    3. La imagen infla el prompt, no la respuesta. Ese coste es todo de entrada y el modelo lo digiere antes del primer token. La latencia sube aunque respondas tres líneas.

    Dónde falla un modelo multimodal (y falla más de lo que crees)

    Un modelo multimodal alucina con imágenes por el mismo motivo por el que la IA se inventa cosas con texto: no hay un módulo de verdad, hay una distribución de probabilidad. La diferencia es que con una imagen mala el modelo tiene menos señal y más margen para rellenar con lo plausible.

    Mi dashboard fue justo eso. Cifras pequeñas, reescaladas, con poco contraste. El modelo generó el número que estadísticamente encajaba en ese hueco.

    La documentación de Anthropic reconoce los límites sin maquillaje. Con imágenes de baja calidad, rotadas o de menos de 200 píxeles, alucina. Los conteos de objetos son aproximados. Las coordenadas, también. Y no puede determinar si una imagen fue generada por IA: si se lo preguntas, se inventa la respuesta.

    Léelo otra vez: el conteo es aproximado. Si tu caso de uso es "cuántos palés hay en esta foto" y tu negocio depende de esa cifra, tienes un problema de arquitectura, no de prompt.

    Sobre el OCR: un modelo multimodal entiende un documento con layout raro, tablas torcidas o manuscritos mucho mejor que Tesseract. Pero un OCR clásico es determinista y trazable. El modelo puede darte dos respuestas distintas para la misma imagen, y si le pides coordenadas te las da aproximadas, nunca como una región verificable contra el original. En un pipeline de compliance eso es inaceptable.

    Modelo multimodal OCR clásico (Tesseract, Textract)
    Layout variable, manuscritos, fotos malas Muy bueno Malo
    Misma imagen → misma salida No garantizado Sí
    Trazabilidad de dónde salió el dato No la da Sí, con bounding boxes
    Coste Por visual token, escala con la resolución Plano o por página
    Entiende el contenido ("¿este ticket es de comida?") Sí No
    Apto para compliance sin revisión humana No Sí

    Cuándo usar un modelo multimodal y cuándo es un martillo caro

    Mi regla, después de comerme varias facturas de API sin necesidad:

    Si el dato ya existe en forma estructurada, no le mandes la foto. Si tienes el PDF con capa de texto, extrae el texto. Si tienes la API del dashboard, llama a la API. Mandar una captura de algo que podías consultar en JSON es la forma más cara de leer un número.

    Usa multimodal cuando la información vive en la disposición visual y no en el contenido. Un ticket arrugado fotografiado de noche. Un diagrama en una pizarra. El screenshot de una UI rota que un usuario manda por soporte. Ahí la alternativa no es un parser peor: es que no hay alternativa.

    Y vigílalo dentro del bucle agéntico. Si montas un agente que navega e interpreta pantallas, cada iteración multiplica el coste visual. Esa distinción entre IA generativa e IA agéntica importa mucho más cuando cada paso arrastra 2.700 tokens de imagen.

    Y si lo que necesitas es buscar entre miles de imágenes en vez de razonar sobre una, ya no quieres un modelo generativo: quieres embeddings multimodales e índice vectorial. Lo tienes montado paso a paso en el pipeline multimodal con Gemini Embedding 2.

    La decisión que va antes —si tu problema es de búsqueda, de RAG o de fine-tuning— la desmenucé aquí.

    Lo que puedes hacer hoy

    Coge la funcionalidad multimodal que tengas en marcha o en el backlog y haz una sola cosa: calcula sus visual tokens con la fórmula, multiplícalos por tu volumen mensual real y compáralo con lo que cuesta resolverlo sin imagen.

    En más casos de los que esperas descubrirás que ibas a pagar por interpretar un pantallazo de un dato que ya tenías en una tabla. En el resto tendrás el número exacto para defender el proyecto delante de quien firma.

    Los modelos multimodales no son magia ni son un timo. Son un canal de entrada más, con su precio por parche y su margen de error. Trátalos como lo que son: una dependencia cara. Mídela antes de casarte con ella.

    Cómo encaja esto en un producto completo —qué resuelve el modelo y qué resuelve código normal— lo trabajo de principio a fin en Construye con IA. Y si prefieres discutirlo con gente que está construyendo lo mismo esta semana, estamos en Dominicode Labs.

    Preguntas frecuentes

    ¿Qué es un modelo multimodal en una frase?

    Un modelo que acepta varios tipos de entrada —texto, imagen, audio, vídeo— porque los convierte todos a vectores del mismo espacio antes de procesarlos. En la práctica, para el desarrollador significa una sola cosa: tu imagen entra en el prompt como tokens, cuesta como tokens y se factura como tokens.

    ¿Un modelo multimodal "ve" la imagen como una persona?

    No. Trocea el bitmap en parches, convierte cada parche en un vector y los intercala con los tokens de tu prompt. No hay percepción: hay una secuencia de números sobre la que se aplica atención. Por eso describe con precisión una escena compleja y a la vez falla contando cuatro objetos.

    ¿Cuántos tokens cuesta enviar una imagen?

    Depende de la resolución y del proveedor. En la API de Claude son ⌈ancho / 28⌉ × ⌈alto / 28⌉ visual tokens, con reescalado automático si superas el límite del modelo: 1000×1000 px son 1.296 tokens y un 4K llega al tope de 4.784 en el tier de alta resolución. Son cifras aproximadas de la documentación oficial, así que loguea usage.input_tokens en vez de fiarte de una estimación.

    ¿Es mejor un modelo multimodal que un OCR clásico?

    Para documentos con layout variable, manuscritos o fotos malas, casi siempre sí. Para pipelines que necesitan determinismo, trazabilidad y coste plano, no. Muchos sistemas serios usan los dos, con el modelo actuando solo sobre lo que el OCR no resuelve.

    ¿Los modelos multimodales también generan imágenes?

    No todos. Aceptar imágenes como entrada y producirlas como salida son capacidades distintas. Claude entiende imágenes pero no las genera ni las edita, según su propia documentación. Gemini y la familia GPT sí tienen generación, con endpoints y precios propios. Confirma cuál de las dos necesitas antes de planificar la feature.

    Por Bezael Pérez — Developer senior con más de 15 años de experiencia y fundador de Dominicode.

  • Claude Opus 5: los 2 breaking changes que rompen tu código

    Claude Opus 5: los 2 breaking changes que rompen tu código

    Cambias una línea. Un campo model dentro de un JSON. Diez segundos de trabajo, deploy a staging, a otra cosa.

    Veinte minutos después el endpoint de resúmenes devuelve textos cortados a mitad de frase. Y una ruta concreta —la de análisis largo, la que más te importa— devuelve 400 sin que hayas tocado nada más.

    No es un bug de Anthropic. Eres tú, migrando a Claude Opus 5 como si fuera un cambio de versión menor.

    No lo es. Y el problema es que casi todo lo que vas a leer estos días sobre este modelo son tablas de benchmarks. El titular es que cuesta la mitad que Fable 5. La letra pequeña es que si no tocas dos parámetros, tu aplicación empieza a devolver respuestas cortadas y errores 400.

    Este post va de la letra pequeña.

    Qué es Claude Opus 5 y qué cambia respecto a Opus 4.8

    Claude Opus 5 es el modelo más capaz de Anthropic, disponible desde el 24 de julio de 2026 con el identificador de API claude-opus-5, sin sufijo de fecha. Cuesta $5 por millón de tokens de entrada y $25 de salida —el mismo precio que Opus 4.8— y trae dos breaking changes respecto a la generación anterior: el thinking viene activado por defecto y desactivarlo deja de ser compatible con los niveles de effort xhigh y max.

    Atributo Claude Opus 5 Claude Opus 4.8
    ID de API claude-opus-5 claude-opus-4-8
    Precio entrada / salida $5 / $25 por millón $5 / $25 por millón
    Fast mode (solo API de Anthropic) $10 / $50 por millón —
    Thinking al omitir el parámetro Adaptativo, activado Desactivado
    Qué cubre max_tokens Thinking + respuesta Solo la respuesta
    Effort por defecto en la API high —
    thinking: disabled + xhigh/max HTTP 400 Válido
    Mínimo para prompt caching 512 tokens 1024 tokens
    Ventana de contexto 1M tokens (defecto y máximo) —
    Salida máxima 128K tokens —
    Rate limits Cubo propio Pool combinado Opus 4.x

    Está disponible en Claude.ai, Claude Code, Claude Cowork, la API de Anthropic, Amazon Bedrock (anthropic.claude-opus-5), Google Cloud y Microsoft Foundry. Es el modelo por defecto en Claude Max y el más potente disponible en Claude Pro. Los datos de esta tabla están contrastados con la documentación oficial de Anthropic.

    Los benchmarks de Claude Opus 5, en treinta segundos

    Sí, los números son buenos. Los despacho rápido porque no son el tema.

    En CursorBench 3.2, a máximo effort, Claude Opus 5 se queda a un 0,5% del pico de Fable 5 —a la mitad de coste por tarea—. En ARC-AGI 3 triplica la puntuación del siguiente mejor modelo. En Frontier-Bench v0.1 más que dobla el rendimiento de Opus 4.8. Los tres resultados salen de las cifras publicadas por Anthropic.

    No es el mejor en todo: sigue por detrás de Mythos 5 en tareas de ciberseguridad ofensiva. Y Anthropic lo describe como su modelo mejor alineado hasta la fecha, con la menor tasa de comportamiento engañoso.

    Si vienes de Claude Opus 4.8, pagas lo mismo por token por un modelo bastante mejor. Con un matiz que casi nadie menciona: Opus 5 piensa por defecto y escribe más largo, así que gasta más tokens por tarea. Misma tarifa no significa misma factura. Y si estabas pagando el premium de Fable 5 por tareas de agente, ahí sí: Anthropic mide la mitad de coste por tarea.

    Perfecto. Ahora la parte que rompe cosas.

    Breaking change 1 de Claude Opus 5: el thinking viene activado por defecto

    En Claude Opus 5, omitir el parámetro thinking ejecuta thinking adaptativo; en Opus 4.8 y 4.7 omitirlo significaba no razonar. Este es el cambio que corta tus respuestas a mitad de frase.

    Antes, el silencio equivalía a "no razones, contéstame". Ahora el silencio es un sí.

    Y aquí viene la parte que duele: max_tokens es un tope duro sobre thinking más texto de respuesta, juntos. No son dos presupuestos separados.

    Si tenías max_tokens ajustado al milímetro para tu respuesta —y todo el que ha optimizado costes lo tiene ajustado al milímetro— el modelo se gasta parte de ese presupuesto razonando y la respuesta se corta.

    Este código funcionaba perfectamente ayer:

    import Anthropic from "@anthropic-ai/sdk";
const client = new Anthropic();

// Opus 4.8 — omitir "thinking" = sin razonamiento; 1024 tokens íntegros para la respuesta
const res = await client.messages.create({
  model: "claude-opus-4-8",
  max_tokens: 1024,
  messages: [{ role: "user", content: prompt }],
});

    Cambias el model a claude-opus-5 y esos 1024 tokens ahora se reparten entre razonamiento y respuesta. Nadie te avisa: no hay error, solo un texto que termina a media frase.

    Tienes dos salidas. La buena:

    // Opus 5 — thinking explícito y presupuesto con margen
const res = await client.messages.create({
  model: "claude-opus-5",
  max_tokens: 8192, // cubre thinking + respuesta
  thinking: { type: "adaptive", display: "summarized" },
  output_config: { effort: "medium" },
  messages: [{ role: "user", content: prompt }],
});

    Y la que replica el comportamiento anterior:

    thinking: { type: "disabled" }

    Cuidado con esa segunda, porque tiene trampa. Es exactamente el breaking change número dos.

    Sobre display: los tokens de razonamiento en crudo no se devuelven nunca. El valor por defecto es "omitted". Si pones "summarized" recibes un resumen legible del razonamiento, útil para logs y para depurar por qué el modelo llegó a donde llegó.

    Breaking change 2: desactivar el thinking en Opus 5 está capado a effort high

    Esta es la que devuelve 400.

    En Opus 5 la escala completa de effort es low, medium, high, xhigh y max. El valor por defecto de la API es high.

    Combinar thinking: { type: "disabled" } con effort xhigh o max devuelve HTTP 400. En Opus 4.8 esa combinación era perfectamente válida.

    // Válido en Opus 4.8 — error 400 en Opus 5
const res = await client.messages.create({
  model: "claude-opus-5",
  max_tokens: 4096,
  thinking: { type: "disabled" },
  output_config: { effort: "xhigh" }, // 400
  messages: [{ role: "user", content: prompt }],
});

    Y ahora el detalle que hace que esto sea peligroso de verdad: la validación es por petición. No hay un chequeo global al arrancar. Puedes tener veinte llamadas funcionando con thinking desactivado y effort high, y que la veintiuna —la que sube a xhigh para el caso difícil— se rechace. Las anteriores funcionando no te protegen de nada.

    Traducido: cualquier ruta de tu código que desactive el thinking hay que auditarla antes de migrar, no después. Búscalo con un grep por "disabled" y revisa qué effort viaja en cada una de esas peticiones.

    Mi recomendación es no mantener esa ruta. En lugar de desactivar el thinking, bájalo a effort medium con thinking activado:

    // Sustituto recomendado para las rutas que antes desactivaban thinking
thinking: { type: "adaptive" },
output_config: { effort: "medium" },

    En Opus 5 los niveles low y medium rinden inusualmente bien. La intuición de "menos effort, peor respuesta" que traías de la generación anterior ya no aplica igual: prueba medium antes de asumir que necesitas high.

    Con un matiz, para que nadie me lea en diagonal: para coding y trabajo agéntico, Anthropic recomienda arrancar en xhigh y bajar solo donde tus evals demuestren que la calidad aguanta. Lo de medium es el sustituto de las rutas que antes desactivaban el thinking, no un consejo para bajarle el effort a tu agente de coding. Y si al bajarlo compruebas que la tarea nunca necesitó Opus, Claude Sonnet 5 cubre buena parte de ese terreno por bastante menos dinero.

    El tercer sitio donde revienta: el rechazo que llega con un 200

    Este no está en la lista oficial de breaking changes, pero te va a tirar producción igual.

    Los clasificadores de seguridad pueden declinar una petición. Cuando lo hacen, la API devuelve HTTP 200 con stop_reason: "refusal". No es un error. Tu try/catch no lo captura, tu retry no se dispara, tu monitorización no lo ve.

    Y content llega vacío: un array sin bloques. Así que este patrón —el que escribe todo el mundo la primera vez— revienta con un TypeError:

    const res = await client.messages.create({ /* ... */ });
const text = res.content[0].text; // 💥 TypeError: content llega vacío

    La corrección son cuatro líneas:

    const res = await client.messages.create({ /* ... */ });

if (res.stop_reason === "refusal") {
  logger.warn("Petición declinada por los clasificadores", { requestId: res.id });
  return fallbackResponse();
}

const text = res.content.find((b) => b.type === "text")?.text ?? "";

    Dos datos más que ayudan aquí. Un rechazo que llega antes de emitir output no se factura, aunque sí consume rate limit. Y si no quieres montar el fallback a mano, Anthropic tiene un parámetro fallbacks en modo "default" (con el beta header server-side-fallback-2026-07-01) que reencamina la petición rechazada a otro modelo dentro de la misma llamada: los rechazos de categoría ciber caen a Opus 4.8.

    Comprueba stop_reason antes de leer content. Siempre. Con este modelo y con el siguiente.

    Dos cambios de comportamiento que te van a sorprender

    Escribe respuestas más largas por defecto. Y bajar el effort no lo arregla —es un eje distinto—. Si necesitas respuestas breves, pídelo en el prompt de forma explícita: límite de palabras, formato, o ambos.

    Verifica su propio trabajo sin que se lo pidas. Esta es la importante, porque invierte una buena práctica de prompting que era válida hasta la semana pasada.

    Todos tenemos system prompts con alguna variante de "revisa tu respuesta antes de contestar". En Opus 5 esas instrucciones provocan verificación excesiva: más tokens, más latencia, misma calidad. La solución no es reescribirlas con mejor redacción. Es borrarlas.

    Con la delegación en subagentes el ajuste es distinto. Opus 5 delega más que Opus 4.8 por defecto, así que los empujones que añadiste para forzarla ahora sobran. Pero aquí no basta con borrar: la recomendación de Anthropic es poner límites —en qué escenarios se delega, o cuántos subagentes como máximo—. Pasas de empujar a acotar.

    Es la parte contraintuitiva del oficio: mantener un system prompt no es acumular reglas, es borrarlas cuando el modelo ya no las necesita. Es exactamente el criterio que trabajo en el curso Construye con IA, donde el prompt se trata como código con mantenimiento, no como un texto que se escribe una vez y se olvida.

    Lo que mejora en Claude Opus 5 sin que toques nada

    El mínimo de prompt caching baja a 512 tokens. En Opus 4.8 eran 1024, y el umbral está en la documentación de prompt caching. Prompts de sistema que antes se quedaban justo por debajo del umbral y no cacheaban, ahora sí cachean, sin cambiar una línea de código.

    Si tienes muchas llamadas cortas y repetitivas, revisa la factura la semana que viene: puede bajar sola. Y si aún no tienes el caching bien montado, la mecánica completa está en Prompt Caching en Claude: reduce tu factura de API un 90%.

    Otros dos datos que conviene tener a mano: la ventana de contexto es de 1M tokens —es a la vez el valor por defecto y el máximo— con 128K tokens de salida. Y los rate limits de Opus 5 son un cubo separado del pool combinado de Opus 4.x: al migrar tráfico no heredas tu cuota anterior. Si mueves un volumen serio, comprueba límites antes del despliegue y no el lunes por la mañana con todo el tráfico encima.

    Cómo migrar a Claude Opus 5 en 4 pasos

    Cuatro pasos, en este orden:

    1. Grep por "disabled" en todas tus llamadas al thinking. Cada resultado, con su effort al lado. Si hay xhigh o max, es un 400 esperándote.
    2. Revisa tus max_tokens. Todo lo que esté ajustado al límite de la respuesta necesita margen para el thinking, o cambia a thinking: { type: "disabled" } con effort high como máximo.
    3. Comprueba stop_reason antes de leer content. Cuatro líneas.
    4. Borra las instrucciones de auto-verificación de tus system prompts. No las reescribas. Y en las de delegación, cambia el empujón por un límite: cuándo se delega y cuántos subagentes como máximo.

    Media hora de trabajo. Y a cambio: te acercas a la inteligencia frontera de Fable 5 por la mitad de coste por tarea.

    Si quieres ver este tipo de migraciones aplicadas sobre proyectos reales —con los prompts, el código y los errores que salen por el camino— es lo que hacemos en Dominicode Labs, y voy publicando los análisis modelo a modelo en el canal de YouTube.

    El precio lo pone Anthropic. Los 400 los pones tú.

    Preguntas frecuentes sobre Claude Opus 5

    ¿Cuánto cuesta Claude Opus 5?

    $5 por millón de tokens de entrada y $25 por millón de tokens de salida, exactamente el mismo precio que tenía Opus 4.8. Fable 5 cuesta $10/$50, así que Opus 5 se acerca a esa franja de inteligencia frontera por la mitad. Existe un fast mode disponible únicamente en la API de Anthropic que cuesta el doble: $10/$50. En suscripciones, es el modelo por defecto de Claude Max y el más potente disponible en Claude Pro.

    ¿Qué se rompe al migrar de Opus 4.8 a Claude Opus 5?

    Dos cosas concretas. Primera: el parámetro thinking ahora viene activado por defecto, y como max_tokens es un tope duro sobre thinking más respuesta juntos, los presupuestos ajustados provocan respuestas cortadas a mitad de frase. Segunda: thinking: { type: "disabled" } combinado con effort xhigh o max devuelve un error 400, cuando en Opus 4.8 esa combinación era válida. A eso conviene sumar una tercera comprobación: los rechazos de los clasificadores llegan como HTTP 200 con stop_reason: "refusal", no como error.

    ¿Cómo desactivo el thinking en Claude Opus 5?

    Con thinking: { type: "disabled" }, pero solo puedes hacerlo hasta effort high. Si envías esa configuración con xhigh o max, la petición se rechaza con un 400. Y ojo: la validación se hace petición a petición, así que una llamada posterior que suba el effort se rechazará aunque todas las anteriores hayan funcionado. En la mayoría de casos compensa más bajar a effort medium con el thinking activado, porque en Opus 5 los niveles low y medium rinden bastante mejor de lo que esperarías.

    ¿Sigo necesitando el «revisa tu respuesta antes de contestar» en mis prompts?

    No, y además es contraproducente. Opus 5 verifica su propio trabajo sin que se lo pidas, así que esas instrucciones provocan verificación excesiva: gastas más tokens y añades latencia sin ganar calidad. La recomendación es borrarlas, no reescribirlas. Con la delegación en subagentes el ajuste es distinto: los empujones para forzarla sobran, pero Anthropic recomienda sustituirlos por un límite explícito —en qué escenarios se delega y cuántos subagentes como máximo—, porque Opus 5 delega más que Opus 4.8 por defecto.

    ¿Hay que cambiar algo para aprovechar el prompt caching en Opus 5?

    Nada. El mínimo de tokens necesario para cachear baja de 1024 a 512, así que los prompts que antes eran demasiado cortos para entrar en caché ahora cachean automáticamente, sin tocar código. Si tu carga de trabajo son muchas llamadas cortas con un system prompt repetido, es probable que la factura baje sola tras migrar.

    ¿Puedo mover todo mi tráfico de Opus 4.x a Opus 5 de golpe?

    Técnicamente sí, pero revisa los rate limits antes. Los límites de Opus 5 son un cubo separado del pool combinado de Opus 4.x, de modo que al migrar no heredas la cuota que ya tenías asignada. Si mueves un volumen alto sin comprobarlo, puedes empezar a recibir throttling con un código que hasta ese momento no lo veía nunca.

    Por Bezael Pérez — Developer senior con más de 15 años de experiencia y fundador de Dominicode.

  • Claude API: Crash Course para developers con TypeScript

    Claude API: Crash Course para developers con TypeScript

    Hace unos meses un developer me escribió frustrado. Llevaba dos días intentando integrar Claude en su app. No le funcionaba el streaming, no entendía por qué sus respuestas llegaban cortadas, y había probado tres ejemplos distintos de Stack Overflow que usaban versiones diferentes del SDK.

    El problema no era la API. Era que había empezado por el medio.

    Esta es la Claude API introducción que yo habría querido tener al principio: sin rodeos, con código real, y con el orden correcto para entender qué está pasando antes de que algo falle.

    Qué es la Claude API y por qué te importa

    Claude es el modelo de lenguaje de Anthropic. La API te da acceso directo a ese modelo desde tu código: puedes enviarle mensajes, pedirle que razone, que use herramientas externas, que responda en streaming o que procese imágenes.

    La diferencia respecto a ChatGPT para developers es principalmente la calidad del razonamiento en tareas de código complejas y el system prompt — Claude lo sigue con una precisión que cambia cómo construyes agentes.

    Setup: API key y SDK

    Primero necesitas una cuenta en console.anthropic.com. Una vez dentro, ve a API Keys y genera una nueva clave. Guárdala — no la vuelves a ver.

    Instala el SDK oficial con npm o Bun:

    npm install @anthropic-ai/sdk
# o con Bun
bun add @anthropic-ai/sdk

    Guarda la clave en una variable de entorno. Nunca en el código:

    # .env
ANTHROPIC_API_KEY=sk-ant-...

    Tu primera llamada en TypeScript

    Este es el "Hello World" de la Claude API. Sin clases, sin abstracción, directo al grano:

    import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic({
  apiKey: process.env.ANTHROPIC_API_KEY,
});

async function main() {
  const response = await client.messages.create({
    model: "claude-sonnet-4-6",
    max_tokens: 1024,
    messages: [
      {
        role: "user",
        content: "Explica qué es un closure en JavaScript en 2 líneas.",
      },
    ],
  });

  console.log(response.content[0].type === "text" ? response.content[0].text : "");
}

main();

    Eso es todo. Ejecutas esto y tienes una respuesta de Claude en tu terminal.

    Lo que necesitas entender de la estructura:

    • model — qué versión de Claude usas (más sobre esto abajo)
    • max_tokens — límite de tokens en la respuesta (no el total de la conversación)
    • messages — array de turnos de conversación con role: "user" o role: "assistant"

    Los conceptos que no puedes ignorar

    Modelos disponibles

    Anthropic tiene tres familias activas:

    Modelo Cuándo usarlo
    claude-sonnet-4-6 El equilibrio perfecto: velocidad + calidad. Mi default para casi todo.
    claude-haiku-4-5 Más rápido y barato. Bueno para tareas simples o llamadas en volumen.
    claude-opus-4-8 El más potente. Para tareas de razonamiento complejo donde el coste no es el problema.

    Si estás empezando, usa claude-sonnet-4-6. No pienses más.

    System prompt vs User message

    El system es la personalidad y las instrucciones permanentes de Claude. El user es lo que cambia en cada turno.

    const response = await client.messages.create({
  model: "claude-sonnet-4-6",
  max_tokens: 1024,
  system: "Eres un reviewer de código senior. Responde siempre en español. Sé directo y señala el problema antes de proponer la solución.",
  messages: [
    {
      role: "user",
      content: "Revisa esta función: function add(a, b) { return a - b; }",
    },
  ],
});

    El system prompt es donde ocurre la mayor parte de la magia cuando construyes agentes. Si quieres ver cómo llevamos esto a proyectos reales con Claude Code, en el curso Construye con IA cubrimos exactamente eso: de la idea al producto con agentes que siguen instrucciones de producción.

    Tokens: lo que cuesta dinero

    Un token es aproximadamente 0,75 palabras en inglés (algo menos en español). La API te cobra por input_tokens (lo que envías) y output_tokens (lo que Claude responde).

    Después de cada llamada puedes ver el uso:

    console.log(response.usage);
// { input_tokens: 48, output_tokens: 312 }

    max_tokens limita la respuesta, no la llamada completa. Si pones max_tokens: 100 y la respuesta necesita 200 tokens, Claude cortará el texto a mitad. Es uno de los errores más comunes al empezar.

    ¿Cómo implementar streaming con la Claude API en TypeScript?

    Sin streaming, esperas a que Claude termine de generar toda la respuesta antes de recibirla. Con streaming, recibes los tokens a medida que se generan — igual que ves escribir a Claude en el chat web.

    Para UX en tiempo real, el streaming no es opcional. Es lo que distingue una app que se siente viva de una que "se congela" tres segundos antes de mostrar algo. En los proyectos de agentes que construimos en Labs, migrar de llamada síncrona a streaming eliminó la necesidad de un loader — los usuarios percibieron la respuesta como inmediata sin que cambiáramos nada más.

    import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic({
  apiKey: process.env.ANTHROPIC_API_KEY,
});

async function streamResponse() {
  const stream = await client.messages.create({
    model: "claude-sonnet-4-6",
    max_tokens: 1024,
    stream: true,
    messages: [
      {
        role: "user",
        content: "Escribe un test unitario en TypeScript para una función que suma dos números.",
      },
    ],
  });

  for await (const event of stream) {
    if (
      event.type === "content_block_delta" &&
      event.delta.type === "text_delta"
    ) {
      process.stdout.write(event.delta.text);
    }
  }

  console.log("\n--- Stream completado ---");
}

streamResponse();

    El loop for await itera sobre los eventos del stream. El tipo que te importa es content_block_delta con delta.type === "text_delta" — ahí está el texto.

    ¿Qué es el tool use en Claude API y cómo funciona?

    Tool use (o function calling) permite que Claude llame a funciones definidas por ti. Claude decide cuándo usarlas y con qué argumentos. Tú ejecutas la función y le devuelves el resultado.

    El siguiente ejemplo define una herramienta get_weather ficticia:

    const response = await client.messages.create({
  model: "claude-sonnet-4-6",
  max_tokens: 1024,
  tools: [
    {
      name: "get_weather",
      description: "Obtiene el tiempo actual para una ciudad.",
      input_schema: {
        type: "object",
        properties: {
          city: {
            type: "string",
            description: "El nombre de la ciudad.",
          },
        },
        required: ["city"],
      },
    },
  ],
  messages: [
    {
      role: "user",
      content: "¿Qué tiempo hace en Madrid ahora mismo?",
    },
  ],
});

// Si Claude quiere usar la herramienta, el stop_reason será "tool_use"
if (response.stop_reason === "tool_use") {
  const toolUse = response.content.find((b) => b.type === "tool_use");
  console.log("Claude quiere llamar a:", toolUse?.name);
  console.log("Con argumentos:", toolUse?.input);
  // Aquí ejecutarías la función real y devolverías el resultado a Claude
}

    Esto es la base de cualquier agente. Claude no ejecuta código — tú lo ejecutas y le informas del resultado. El loop de razonamiento lo controla Claude; la ejecución la controlas tú. Si quieres ver cómo este patrón escala a un pipeline completo — desde un ticket de Jira hasta el deploy —, tienes el ejemplo en el post sobre automatizar el proceso de desarrollo con IA.

    Errores comunes al empezar

    Rate limits. La API tiene límites por minuto tanto en requests como en tokens. Si los golpeas, recibes un 429. Solución: exponential backoff o usar Haiku para prototipos de alto volumen.

    Context window agotado. Cada modelo tiene un límite de tokens totales en conversación (input + output). Sonnet 4.6 tiene 200K tokens de context window — es enorme, pero si metes archivos enteros en cada llamada, lo llenas. Sé selectivo con lo que incluyes en el contexto.

    Formato de mensajes incorrecto. El array messages debe alternar user y assistant. No puedes tener dos mensajes de user seguidos sin un assistant entre medias. Eso devuelve un error 400.

    max_tokens demasiado bajo. Si la respuesta se corta, sube max_tokens. El valor por defecto no existe — es un parámetro obligatorio. Empieza con 1024 y ajusta según lo que necesites.

    Variables de entorno no cargadas. Si ves AuthenticationError, casi siempre es que ANTHROPIC_API_KEY no está disponible en el proceso. Verifica con console.log(process.env.ANTHROPIC_API_KEY) antes de depurar nada más.

    Qué explorar después

    Una vez tienes la llamada básica y el streaming funcionando, estos son los siguientes pasos lógicos:

    Vision. Puedes enviar imágenes en el array content y Claude las analiza. Útil para screenshots, diagramas, facturas.

    Embeddings. Anthropic no tiene embeddings propios en la API, pero Claude funciona muy bien combinado con embeddings de OpenAI o Cohere para búsqueda semántica.

    Batch API. Para procesar cientos de prompts sin necesidad de respuesta en tiempo real. Hasta un 50% más barato que llamadas individuales.

    Workbench de Anthropic. En console.anthropic.com tienes un playground para probar prompts, comparar modelos y ver el uso de tokens antes de escribir una sola línea de código. Es la herramienta que más uso al diseñar system prompts.

    Multiturno real. Construir una conversación que mantenga contexto entre turnos requiere gestionar el array messages manualmente — añadir cada respuesta de Claude como role: "assistant" y cada input del usuario como role: "user". No hay estado en la API.

    Si quieres ver tool use aplicado a un workflow de code review automático antes de un PR, tienes el flujo completo en el post sobre agentic code review con Claude Code.

    Si tuvieras que elegir solo un área para explorar después del streaming, elige Vision — es el salto de ROI más rápido y el que más impacto tiene en una demo.

    FAQ

    ¿Necesito tarjeta de crédito para empezar?
    Sí. Anthropic requiere un método de pago para activar la API, pero tiene un tier de prueba con crédito gratuito. Puedes hacer cientos de llamadas de desarrollo sin pagar nada en los primeros días.

    ¿Cuál es la diferencia entre la API de Claude y Claude.ai?
    Claude.ai es el producto de consumo (el chat web). La API es el acceso programático al modelo. Tienen facturación y cuentas separadas. Una suscripción a Claude.ai no te da acceso a la API.

    ¿Cuánto cuesta en producción?
    Depende del modelo y el volumen. Claude Sonnet 4.6 está alrededor de $3 por millón de input tokens y $15 por millón de output tokens — verifica siempre en anthropic.com/pricing antes de hacer estimaciones de arquitectura, los precios se actualizan con cada generación de modelo.

    ¿Puedo usar la API en el frontend directamente?
    Técnicamente sí, pero nunca deberías. La API key quedaría expuesta en el cliente. Siempre llama a la API desde un backend o un serverless function que tú controlas.

    ¿Qué pasa si Claude no termina la respuesta y stop_reason no es end_turn?
    Si stop_reason es max_tokens, la respuesta se cortó por el límite que pusiste. Si es tool_use, Claude quiere ejecutar una herramienta. Si es stop_sequence, alcanzó una secuencia de parada que definiste. Valida siempre stop_reason en producción.

    Si quieres ver todo esto aplicado en un proyecto real — no en ejemplos de tutorial sino en un producto con usuarios — en Dominicode Labs tenemos el código de los proyectos que construimos en directo, incluyendo agentes con tool use y streaming. Es donde llevamos la teoría a producción.

    Y si prefieres el formato video con más ejemplos en directo, en el canal de YouTube de Dominicode cubrimos estas integraciones con frecuencia.

    Por Bezael Pérez — Developer senior con más de 15 años de experiencia y fundador de Dominicode.