Forem: Roobia

Guía para Pruebas de Servidor MCP: Manuales y Automatizadas con Apidog

Roobia — Mon, 11 May 2026 08:54:38 +0000

Una publicación de Show HN titulada “Ableton Live MCP” alcanzó 118 puntos y 78 comentarios a principios de esta semana. El patrón ya es familiar: alguien escribió un servidor de Protocolo de Contexto de Modelo (MCP) para una herramienta poco probable, la comunidad de Claude Desktop lo probó y aparecieron más preguntas del tipo “¿debería escribir uno para X?”. MCP pasó de ser un experimento de Anthropic a una capa de integración de agentes en menos de un año.

Prueba Apidog hoy

Ese crecimiento deja un problema práctico: probar servidores MCP sigue siendo incómodo. Ejecutar JSON-RPC sobre stdio a mano funciona para un “hola mundo”, pero se rompe cuando el servidor tiene 12 herramientas, 3 prompts y una API ascendente inestable. Esta guía muestra cómo probar servidores MCP manualmente y cómo automatizar esas pruebas con Apidog, tratando el servidor como cualquier otra API: con contrato, mocks y regresión en CI.

Si viene de un contexto de agentes más general, nuestra guía agents.md combina bien con esto; las convenciones allí facilitan comunicar contratos de servidores MCP dentro del equipo.

TL;DR

MCP es el Protocolo de Contexto de Modelo de Anthropic. Usa JSON-RPC 2.0 sobre stdio o HTTP y expone herramientas, recursos y prompts.
Probar un servidor MCP implica verificar llamadas como initialize, tools/list, tools/call, resources/read y prompts/get.
Empiece manualmente: ejecute el servidor desde la terminal, confirme respuestas y corrija errores de forma.
Automatice después: capture tráfico JSON-RPC en Apidog, guarde cada llamada, añada aserciones y ejecute el conjunto en CI.
Use mocks de Apidog para simular APIs ascendentes y mantener pruebas deterministas.
Descargue Apidog para centralizar solicitudes, mocks y ejecución de pruebas.

Qué es MCP realmente

La especificación del Protocolo de Contexto de Modelo define una interfaz JSON-RPC 2.0. Un cliente, como Claude Desktop, Cursor o un agente propio, inicia un servidor MCP, ejecuta un handshake initialize y luego envía llamadas.

Las llamadas que más debería probar son:

initialize: negocia versión y capacidades.
tools/list: devuelve herramientas disponibles y sus argumentos mediante JSON Schema.
tools/call: invoca una herramienta por nombre.
resources/list y resources/read: exponen contenido direccionable por URI.
prompts/list y prompts/get: exponen plantillas de prompts renderizables.

El transporte puede ser:

stdio: tramas JSON-RPC delimitadas por nueva línea en stdin/stdout.
HTTP transmitible: normalmente POST / con SSE para streaming.

La mayoría de servidores locales usan stdio; los remotos suelen usar HTTP.

El motivo para probarlo bien es simple: si tools/list cambia de forma o devuelve un esquema inválido, todos los clientes MCP pueden romperse al mismo tiempo.

Qué debería probar en un servidor MCP

Un conjunto de pruebas útil cubre seis áreas.

1. Conformidad del protocolo

Verifique que initialize devuelve el protocolVersion esperado y que las capacidades anunciadas coinciden con lo que el servidor soporta.

Ejemplo de aspectos a validar:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2026-04-01",
    "capabilities": {}
  }
}

2. Corrección del esquema

Para cada herramienta en tools/list, valide que exista:

name
description
inputSchema

También confirme que inputSchema sea JSON Schema válido y que los campos requeridos estén definidos correctamente.

Las descripciones vacías o demasiado genéricas dificultan la selección de herramientas por parte de clientes como Claude.

3. Comportamiento de herramientas

Para cada tools/call, valide que la respuesta tenga bloques de contenido correctos:

{
  "content": [
    {
      "type": "text",
      "text": "Resultado"
    }
  ]
}

También pruebe errores esperados. En MCP, un fallo de ejecución de herramienta debería devolver un resultado normal con isError: true, no un error JSON-RPC de protocolo.

{
  "isError": true,
  "content": [
    {
      "type": "text",
      "text": "Falta el argumento requerido: city"
    }
  ]
}

4. Acceso a recursos

Compruebe que cada URI devuelta por resources/list se puede leer con resources/read.

También pruebe paginación si su servidor devuelve recursos en varias páginas.

5. Renderizado de prompts

Valide que prompts/get devuelve arrays messages bien formados y que los argumentos se sustituyen en el lugar correcto.

6. Modos de fallo

Pruebe escenarios que ocurren en producción:

API ascendente caída.
Argumento requerido ausente.
Tipo de argumento inválido.
Timeout.
Respuestas incompletas.
Errores concurrentes.

Pruebas manuales con `stdio`

Empiece con la ruta más simple: terminal, binario del servidor y JSON-RPC.

Si todavía no tiene un servidor, puede crear uno con el inicio rápido oficial del SDK de MCP en Python o TypeScript. El ejemplo de clima con dos herramientas es suficiente para practicar.

Ejecute el servidor con el inspector oficial:

npx @modelcontextprotocol/inspector node your-server.js

El inspector abre una UI local que habla con su servidor vía MCP. Úselo para confirmar:

El proceso arranca.
initialize responde.
Las capacidades se anuncian.
tools/list devuelve herramientas.
tools/call responde con contenido válido.

Cuando el flujo funcione en el inspector, capture llamadas JSON-RPC sin procesar.

Ejemplo con stdio:

echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2026-04-01","capabilities":{}}}' | node your-server.js

Guarde la solicitud y la respuesta. Repita con:

tools/list
tools/call
resources/list
resources/read
prompts/list
prompts/get

Al final tendrá entre 6 y 12 pares solicitud-respuesta que definen el contrato básico de su servidor MCP.

Dos detalles importantes

Primero, los bloques de contenido pueden mezclar tipos:

{
  "content": [
    {
      "type": "text",
      "text": "Resumen"
    },
    {
      "type": "image",
      "data": "...",
      "mimeType": "image/png"
    }
  ]
}

Segundo, no confunda errores de herramienta con errores de protocolo. Si una herramienta falla por un input inválido, devuelva isError: true. Reserve errores JSON-RPC para fallos del protocolo.

De manual a automatizado con Apidog

Las pruebas manuales sirven para encontrar errores obvios. La automatización sirve para responder: “¿mi último cambio rompió el contrato?”.

El flujo recomendado:

Capture solicitudes y respuestas MCP.
Cree un proyecto en Apidog.
Guarde cada llamada JSON-RPC como una solicitud.
Añada aserciones.
Simule APIs ascendentes con mocks.
Ejecute el conjunto en CI.

1. Cree un proyecto de Apidog para su servidor MCP

Abra Apidog y cree un proyecto nuevo.

Si su servidor MCP expone HTTP, configure la URL base del endpoint MCP.

Si su servidor usa solo stdio, ejecútelo detrás de un wrapper HTTP ligero durante pruebas. El inspector oficial incluye opciones para este flujo. También puede crear un script Node que reciba JSON-RPC por HTTP y lo reenvíe al proceso por stdio.

El mismo patrón se usa en pruebas de API sin Postman en 2026 para backends no HTTP.

2. Guarde solicitudes canónicas

Cree una solicitud guardada por cada llamada relevante:

initialize
tools/list
tools/call
resources/list
resources/read
prompts/list
prompts/get

Ejemplo de cuerpo para tools/call:

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "tools/call",
  "params": {
    "name": "get_weather",
    "arguments": {
      "city": "Tokyo"
    }
  }
}

Mantenga IDs estables en pruebas para facilitar depuración.

3. Añada aserciones

La parte importante no es enviar la solicitud, sino validar la respuesta.

Para tools/list, añada aserciones como:

$.result.tools existe.
$.result.tools.length es mayor que 0.
Cada herramienta tiene name.
Cada herramienta tiene description.
Cada herramienta tiene inputSchema.
Cada inputSchema es válido.

Para tools/call con entrada correcta:

$.result.isError es false o no existe.
$.result.content es un array.
$.result.content[0].type tiene el valor esperado.
$.result.content[0].text existe si el tipo es text.

Para tools/call con entrada inválida:

$.result.isError es true.
$.result.content[0].text contiene un mensaje útil.
No se devuelve un error JSON-RPC de protocolo si el fallo es de validación de herramienta.

Ejemplo de respuesta esperada para entrada inválida:

{
  "jsonrpc": "2.0",
  "id": 43,
  "result": {
    "isError": true,
    "content": [
      {
        "type": "text",
        "text": "Falta el argumento requerido: city"
      }
    ]
  }
}

Apidog almacena las aserciones por solicitud y muestra los fallos en el reporte de ejecución.

4. Simule APIs ascendentes con mocks

Muchos servidores MCP envuelven APIs externas:

Clima.
GitHub.
Linear.
Notion.
Bases de datos internas.
Servicios internos.

No conviene que CI golpee esas APIs en cada commit. Introduce latencia, límites de uso y fallos no deterministas.

Con el servidor de mocks de Apidog puede definir endpoints ascendentes simulados y devolver respuestas JSON realistas.

Flujo práctico:

Defina cada endpoint ascendente como una ruta mock.
Configure el servidor MCP para usar la URL del mock en pruebas.
Mantenga la URL real solo para staging o producción.
Regrabe fixtures cuando la API real cambie.

Este enfoque se cubre también en desarrollo de API contract-first.

Resultado: pruebas rápidas, sin red externa y con fallos reproducibles.

5. Ejecute el conjunto en CI

Los proyectos de Apidog se pueden ejecutar desde CLI. El comando apidog run ejecuta solicitudes guardadas, evalúa aserciones y devuelve un código distinto de cero si algo falla.

Ejemplo mínimo con GitHub Actions:

name: MCP server tests

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: 22

      - run: npm ci

      - name: Start MCP HTTP wrapper
        run: node test/wrapper.js &

      - name: Run Apidog suite
        run: npx apidog run --project-id $APIDOG_PROJECT --env ci
        env:
          APIDOG_PROJECT: ${{ secrets.APIDOG_PROJECT }}
          APIDOG_TOKEN: ${{ secrets.APIDOG_TOKEN }}

Con esto, cada push ejecuta el contrato MCP completo. Si una herramienta cambia su esquema, CI lo detecta antes del merge.

Cómo se ve una buena cobertura

Un plan de pruebas para un servidor MCP en Apidog suele incluir:

1 solicitud initialize con aserciones de versión y capacidades.
1 solicitud tools/list con aserciones de forma y JSON Schema.
De 2 a 4 solicitudes tools/call por herramienta:
- ruta feliz;
- argumento faltante;
- tipo inválido;
- error ascendente.
1 resources/list.
1 resources/read por familia de recursos.
1 prompts/list.
1 prompts/get por plantilla.

Para un servidor con 10 herramientas, 3 recursos y 4 prompts, el conjunto puede tener entre 50 y 70 solicitudes.

Errores comunes al probar MCP

Saltarse `initialize`

Algunos servidores construyen el registro de herramientas durante initialize. Si ejecuta tools/list directamente, puede obtener falsos negativos.

Ejecute siempre:

initialize
tools/list
llamadas específicas

Afirmar cadenas de error exactas

Los mensajes de error cambian. Es mejor afirmar:

isError: true
un código estable, si existe;
una expresión regular;
la presencia de campos clave.

Dejar que el mock se desvíe de producción

Un mock incorrecto produce pruebas verdes para una integración rota. Regrabe fixtures a partir de respuestas reales cuando cambie la API ascendente.

Olvidar streaming

Los servidores MCP por HTTP pueden transmitir resultados mediante SSE. Si su endpoint usa streaming, habilítelo en la solicitud de prueba y valide el flujo ensamblado.

No probar concurrencia

Los clientes MCP pueden enviar varias llamadas tools/call en paralelo. Si su servidor comparte estado mutable, una prueba secuencial puede pasar mientras producción falla.

Añada pruebas paralelas para herramientas críticas.

Mezclar errores de protocolo y de herramienta

MCP separa esos errores a propósito. Si una herramienta falla, devuelva isError: true. Si el mensaje JSON-RPC está mal formado, use error de protocolo.

Este tipo de problema de contrato también aparece en desarrollo contract-first de plataforma API.

Casos de uso reales

Un equipo que construía un servidor MCP interno para una API de gestión de incidentes detectó tres regresiones en una semana usando aserciones sobre tools/list. Sin esas pruebas, los errores habrían llegado a todos los usuarios internos de Claude Desktop al mismo tiempo.

Un desarrollador que mantiene un servidor MCP open source para Notion usa mocks de Apidog para ejecutar pruebas sin alcanzar límites de velocidad durante CI. El conjunto se ejecuta en cada PR, tarda pocos segundos y permite colaborar sin acceso directo a la API real.

Un equipo de plataforma con 14 servidores MCP internos creó un workspace compartido en Apidog. Cada contrato vive en el mismo lugar, los servidores nuevos heredan una base de pruebas y los revisores comparan cambios de esquema antes de fusionar.

Otro equipo que construye un servidor MCP para una plataforma interna de observabilidad usa entornos de Apidog para ejecutar el mismo conjunto contra staging y producción. Cambia fixtures y URLs por entorno, pero conserva las mismas aserciones.

Conclusión

MCP creció rápido, pero las pruebas todavía suelen ser manuales y frágiles. La solución es tratar su servidor MCP como una API JSON-RPC: definir contrato, simular dependencias y ejecutar regresión en CI.

Puntos clave:

Un servidor MCP es una API JSON-RPC; pruébelo con el mismo rigor que una API REST.
Empiece con el inspector oficial y capture solicitudes canónicas.
Automatice en Apidog con solicitudes guardadas, aserciones, mocks y CI.
Cubra protocolo, esquema, herramientas, recursos, prompts y fallos.
Use mocks para mantener pruebas rápidas y deterministas.

Siguiente paso: abra Apidog, cree un proyecto, pegue las solicitudes MCP capturadas, añada aserciones JSONPath para tools/list y ejecute el conjunto. En menos de una hora sabrá si el contrato de su servidor está listo para enviarse.

Preguntas frecuentes

¿Qué es MCP?

MCP, el Protocolo de Contexto de Modelo, es la especificación abierta de Anthropic para que clientes de IA, como Claude Desktop, llamen herramientas, recursos y prompts externos. Usa JSON-RPC 2.0 sobre stdio o HTTP transmitible. La especificación completa de MCP está publicada en modelcontextprotocol.io.

¿Puedo probar un servidor MCP sin wrapper HTTP?

Sí. El inspector oficial de MCP se comunica directamente con stdio y ofrece una UI para pruebas manuales.

Para automatizar en Apidog, use un wrapper HTTP ligero durante CI. El tráfico de producción puede seguir usando stdio.

¿Cómo simulo APIs ascendentes?

Defina cada endpoint ascendente como un mock en Apidog, configure el servidor MCP para apuntar al mock durante pruebas y cambie a URLs reales en producción. El mismo patrón se explica en herramientas de prueba de API para ingenieros de control de calidad.

¿Qué pasa con resultados de herramientas en streaming?

Los servidores MCP HTTP pueden transmitir resultados mediante Server-Sent Events (SSE). Apidog admite SSE en solicitudes guardadas; actívelo en la configuración de la solicitud y valide el flujo ensamblado.

¿Debo probar la versión del protocolo?

Sí. Fije el protocolVersion soportado en initialize y añada una aserción. Las discrepancias pueden causar incompatibilidades silenciosas con clientes MCP.

¿Puedo probar con Claude Desktop real?

Sí, y debería hacerlo como prueba de humo antes de cada lanzamiento. Pero no lo use como bucle principal de regresión: es manual, lento y no determinista. Use Apidog para automatización y Claude Desktop para validación final.

¿Dónde puedo ver ejemplos reales de servidores MCP?

El repositorio oficial de servidores MCP incluye implementaciones para sistemas de archivos, GitHub, Slack, Postgres y más. Revise sus definiciones de herramientas para entender cómo debería verse una forma MCP bien diseñada.

Qué es Maigret: Escáner OSINT Que No Se Rompe

Roobia — Mon, 11 May 2026 06:09:51 +0000

La mayoría de las herramientas OSINT envejecen rápido: la web cambia, los sitios mueven rutas, los captchas evolucionan y muchas herramientas dejan de funcionar en pocos años. Maigret es una excepción: lleva años funcionando, soporta más de 3.000 sitios, ofrece paquete de Python, bot de Telegram e interfaz web. Más importante aún: su arquitectura muestra cómo construir un escáner basado en firmas que resiste cambios constantes en sitios externos.

Prueba Apidog hoy

Esta guía está pensada para ingenieros. Verás qué hace Maigret, cuándo tiene sentido usarlo de forma legítima, cómo escala a miles de sitios y cómo aplicar sus patrones —firmas, aserciones multi-señal, detección de deriva y verificación recurrente— a pruebas de API con Apidog.

Si aún no lo has leído, nuestra publicación Pruebas de API sin Postman en 2026 cubre ideas similares de coincidencia de patrones y detección de desviación en un ámbito más amigable.

En resumen

Maigret busca cuentas públicas asociadas a un nombre de usuario en más de 3.000 sitios.
Su arquitectura se basa en una base de datos de firmas versionada, búsqueda recursiva, detección de deriva y manejo parcial de captchas.
Sus usos legítimos incluyen OSINT autorizado, recuperación de cuentas propias, auditorías de seguridad, protección de marca y apoyo a investigaciones formales.
Usarlo contra personas privadas sin consentimiento puede constituir acoso o acecho según la jurisdicción.
Los mismos patrones técnicos se aplican directamente a pruebas de API: contratos, fixtures, aserciones multi-señal y monitoreo programado.
Puedes implementar estos patrones en Apidog para validar APIs de forma más robusta.

Qué es y qué no es Maigret

Maigret es una herramienta de Python con licencia MIT mantenida por soxoj. Su objetivo, según el README, es recopilar un expediente público sobre una persona a partir de un nombre de usuario en más de 3.000 sitios.

Instalación básica:

pip install maigret

Ejecución mínima:

maigret nombre_usuario

Esto consulta los sitios definidos en su base de datos, detecta posibles perfiles públicos y genera un informe con los datos encontrados.

Tres puntos importantes:

Solo usa datos públicos.

No inicia sesión, no reutiliza credenciales y no usa claves privadas. Si un perfil es visible para visitantes anónimos, Maigret puede leerlo. Si no, devuelve un resultado negativo, desconocido o bloqueado.
Se usa en contextos legítimos.

Periodistas, equipos antifraude, equipos de protección de marca, investigadores OSINT y equipos de red-team autorizados lo utilizan como parte de flujos de trabajo formales.
Puede ser mal utilizado.

Ejecutarlo contra una persona privada sin consentimiento puede cruzar límites éticos y legales. Antes de usarlo, valida autorización, jurisdicción y alcance.

Este artículo se centra en la ingeniería detrás de Maigret y en cómo reutilizar sus patrones en pruebas de API.

La base de datos de firmas de sitios

La parte más interesante de Maigret es su base de datos de firmas. Cada entrada describe cómo validar un sitio:

URL base del perfil.
Patrón de URL del usuario.
Cadenas que indican que el perfil existe.
Cadenas que indican que el perfil no existe.
Reglas de extracción de datos.
Cabeceras opcionales.
Etiquetas de país, categoría o comportamiento.
Señales de captcha o limitación de tasa.

La base de datos está en JSON, versionada en GitHub y se actualiza automáticamente cada 24 horas cuando se ejecuta la herramienta. Si un sitio cambia y los mantenedores corrigen la firma, las instalaciones activas reciben la actualización sin reinstalar.

El patrón es aplicable directamente a APIs.

En vez de codificar pruebas aisladas por endpoint, define firmas de comportamiento:

{
  "endpoint": "GET /users/{id}",
  "expectedStatus": 200,
  "requiredHeaders": ["content-type"],
  "bodyMustContain": ["id", "email", "createdAt"],
  "bodyMustNotContain": ["password", "internalToken"]
}

Para un proyecto con decenas o cientos de endpoints, este enfoque permite:

Validar contratos como datos.
Versionar expectativas.
Compartir reglas entre equipos.
Detectar cambios de forma más rápido.

También es la base del desarrollo de API contract-first y del libro de jugadas de pruebas de servidor MCP.

Cómo Maigret detecta “usuario encontrado” vs. “usuario no encontrado”

Un escáner simple haría esto:

GET https://example.com/user/<username>

Y después comprobaría el código de estado.

Eso falla con frecuencia porque muchos sitios devuelven 200 OK incluso cuando el usuario no existe. Otros devuelven páginas genéricas, páginas cacheadas o desafíos de captcha.

Maigret usa reglas más específicas por sitio:

urlMain
url
presenseStrs
absenceStrs
expresiones regulares de extracción
cabeceras personalizadas
etiquetas

Un resultado “encontrado” requiere que las cadenas de presencia aparezcan y que las cadenas de ausencia no aparezcan. Un resultado “no encontrado” requiere lo contrario. Si las señales no son concluyentes, el resultado queda como desconocido.

Ejemplo conceptual:

{
  "name": "ExampleSite",
  "url": "https://example.com/{username}",
  "presenseStrs": ["Profile", "Followers"],
  "absenceStrs": ["User not found", "This account does not exist"]
}

El equivalente en pruebas de API es no confiar solo en el status code.

Una prueba más robusta debe validar:

código HTTP;
estructura del cuerpo;
campos obligatorios;
ausencia de campos sensibles;
cabeceras esperadas;
valores de error.

Ejemplo:

{
  "status": 200,
  "body": {
    "id": "usr_123",
    "email": "dev@example.com"
  }
}

Aserciones recomendadas:

status == 200
body.id exists
body.email matches email format
body.password does not exist
headers.content-type contains application/json

Apidog permite combinar aserciones de estado, cuerpo y cabeceras en una misma solicitud, equivalente a las señales de presencia y ausencia que usa Maigret.

Búsqueda recursiva y extracción de información

Cuando Maigret encuentra una cuenta, no se detiene ahí. También intenta extraer identificadores públicos adicionales:

correos electrónicos;
teléfonos;
nombres reales;
otros nombres de usuario;
enlaces a perfiles externos.

Después puede reutilizar esos identificadores como nuevas entradas de búsqueda. Ese flujo convierte una coincidencia inicial en una exploración recursiva de perfiles relacionados.

En APIs ocurre algo similar.

Si un endpoint devuelve un campo no documentado:

{
  "id": "ord_123",
  "customerId": "cus_456",
  "paymentIntentId": "pi_789"
}

Ese campo puede indicar:

un endpoint relacionado;
una dependencia descendente;
una entidad no documentada;
un caso de prueba faltante.

Flujo práctico:

Ejecuta una solicitud base.
Detecta campos nuevos o no documentados.
Busca endpoints que consumen esos campos.
Añade casos de prueba para esos endpoints.
Actualiza el contrato.

Este patrón convierte las respuestas reales en entradas para ampliar la cobertura de pruebas.

Manejo de captcha y límite de tasa

Maigret no intenta romper defensas agresivas. Detecta señales de captcha o rate limiting y actúa de forma conservadora.

Sus estrategias incluyen:

rotar user agents;
respetar cabeceras de reintento;
usar dominios móviles o simplificados cuando existen;
enrutar mediante Tor o I2P cuando el sitio lo permite;
marcar resultados como “captcha detectado” cuando no puede continuar.

La lección para APIs es clara: tus pruebas no deben forzar sistemas externos.

Implementa clientes de prueba que detecten:

HTTP/1.1 429 Too Many Requests
Retry-After: 60

Y respondan con backoff:

async function requestWithBackoff(fn, retries = 3) {
  for (let attempt = 0; attempt < retries; attempt++) {
    const response = await fn();

    if (response.status !== 429) {
      return response;
    }

    const retryAfter = Number(response.headers.get("retry-after") || 2);
    await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
  }

  throw new Error("Rate limit exceeded after retries");
}

Esto evita falsos negativos, bloqueos de IP y ruido en proveedores externos.

El problema de la deriva de firmas

Una base de datos de 3.000 sitios solo sirve si se mantiene actualizada. Los sitios cambian:

rutas de perfil;
HTML;
textos de error;
reglas anti-bot;
nombres de marca;
dominios.

Una firma obsoleta produce:

falsos negativos;
falsos positivos;
resultados desconocidos;
pérdida de confianza en la herramienta.

Maigret mitiga esto con varias capas:

actualización automática desde GitHub cada 24 horas;
contribuciones de la comunidad;
bandera manual --update;
pruebas de firmas contra usuarios conocidos y autorizados.

Ejemplo:

maigret --update nombre_usuario

El punto más importante es el arnés de pruebas: para cada sitio, Maigret puede validar una firma contra un usuario existente conocido. Si esa validación falla, la firma probablemente derivó.

En pruebas de API, el equivalente es guardar una respuesta buena conocida como fixture y compararla periódicamente contra el endpoint real.

Flujo recomendado:

Define el contrato esperado.
Guarda una respuesta válida conocida.
Ejecuta la prueba de forma programada.
Compara estructura, tipos y campos.
Alerta si aparece deriva.

Apidog soporta este patrón: puedes guardar respuestas, ejecutar pruebas programadas y detectar cambios en endpoints. Nuestra guía de la API DeepSeek V4 muestra el lado manual para un proveedor específico.

El modo de resumen opcional con IA

Maigret incluye la bandera --ai, que usa un endpoint LLM compatible con OpenAI para resumir los hallazgos.

maigret nombre_usuario --ai

La arquitectura es correcta porque separa responsabilidades:

las reglas deterministas deciden si una cuenta coincide;
el LLM solo resume resultados;
la entrada al modelo está restringida;
el modelo no decide el veredicto.

Ese patrón también funciona para reportes de pruebas de API.

Arquitectura recomendada:

Pruebas deterministas → Resultado estructurado → Resumen LLM → Slack / email / reporte

No uses el LLM para decidir si una prueba pasa o falla. Usa reglas explícitas para eso. El modelo puede ayudar a convertir una salida técnica en un resumen legible para equipos no técnicos.

Nuestra publicación sobre uso de computadoras vs APIs estructuradas explica por qué la capa estructurada debe ir primero.

Casos de uso legítimos

Estos son escenarios donde Maigret puede usarse de forma apropiada si existe autorización y alcance claro.

1. Recuperación de cuentas propias

Puedes buscar cuentas antiguas asociadas a un nombre de usuario que usabas años atrás.

Útil para:

auditorías de privacidad;
cierre de cuentas abandonadas;
reducción de huella digital;
limpieza antes de cambios laborales.

2. Monitoreo de abuso de marca

Empresas pueden buscar nombres de marca, productos o dominios para detectar cuentas falsas o suplantación.

Ejemplos:

maigret nombre_marca
maigret producto_empresa

3. Búsqueda de personas desaparecidas

Organizaciones autorizadas pueden usar OSINT con consentimiento familiar y coordinación con autoridades. El trabajo independiente sin coordinación puede perjudicar una investigación.

4. Red-team autorizado

Equipos de pentesting pueden usar Maigret para mapear exposición pública de una organización dentro del alcance definido por contrato.

Regla práctica: si no está en el alcance, no se prueba.

5. Periodismo de investigación

Reporteros pueden usar herramientas OSINT en investigaciones de fraude, crimen organizado o figuras públicas, bajo revisión editorial y legal.

Lo que no entra en esta lista:

buscar a una persona por curiosidad;
vigilar a una expareja;
perfilar a desconocidos;
crear datasets de personas sin consentimiento.

Patrones de Maigret aplicables a pruebas de API

Estos patrones son transferibles a cualquier suite de pruebas de API.

1. Firmas como datos, no como código

Evita codificar todas las expectativas dentro de scripts. Modela el comportamiento esperado como datos versionados.

Ejemplo:

{
  "name": "Get user by ID",
  "method": "GET",
  "path": "/users/{id}",
  "expected": {
    "status": 200,
    "requiredFields": ["id", "email", "createdAt"],
    "forbiddenFields": ["passwordHash", "internalNotes"]
  }
}

2. Aserciones multi-señal

No aceptes una respuesta como válida solo porque devuelve 200.

Valida:

status code;
esquema;
campos obligatorios;
campos prohibidos;
cabeceras;
tipos;
valores de negocio.

3. Firmas sincronizadas

Maigret actualiza firmas desde un repositorio central. En APIs, el equivalente es sincronizar documentación, contratos y pruebas desde una fuente compartida.

Los proyectos de Apidog soportan sincronización en la nube. El flujo completo se cubre en Pruebas de API sin Postman.

4. Detección de desviaciones

Programa ejecuciones periódicas contra endpoints críticos. Compara la respuesta actual contra una respuesta conocida buena.

Ejemplo de diferencia que debería alertar:

 {
   "id": "usr_123",
-  "email": "dev@example.com",
+  "contactEmail": "dev@example.com",
   "createdAt": "2026-05-01T10:00:00Z"
 }

Ese cambio puede parecer pequeño, pero rompe clientes que esperan email.

5. LLM como postprocesador

Usa reglas deterministas para aprobar o fallar. Usa IA solo para explicar.

Ejemplo de salida estructurada:

{
  "failedTests": 3,
  "breakingChanges": [
    "Field email renamed to contactEmail",
    "Endpoint /users/{id} no longer returns createdAt"
  ]
}

Después, un LLM puede convertirlo en:

La API de usuarios introdujo dos cambios incompatibles: el campo email fue renombrado y createdAt ya no aparece en la respuesta. Revisa clientes que consumen GET /users/{id}.

Errores comunes al ejecutar Maigret

Si vas a experimentar con Maigret en entornos autorizados, evita estos errores.

Ejecutar sin `-a` y asumir que el escaneo fue completo

Por defecto, Maigret puede escanear un subconjunto de sitios principales. Para consultar la base completa:

maigret nombre_usuario -a

Esto tarda más, pero cubre la cola larga.

Ignorar etiquetas

Puedes filtrar por país o categoría:

maigret nombre_usuario --tags jp
maigret nombre_usuario --tags social

Esto ayuda cuando el objetivo autorizado tiene contexto regional específico.

No actualizar firmas

Antes de una investigación seria:

maigret --update nombre_usuario

Las firmas antiguas aumentan falsos positivos y falsos negativos.

Usar Tor sin interpretar bloqueos correctamente

Algunos sitios bloquean nodos de salida Tor. Un bloqueo no significa que el usuario exista o no exista. Solo significa que el sitio bloqueó esa ruta.

Tratar los hallazgos como prueba final

Maigret extrae datos públicos. Las páginas pueden contener información falsa, abandonada o fabricada. Trata los resultados como pistas que requieren verificación.

Casos de uso en el mundo real

Una consultora de seguridad puede usar Maigret como primer paso en un ejercicio de red-team autorizado. El resultado ayuda al cliente a visualizar su superficie pública antes de pruebas más profundas.

Un investigador antifraude puede usar --ai para convertir un escaneo amplio en un resumen breve para clientes no técnicos. La búsqueda sigue siendo determinista; el LLM solo redacta.

Un equipo de ingeniería puede aplicar los mismos principios —firmas, fixtures, ejecución programada y detección de deriva— para mantener una suite de pruebas de API en cientos de microservicios usando Apidog.

Conclusión

Maigret es un buen ejemplo de cómo diseñar una herramienta que escala a miles de reglas sin romperse cada vez que cambia una superficie externa. Incluso si nunca haces OSINT, su arquitectura es útil para pruebas de API.

Ideas clave:

Maigret usa una base de datos de firmas versionada y autoactualizable.
La detección multi-señal es más fiable que validar solo códigos de estado.
La deriva rompe herramientas y suites de pruebas si no se monitorea.
Los fixtures conocidos permiten detectar cambios temprano.
Los LLM funcionan mejor como capa de resumen, no como juez.
Los mismos patrones se pueden aplicar en Apidog.

Siguiente paso práctico: revisa el formato de firmas de Maigret y luego modela un endpoint de tu proyecto de la misma forma en Apidog: firma explícita, aserciones multi-señal, fixture guardado y ejecución programada. La primera vez que un proveedor cambie un campo a las 2 a.m., tu suite lo detectará antes que tus usuarios.

Preguntas frecuentes

¿Es legal usar Maigret?

Depende de la jurisdicción y del objetivo. Usarlo en ti mismo, en cuentas que posees, en una empresa para la que tienes autorización escrita o como parte de periodismo autorizado suele ser aceptable. Usarlo contra una persona sin consentimiento puede cruzar leyes de acoso o acecho en la UE, EE. UU., Reino Unido y otras regiones.

¿Funciona Maigret sin Python?

El paquete oficial requiere Python 3.10+. El autor también mantiene un bot de Telegram y una configuración de Cloud Shell para quienes no quieren instalarlo localmente.

¿Qué tan precisa es la cifra de más de 3.000 sitios?

La base de datos lista más de 3.000 entradas, aunque no todas están activas o funcionales en todo momento. La actualización automática y las contribuciones de la comunidad mantienen un subconjunto útil y actualizado.

¿Qué añade el modo IA?

La bandera --ai usa un LLM compatible con OpenAI para resumir hallazgos deterministas. No cambia la búsqueda ni decide coincidencias. Debes proporcionar tu propia clave API.

¿Puedo usar Maigret en CI?

Para investigaciones OSINT, normalmente no: es trabajo interactivo y dependiente de contexto. Lo que sí pertenece a CI son sus patrones arquitectónicos: firmas, fixtures, detección de deriva y reproducción programada. Apidog implementa esos flujos para pruebas de API.

¿En qué se diferencia de Sherlock?

Sherlock es más antiguo y simple. Maigret lo extiende con extracción de información, búsqueda recursiva, manejo parcial de captchas, modo de resumen con IA y una base de datos de sitios más rica. Ambos tienen licencia MIT.

¿Dónde reporto una firma obsoleta?

En los issues o pull requests del repositorio de Maigret en GitHub. La base de datos se mantiene gracias a contribuciones de la comunidad; lo normal es enviar una corrección por sitio obsoleto.

Cómo Solucionar Error 'Invalid custom3p enterprise config' en Código Claude

Roobia — Mon, 11 May 2026 03:31:31 +0000

Si has intentado apuntar Claude Code a DeepSeek V4, OpenRouter u otro proveedor de modelos de terceros, es probable que hayas visto este error: Invalid custom3p enterprise config. El mensaje no explica qué validar ni dónde mirar, pero normalmente se resuelve corrigiendo la URL base, la variable de autenticación o el archivo de configuración.

Prueba Apidog hoy

Esta guía explica qué significa custom3p, cómo depurar el error y qué configuraciones usar para ejecutar el bucle de agente de Claude Code con OpenRouter, LiteLLM o un backend local como vLLM.

En resumen

Invalid custom3p enterprise config significa que Claude Code no puede validar la configuración de un proveedor de terceros.

En Claude Code, custom3p es la etiqueta interna para cualquier endpoint no-Anthropic configurado mediante:

ANTHROPIC_BASE_URL

Las causas más comunes son:

ANTHROPIC_BASE_URL termina en /v1
Estás usando la variable de credencial incorrecta
~/.claude/settings.json tiene JSON inválido
La instalación nueva no completó el onboarding
La pasarela no reenvía encabezados requeridos
Una política empresarial bloquea la configuración

Empieza por la URL base: en la mayoría de casos, eliminar /v1 resuelve el problema.

Qué significa realmente `custom3p`

Claude Code puede enrutar solicitudes en varios modos:

Modo	Cómo se activa
API de Anthropic	Sin anulación configurada
Amazon Bedrock	`CLAUDE_CODE_USE_BEDROCK=1`
Google Vertex AI	`CLAUDE_CODE_USE_VERTEX=1`
Microsoft Foundry	`CLAUDE_CODE_USE_FOUNDRY=1`
Tercero personalizado	`ANTHROPIC_BASE_URL` apunta a otro host

La última opción es custom3p: “custom third-party provider”.

Cuando ANTHROPIC_BASE_URL apunta a LiteLLM, OpenRouter, vLLM, una pasarela corporativa u otro endpoint no-Anthropic, Claude Code ejecuta una validación antes de enviar la primera solicitud real.

Si esa validación falla, muestra:

Invalid custom3p enterprise config

Este error es de configuración. No significa necesariamente que el proveedor esté bloqueado.

Por qué aparece este error ahora

En abril de 2026, Anthropic bloqueó el acceso a suscripciones Claude Pro y Max para herramientas de agentes de terceros que suplantaban la ID de cliente de Claude Code.

Eso es diferente a usar el soporte oficial de Claude Code para proveedores personalizados.

Después de ese cambio, muchos desarrolladores empezaron a enrutar Claude Code a backends más económicos mediante ANTHROPIC_BASE_URL. Por ejemplo, un hilo de Reddit documentó el uso de DeepSeek V4 Pro a través de OpenRouter, con un coste menor por millón de tokens de salida frente a Anthropic. Proyectos como DeepClaude empaquetaron esta configuración en un flujo de un solo comando.

El problema: Claude Code exige que la configuración de proveedor personalizado sea válida. Si falla una URL, una credencial o un encabezado, obtienes Invalid custom3p enterprise config.

Causa raíz 1: `ANTHROPIC_BASE_URL` termina en `/v1`

Este es el fallo más común.

Claude Code añade automáticamente:

/v1/messages

a la URL configurada en ANTHROPIC_BASE_URL.

Si tu URL ya termina en /v1, Claude Code termina llamando a:

/v1/v1/messages

y la pasarela suele responder 404.

Incorrecto

export ANTHROPIC_BASE_URL="https://api.openrouter.ai/api/v1"

export ANTHROPIC_BASE_URL="https://litellm.yourcompany.com/v1"

Correcto

export ANTHROPIC_BASE_URL="https://api.openrouter.ai/api"

export ANTHROPIC_BASE_URL="https://litellm.yourcompany.com"

Verifica el endpoint real

Ejecuta:

curl -s -o /dev/null -w "%{http_code}" \
  -H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" \
  "${ANTHROPIC_BASE_URL}/v1/messages" \
  -d '{"model":"claude-sonnet-4-6","max_tokens":1,"messages":[{"role":"user","content":"hi"}]}'

Interpreta el resultado:

200: el endpoint existe y respondió correctamente
400: el endpoint existe, aunque el body no sea válido para esa pasarela
404: probablemente tienes un problema con /v1

Causa raíz 2: variable de credencial incorrecta

Claude Code puede enviar credenciales de dos formas distintas:

Variable	Encabezado enviado	Cuándo usar
`ANTHROPIC_API_KEY`	`x-api-key`	Pasarelas compatibles con el formato Anthropic
`ANTHROPIC_AUTH_TOKEN`	`Authorization: Bearer`	LiteLLM, OpenRouter y pasarelas estilo OAuth

Si usas la variable incorrecta, la pasarela puede rechazar la solicitud y Claude Code lo reportará como configuración inválida.

OpenRouter

OpenRouter normalmente espera Authorization: Bearer:

export ANTHROPIC_AUTH_TOKEN="sk-or-your-openrouter-key"
export ANTHROPIC_BASE_URL="https://openrouter.ai/api"

No uses ANTHROPIC_API_KEY para OpenRouter si tu configuración espera Bearer tokens.

LiteLLM

export ANTHROPIC_AUTH_TOKEN="sk-litellm-your-virtual-key"
export ANTHROPIC_BASE_URL="https://your-litellm-server:4000"

Pasarela DeepSeek o vLLM con API key

export ANTHROPIC_API_KEY="your-key-here"
export ANTHROPIC_BASE_URL="https://your-vllm-server"

Regla práctica: revisa la documentación de tu pasarela y confirma si espera Authorization: Bearer o x-api-key.

Causa raíz 3: `settings.json` malformado

Si configuras Claude Code desde:

~/.claude/settings.json

un JSON inválido impide que Claude Code lea la configuración.

Error: coma final

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://openrouter.ai/api",
    "ANTHROPIC_AUTH_TOKEN": "sk-or-your-key",
  }
}

Error: comillas inteligentes

{
  "env": {
    “ANTHROPIC_BASE_URL”: “https://openrouter.ai/api”
  }
}

Configuración válida

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://openrouter.ai/api",
    "ANTHROPIC_AUTH_TOKEN": "sk-or-your-openrouter-key"
  }
}

Valida el archivo antes de iniciar Claude Code

Con Python:

python3 -c "import json, os; json.load(open(os.path.expanduser('~/.claude/settings.json')))" && echo "Valid JSON"

O con jq:

jq . ~/.claude/settings.json

Si alguno de estos comandos falla, Claude Code no podrá cargar la configuración.

Causa raíz 4: la instalación nueva no completó el onboarding

Claude Code revisa:

~/.claude.json

y busca:

"hasCompletedOnboarding": true

En una instalación nueva, si esa clave no existe o es false, Claude Code puede omitir tu configuración personalizada y entrar en el flujo estándar de autenticación.

Verifica el estado actual

cat ~/.claude.json | python3 -m json.tool 2>/dev/null | grep hasCompletedOnboarding

Solución

Edita ~/.claude.json y añade:

{
  "hasCompletedOnboarding": true,
  "primaryApiKey": "sk-placeholder"
}

primaryApiKey funciona como marcador de posición. Tu configuración real vendrá de settings.json o de variables de entorno.

Después de guardar, reinicia Claude Code.

Causa raíz 5: la pasarela no reenvía encabezados requeridos

Claude Code envía encabezados adicionales durante la validación. Si tu proxy o pasarela los elimina, la validación puede fallar.

Encabezados importantes:

anthropic-beta
anthropic-version
X-Claude-Code-Session-Id

LiteLLM los maneja por defecto en versiones recientes. Si usas nginx u otro proxy personalizado, reenvíalos explícitamente.

Ejemplo con nginx

location /v1/ {
  proxy_pass http://backend;
  proxy_set_header anthropic-beta $http_anthropic_beta;
  proxy_set_header anthropic-version $http_anthropic_version;
  proxy_set_header X-Claude-Code-Session-Id $http_x_claude_code_session_id;
}

Si no puedes reenviar `anthropic-beta`

Configura:

export CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1

Esto desactiva características experimentales que dependen del encabezado beta. El bucle principal de agente puede seguir funcionando, pero algunas capacidades avanzadas podrían no estar disponibles.

Causa raíz 6: conflicto con política empresarial

Si usas Claude Team o Enterprise, tu administrador puede haber aplicado configuraciones gestionadas. Estas pueden tener prioridad sobre:

Variables de entorno
~/.claude/settings.json
URLs base personalizadas
Modelos disponibles

Verifica si hay configuración gestionada

ls ~/.claude/managed-settings.json 2>/dev/null && echo "Managed settings found"

También puedes revisar desde Claude Code:

/status

Si ves “Managed settings”, habla con tu administrador. Puede que necesites que habilite:

El dominio de tu pasarela
IDs de modelo específicos
El uso de ANTHROPIC_BASE_URL
Excepciones para URLs personalizadas

En despliegues empresariales, estas configuraciones suelen estar en rutas como:

/Library/Application Support/ClaudeCode/managed-settings.json

o su equivalente en Windows/Linux.

Configuraciones completas y funcionales

Claude Code + OpenRouter + DeepSeek V4 Pro

OpenRouter expone una API compatible con Anthropic. Para enrutar Claude Code a DeepSeek V4 Pro, usa ANTHROPIC_AUTH_TOKEN y no incluyas /v1 al final de la URL.

En ~/.claude/settings.json:

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://openrouter.ai/api",
    "ANTHROPIC_AUTH_TOKEN": "sk-or-your-openrouter-key",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "deepseek/deepseek-v4-pro",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "deepseek/deepseek-v4-pro",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "deepseek/deepseek-v4-pro"
  }
}

La anulación de modelos es importante porque Claude Code puede seguir enviando claude-sonnet-4-6 aunque cambies la URL base.

Sin estos valores, la solicitud puede llegar a OpenRouter con un modelo diferente al que esperas.

Nota: OpenRouter no implementa completamente la especificación de streaming de Anthropic para todas las llamadas a herramientas. El bucle principal funciona, pero cadenas complejas de herramientas pueden fallar en algunos casos. Revisa el estado de compatibilidad de OpenRouter.

Claude Code + LiteLLM

LiteLLM es una opción práctica si quieres mapear los nombres de modelos que Claude Code envía por defecto a otros proveedores.

`config.yaml` de LiteLLM

model_list:
  - model_name: claude-sonnet-4-6
    litellm_params:
      model: deepseek/deepseek-v4
      api_key: "sk-your-deepseek-key"
  - model_name: claude-opus-4-7
    litellm_params:
      model: deepseek/deepseek-v4-pro
      api_key: "sk-your-deepseek-key"

`~/.claude/settings.json`

{
  "env": {
    "ANTHROPIC_BASE_URL": "http://localhost:4000",
    "ANTHROPIC_AUTH_TOKEN": "sk-litellm-your-key"
  }
}

Con este enfoque, Claude Code envía claude-sonnet-4-6, y LiteLLM lo enruta internamente a DeepSeek V4.

Claude Code + vLLM local

Para inferencia local con vLLM, inicia el servidor:

python -m vllm.entrypoints.openai.api_server \
  --model deepseek-ai/DeepSeek-V3 \
  --dtype auto \
  --api-key local-key \
  --port 8000

Luego configura Claude Code:

export ANTHROPIC_BASE_URL="http://localhost:8000"
export ANTHROPIC_API_KEY="local-key"
export ANTHROPIC_DEFAULT_SONNET_MODEL="deepseek-ai/DeepSeek-V3"

Cómo depurar el error paso a paso

Si las configuraciones anteriores no funcionan, ejecuta Claude Code con logs:

claude --debug 2>&1 | head -100

Busca estas líneas:

Sending request to: confirma la URL final
Response status: muestra el código HTTP de la pasarela
enterprise config error: muestra el error interno de validación

También puedes reproducir la solicitud manualmente:

curl -v -X POST "${ANTHROPIC_BASE_URL}/v1/messages" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${ANTHROPIC_AUTH_TOKEN}" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: max-tokens-3-5-sonnet-2024-07-15" \
  -d '{
    "model": "claude-sonnet-4-6",
    "max_tokens": 10,
    "messages": [{"role": "user", "content": "hi"}]
  }'

Interpreta la respuesta:

200: la pasarela acepta la solicitud
401: credencial incorrecta o encabezado incorrecto
403: acceso bloqueado
404: URL base incorrecta
422: formato de body o modelo inválido

Probando APIs con Apidog

Cuando depuras proveedores de terceros, Apidog te permite inspeccionar solicitudes y respuestas sin reiniciar Claude Code en cada intento.

Un flujo práctico:

Crea una colección para tu pasarela LLM.
Añade una solicitud POST /v1/messages.
Configura variables de colección para:
- ANTHROPIC_BASE_URL
- ANTHROPIC_AUTH_TOKEN
- anthropic-version
- anthropic-beta
Prueba la misma solicitud contra OpenRouter, LiteLLM o tu gateway interno.
Compara encabezados, códigos HTTP y cuerpos de respuesta.

Ejemplo de body:

{
  "model": "claude-sonnet-4-6",
  "max_tokens": 10,
  "messages": [
    {
      "role": "user",
      "content": "hi"
    }
  ]
}

Esto es útil para confirmar si tu pasarela está eliminando encabezados como anthropic-beta o X-Claude-Code-Session-Id.

Configuraciones de Claude Code relacionadas

Desactivar la dependencia del encabezado beta

Si tu pasarela no puede reenviar encabezados personalizados:

export CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1

Esto reduce la validación de características beta. El bucle de agente sigue funcionando, pero puedes perder funciones experimentales.

Activar descubrimiento de modelos de pasarela

Desde Claude Code v2.1.129, puedes poblar el selector /model desde el endpoint /v1/models de la pasarela:

export CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1

Claude Code consulta:

/v1/models

y añade modelos compatibles al selector.

Ten en cuenta que solo se añaden automáticamente modelos cuyos IDs comienzan con claude o anthropic. Para modelos como DeepSeek, fija el modelo manualmente:

export ANTHROPIC_DEFAULT_SONNET_MODEL="deepseek/deepseek-v4-pro"

Añadir un modelo personalizado al selector

export ANTHROPIC_CUSTOM_MODEL_OPTION="deepseek/deepseek-v4-pro"
export ANTHROPIC_CUSTOM_MODEL_OPTION_NAME="DeepSeek V4 Pro"
export ANTHROPIC_CUSTOM_MODEL_OPTION_DESCRIPTION="17x más barato que Claude Opus"

Esto añade una opción al selector /model, útil si alternas entre Claude y un modelo de pasarela.

Checklist rápido de solución

Antes de seguir depurando, revisa:

echo "$ANTHROPIC_BASE_URL"

Debe verse así:

https://openrouter.ai/api

No así:

https://openrouter.ai/api/v1

Luego valida credenciales:

env | grep ANTHROPIC

Para OpenRouter o LiteLLM deberías usar normalmente:

ANTHROPIC_AUTH_TOKEN=...

Para gateways compatibles con x-api-key:

ANTHROPIC_API_KEY=...

Valida JSON:

jq . ~/.claude/settings.json

Y prueba la URL:

curl -v "${ANTHROPIC_BASE_URL}/v1/messages"

Guías relacionadas

Si estás explorando Claude Code con backends personalizados, estas guías cubren temas cercanos:

Preguntas frecuentes

¿Usar un proveedor de terceros con Claude Code viola los términos de Anthropic?

No necesariamente. Anthropic documenta el patrón ANTHROPIC_BASE_URL para enrutar a través de Bedrock, Vertex AI, Foundry y pasarelas personalizadas.

Lo que Anthropic bloqueó fueron herramientas que suplantaban la ID de cliente de Claude Code para acceder a la API de Anthropic usando precios de suscripción.

Usar tu propia pasarela o un proveedor como OpenRouter con tu propia clave API es un caso diferente.

¿Funciona el bucle de agente de Claude Code con DeepSeek V4 Pro?

El bucle principal funciona: edición de archivos, comandos de shell y tareas de varios pasos.

Las limitaciones principales a través de proveedores de terceros son:

Herramientas de servidor MCP
Entrada de imágenes o visión

Si dependes de esas capacidades, usa la API de Anthropic, Bedrock o Vertex.

¿Por qué dice “configuración empresarial” si no tengo plan empresarial?

Claude Code usa “enterprise config” como etiqueta interna para configuraciones de proveedor de terceros.

No significa que necesites un plan Enterprise.

¿Puedo cambiar entre Anthropic y un proveedor de terceros en la misma sesión?

No. Claude Code lee la URL base al iniciar.

Para cambiar proveedor:

Cierra Claude Code.
Cambia variables de entorno o settings.json.
Inicia una nueva sesión.

Herramientas como DeepClaude encapsulan este cambio mediante flags como:

--backend ds
--backend anthropic

Mi pasarela está detrás de un firewall. ¿Claude Code soporta proxy?

Sí. Configura HTTPS_PROXY antes de iniciar:

export HTTPS_PROXY="http://your-proxy:8080"
export ANTHROPIC_BASE_URL="https://your-internal-gateway"

Si tu proxy corporativo intercepta TLS, añade el certificado CA:

export NODE_EXTRA_CA_CERTS="/path/to/corporate-ca-bundle.pem"

Mi `curl` funciona, pero Claude Code falla. ¿Qué cambia?

Claude Code hace una validación previa adicional. Esa solicitud puede incluir encabezados que tu prueba manual no envía.

Ejecuta:

claude --debug

y compara:

URL final
Encabezados
Modelo solicitado
Body JSON
Código HTTP

Diferencias comunes:

Falta anthropic-beta
Falta X-Claude-Code-Session-Id
Modelo no soportado por la pasarela
Autenticación en encabezado incorrecto

Conclusión

Invalid custom3p enterprise config es un error de validación de configuración.

La ruta de solución más rápida es:

Elimina /v1 de ANTHROPIC_BASE_URL
Usa la variable correcta: ANTHROPIC_AUTH_TOKEN o ANTHROPIC_API_KEY
Valida ~/.claude/settings.json
Confirma que el onboarding está completo
Asegúrate de que tu pasarela reenvía encabezados requeridos
Revisa políticas gestionadas si estás en un entorno empresarial

Cuando la configuración valida correctamente, Claude Code puede ejecutar su bucle de agente a través de OpenRouter, LiteLLM, vLLM u otra pasarela compatible. Las principales limitaciones al usar proveedores de terceros son MCP y entrada de visión, que pueden requerir la API de Anthropic o proveedores soportados oficialmente.

Obtén API Gemini Gratis e Ilimitada

Roobia — Sat, 09 May 2026 07:00:33 +0000

Gemini de Google ofrece modelos potentes para cargas de trabajo de IA, pero en una aplicación pública gratuita, un prototipo o un proyecto de hackathon, el coste por token puede crecer rápido. Puter.js cambia el modelo de integración: permite usar Gemini y Gemma desde el navegador sin clave API de Google, sin proyecto de Google Cloud y sin backend. El uso se asocia al usuario final mediante su cuenta de Puter, mientras que tú integras el modelo desde JavaScript.

Prueba Apidog hoy

TL;DR

Puter.js permite acceder a modelos Gemini y Gemma sin clave API de Google.
Modelos Gemini soportados: 2.5 Pro, 2.5 Flash, 2.5 Flash Lite, 2.0 Flash, 2.0 Flash Lite, 3 Flash Preview y vistas previas anteriores.
Modelos Gemma soportados: Gemma 2, 3 y 4 en varios tamaños.
La integración mínima requiere una etiqueta <script> y una llamada a puter.ai.chat().
Soporta streaming, entrada de imagen, temperatura y conversaciones multiturno desde el navegador.
El usuario final cubre su uso mediante una cuenta de Puter; tú no gestionas claves ni facturación de Google.
Usa Apidog para comparar tu prototipo con la API oficial de Gemini antes de migrar.

Cómo funciona el modelo “gratuito e ilimitado”

Con la API oficial de Gemini, normalmente tú creas un proyecto en Google Cloud o Google AI Studio, generas una clave API y pagas por el consumo de tokens.

Con Puter.js, el flujo cambia:

El usuario abre tu aplicación en el navegador.
Tu aplicación carga Puter.js.
El usuario inicia sesión en Puter o crea una cuenta.
Las llamadas a Gemini se ejecutan a través de Puter.
El uso se descuenta del saldo del usuario final.

Para el desarrollador, esto implica:

Sin clave de Google AI Studio.
Sin proyecto de Google Cloud.
Sin gestión de cuotas ni rotación de claves.
Sin backend obligatorio para llamar al modelo.
Sin coste directo por token desde tu cuenta.

La limitación principal: Puter.js está pensado para aplicaciones de navegador. Si necesitas tareas programadas, webhooks, jobs batch o procesos de backend, la API oficial de Gemini sigue siendo la ruta adecuada.

Paso 1: Instalar Puter.js

Para una página HTML estática, añade el script desde CDN:

<script src="https://js.puter.com/v2/"></script>

Ejemplo mínimo:

<!DOCTYPE html>
<html>
<head>
  <meta charset="UTF-8" />
  <title>Gemini con Puter.js</title>
</head>
<body>
  <div id="output"></div>

  <script src="https://js.puter.com/v2/"></script>
  <script>
    async function main() {
      const response = await puter.ai.chat(
        'Explica qué es una API REST en tres frases.',
        {
          model: 'google/gemini-2.5-flash'
        }
      );

      document.getElementById('output').innerText = response;
    }

    main();
  </script>
</body>
</html>

Si trabajas en una aplicación empaquetada:

npm install @heyputer/puter.js

import { puter } from '@heyputer/puter.js';

Paso 2: Elegir el modelo adecuado

Usa el modelo según el tipo de tarea. Para la mayoría de aplicaciones, empieza con google/gemini-2.5-flash.

ID del modelo	Cuándo usarlo
`google/gemini-2.5-pro`	Razonamiento más profundo, análisis complejo y tareas de contexto largo
`google/gemini-2.5-flash`	Modelo por defecto para chat, Q&A, generación de contenido y prototipos
`google/gemini-2.5-flash-lite`	Clasificación, etiquetado y tareas simples de alto volumen
`google/gemini-2.0-flash`	Base estable con comportamiento conocido
`google/gemini-3-flash-preview`	Vista previa reciente para probar nuevas capacidades
`google/gemma-3-27b-it`	Modelo abierto Gemma ajustado por instrucciones
`google/gemma-4-31b-it`	Variante Gemma más grande disponible en Puter

Regla práctica:

Usa Flash por defecto.
Usa Pro cuando el prompt requiera razonamiento más difícil.
Usa Flash Lite para tareas repetitivas, simples y de gran volumen.

Paso 3: Hacer una primera llamada a Gemini

La llamada básica usa puter.ai.chat():

<!DOCTYPE html>
<html>
<body>
  <script src="https://js.puter.com/v2/"></script>

  <script>
    puter.ai.chat(
      'Explain machine learning in three sentences',
      {
        model: 'google/gemini-2.5-flash'
      }
    ).then(response => {
      puter.print(response);
    });
  </script>
</body>
</html>

Al abrir la página en el navegador:

Puter carga el SDK.
El usuario inicia sesión si todavía no lo ha hecho.
Se envía el prompt al modelo.
La respuesta se imprime en la página.

No necesitas .env, servidor ni clave API.

Paso 4: Mostrar respuestas en streaming

Para interfaces de chat, usa streaming. Esto mejora la percepción de velocidad porque el usuario ve la respuesta mientras se genera.

const outputDiv = document.getElementById('output');

const response = await puter.ai.chat(
  'Explain photosynthesis in detail',
  {
    model: 'google/gemini-2.5-flash',
    stream: true
  }
);

for await (const part of response) {
  if (part?.text) {
    outputDiv.innerHTML += part.text;
  }
}

Un ejemplo de HTML completo:

<!DOCTYPE html>
<html>
<body>
  <button id="run">Preguntar</button>
  <pre id="output"></pre>

  <script src="https://js.puter.com/v2/"></script>
  <script>
    document.getElementById('run').addEventListener('click', async () => {
      const output = document.getElementById('output');
      output.textContent = '';

      const stream = await puter.ai.chat(
        'Resume qué es el patrón Repository en backend.',
        {
          model: 'google/gemini-2.5-flash',
          stream: true
        }
      );

      for await (const part of stream) {
        if (part?.text) {
          output.textContent += part.text;
        }
      }
    });
  </script>
</body>
</html>

Paso 5: Usar visión con una imagen

Gemini también puede analizar imágenes. Pasa la URL de la imagen como segundo argumento:

puter.ai.chat(
  'What do you see in this image? Describe colors, objects, and mood.',
  'https://assets.puter.site/doge.jpeg',
  {
    model: 'google/gemini-2.5-flash'
  }
).then(response => {
  puter.print(response);
});

Casos de uso comunes:

Generación de texto alternativo.
Análisis de capturas de pantalla.
OCR básico.
Revisión visual de productos.
Herramientas de accesibilidad.
Clasificación o etiquetado de imágenes.

Para imágenes naturales y diagramas, Gemini suele ofrecer buen rendimiento. Para capturas con texto muy denso, puede que otros modelos funcionen mejor según el caso.

Paso 6: Ajustar la temperatura

Pasa parámetros en el objeto de opciones:

const response = await puter.ai.chat(
  'Write a creative short story about a robot chef',
  {
    model: 'google/gemini-2.5-flash',
    temperature: 0.2
  }
);

Guía rápida:

Temperatura	Uso recomendado
`0.0` - `0.3`	Respuestas factuales, extracción de datos, clasificación
`0.4` - `0.7`	Chat general, explicaciones, asistencia técnica
`0.8` - `1.0`	Escritura creativa, brainstorming, variaciones de estilo

Para la mayoría de casos de chat, 0.7 funciona bien como punto de partida.

Paso 7: Crear conversaciones multiturno

Para mantener contexto entre mensajes, envía un array de mensajes:

const messages = [
  {
    role: 'user',
    content: 'I am building a Next.js app with Postgres.'
  },
  {
    role: 'assistant',
    content: 'Got it. What do you need help with?'
  },
  {
    role: 'user',
    content: 'How should I structure migrations?'
  }
];

const response = await puter.ai.chat(messages, {
  model: 'google/gemini-2.5-pro'
});

console.log(response);

Patrón de implementación:

const messages = [];

async function sendMessage(userInput) {
  messages.push({
    role: 'user',
    content: userInput
  });

  const response = await puter.ai.chat(messages, {
    model: 'google/gemini-2.5-flash'
  });

  messages.push({
    role: 'assistant',
    content: response
  });

  return response;
}

Antes de cada nueva llamada, añade el mensaje del usuario y la respuesta anterior del asistente. Así el modelo recibe la transcripción completa disponible.

Comparar Gemini con otros modelos usando el mismo prompt

Puter expone varios proveedores mediante una interfaz similar. Puedes ejecutar el mismo prompt contra varios modelos y comparar latencia y calidad:

const models = [
  'google/gemini-2.5-flash',
  'claude-sonnet-4-6',
  'gpt-5.5',
  'x-ai/grok-4.3'
];

const prompt = 'Refactor this React component to use hooks: ...';

for (const model of models) {
  const start = performance.now();

  const response = await puter.ai.chat(prompt, {
    model
  });

  const elapsed = performance.now() - start;

  console.log(`${model}: ${elapsed.toFixed(0)}ms`);
  console.log(response);
  console.log('---');
}

Usa este patrón para decidir con datos propios:

Latencia percibida.
Calidad de respuesta.
Consistencia.
Adecuación al tipo de prompt.
Comportamiento en errores o entradas incompletas.

Lo que obtienes y lo que no

Obtienes

Acceso a modelos Gemini 2.5, 2.0, 3 Flash Preview y 2.5 Pro.
Acceso a la familia abierta Gemma 2/3/4.
Conversaciones multiturno.
Respuestas en streaming.
Entrada de visión mediante URL de imagen.
Parámetros como temperature, max_tokens y prompts de sistema.
Integración directa en navegador.

Puede que no obtengas, según la versión de Puter

Function calling nativo de Gemini.
Herramienta de ejecución de código.
Fundamentación en Google Search.
Contexto completo de 2M tokens de Gemini.
Uso limpio desde backend sin sesión de usuario.
Visibilidad directa de los límites de velocidad de Google.

Para agentes complejos, ejecución de código, fundamentación en Search o contexto máximo, usa la API oficial de Google AI Studio. Para chat, Q&A, generación de contenido, prototipos y tareas visuales desde navegador, Puter puede ser suficiente.

Cuándo usar Puter y cuándo usar la API oficial de Gemini

Usa Puter cuando

Estás creando una app pública gratuita y no quieres asumir facturación por tokens.
Estás prototipando y quieres evitar configuración de Google Cloud.
Quieres usar Gemini en un sitio estático.
Estás construyendo una demo, hackathon o extensión de navegador.
Tus usuarios pueden iniciar sesión en Puter.

Usa la API oficial de Gemini cuando

Necesitas llamadas desde backend.
Tienes jobs programados, webhooks, colas o procesos batch.
Necesitas ejecución de código o fundamentación en Search.
Necesitas el contexto completo de 2M tokens.
Necesitas cumplimiento contractual directo con Google.
Necesitas ajuste fino sobre tus propios datos.
No puedes introducir un paso de inicio de sesión con Puter.

Para una guía específica sobre Gemini 3 Flash, consulta Cómo usar la API de vista previa de Gemini 3 Flash.

Probar la integración con Apidog

Las llamadas de Puter ocurren en el navegador, por lo que no se prueban igual que una API backend. Un flujo práctico es separar prototipo y producción:

Crea una página estática con Puter.js.
Añade un parámetro de consulta para enviar prompts de prueba.
Usa Apidog para documentar y validar la API oficial de Gemini si después migras.
Mantén dos entornos: uno para el prototipo con Puter y otro para la API oficial.

Ejemplo de estructura:

Entorno 1: puter-prototype
Base URL: http://localhost:3000

Entorno 2: gemini-prod
Base URL: https://generativelanguage.googleapis.com/v1

Puedes descargar Apidog y configurar ambos entornos en una misma colección. Así puedes documentar el flujo, probar requests equivalentes y preparar la migración a la API oficial si tu proyecto lo requiere.

Para patrones más amplios de testing de APIs, consulta Herramienta de prueba de API para ingenieros de control de calidad.

Otras rutas gratuitas de LLM a través de Puter

El mismo patrón de integración funciona con otros modelos disponibles mediante Puter. Cambias el valor de model y mantienes una interfaz similar:

const response = await puter.ai.chat(
  'Resume este texto para un usuario técnico.',
  {
    model: 'google/gemini-2.5-flash'
  }
);

Recursos relacionados:

Preguntas frecuentes

¿Es realmente ilimitado?

Desde tu lado como desarrollador, sí: no gestionas una cuota propia de Google ni pagas los tokens desde tu cuenta. El consumo depende del saldo disponible en la cuenta Puter del usuario final.

¿Necesito una cuenta de Google o un proyecto de Google Cloud?

No. Puter gestiona la integración ascendente. Tu aplicación no necesita una clave API de Google.

¿Puedo usar esto en producción?

Sí, si tu aplicación está basada en navegador y el flujo de inicio de sesión de Puter encaja con tu producto. Para backend puro, usa la API oficial.

¿El rendimiento es idéntico al de la API oficial de Gemini?

El modelo subyacente es el mismo, pero puede existir una pequeña diferencia de latencia por la capa adicional de Puter. El comportamiento del modelo no debería cambiar por el hecho de llamarlo desde Puter.

¿Qué pasa con la ventana de contexto de 2M tokens?

Puter puede no exponer el límite completo de 2M tokens en todas las variantes. Si tu caso depende de contextos extremadamente largos, usa la API oficial de Google AI Studio.

¿Puedo usarlo en un bot de Discord o servicio backend?

No de forma limpia. Puter está diseñado principalmente para navegador y asume una sesión de usuario. Para bots, workers, cron jobs o servicios backend, usa la API oficial de Gemini.

¿Qué modelo debería usar por defecto?

Usa google/gemini-2.5-flash.

Cambia a google/gemini-2.5-pro para tareas de razonamiento más difíciles y a google/gemini-2.5-flash-lite para clasificación o etiquetado de alto volumen.

¿Puter soporta generación de imágenes con Imagen?

Actualmente, Puter expone generación de imágenes mediante gpt-image-2 y variantes de DALL-E de OpenAI, no Imagen. Para esa ruta, consulta Obtén API de GPT-5.5 ilimitada y gratuita.

Conclusión

Puter.js es una forma directa de usar Gemini desde el navegador sin clave API, sin backend y sin configurar Google Cloud. Para empezar:

Añade https://js.puter.com/v2/.
Llama a puter.ai.chat().
Usa google/gemini-2.5-flash como modelo inicial.
Añade streaming, visión o multiturno según tu caso.

Para prototipos, sitios estáticos, hackathons y apps públicas gratuitas, Puter reduce la fricción de integración. Para backend, ajuste fino, ejecución de código o contexto máximo de Gemini, la API oficial sigue siendo la opción correcta.

Crea tu solicitud una vez en Apidog, compara el prototipo con Puter frente a la API oficial de Gemini y elige la ruta que encaje con tu arquitectura.

API GPT-5.5 y Todos los Modelos OpenAI Gratis e Ilimitados

Roobia — Sat, 09 May 2026 02:37:25 +0000

El GPT-5.5 de OpenAI se distribuye con una API de pago: $5 por millón de tokens de entrada y $30 por millón de tokens de salida. Si estás construyendo un proyecto secundario, una demo de hackathon o una aplicación pública gratuita, ese coste puede bloquear el lanzamiento antes de escribir la primera integración. Una alternativa práctica es usar Puter.js: expone modelos de OpenAI como GPT-5.5, GPT-5.5 Pro, variantes GPT-5.x, GPT-Image-2, DALL-E y OpenAI TTS sin que tengas que gestionar una clave de OpenAI. El uso se carga al usuario final mediante su cuenta de Puter; tú no pagas la factura de tokens.

Prueba Apidog hoy

En resumen

Puter.js permite usar modelos de OpenAI desde el navegador sin clave API, sin cuenta de OpenAI y sin backend propio.
Los modelos de texto compatibles incluyen gpt-5.5, gpt-5.5-pro, gpt-5.4, gpt-5, gpt-5-mini, o1, o3, gpt-4.1, gpt-4o, además de variantes de chat y códec.
Para imágenes puedes usar gpt-image-2, gpt-image-1.5, dall-e-3.
Para texto a voz puedes usar gpt-4o-mini-tts, tts-1, tts-1-hd.
La integración mínima requiere una etiqueta <script> y una llamada a puter.ai.chat.
Streaming, visión, generación de imágenes, texto a voz y llamada a funciones funcionan desde el navegador.
El usuario final cubre su consumo desde Puter; tu aplicación evita exposición directa a la facturación de OpenAI.
Usa Apidog para comparar prompts entre Puter y la API oficial de OpenAI cuando planifiques una migración.

Cómo funciona lo de "gratis ilimitado"

Puter.js cambia el modelo de facturación de los LLM. En vez de que tu aplicación use una clave de OpenAI y asuma cada coste de token, el usuario inicia sesión en Puter y el consumo se carga a su cuenta. Las cuentas nuevas de Puter obtienen crédito inicial; si el usuario necesita más uso, puede recargar.

Para ti como desarrollador, esto implica:

No gestionas claves de OpenAI. No hay secretos en el repositorio, variables de entorno ni rotación de claves.
No tienes límite de uso centralizado. Cada usuario opera con su propia cuenta de Puter.
No tienes exposición directa a la facturación. No recibes una factura de OpenAI por el uso de tus usuarios.

La contrapartida importante: Puter.js está pensado para aplicaciones de navegador. Si necesitas ejecutar tareas en backend, workers, webhooks o procesamiento por lotes sin sesión de usuario, la API oficial de OpenAI sigue siendo la opción adecuada.

Paso 1: Instala Puter.js

Para una página HTML, añade el script desde CDN:

<script src="https://js.puter.com/v2/"></script>

Ejemplo mínimo:

<!DOCTYPE html>
<html lang="es">
<body>
  <script src="https://js.puter.com/v2/"></script>
</body>
</html>

Si usas bundler, instala el paquete NPM:

npm install @heyputer/puter.js

Importa puter en tu código:

import { puter } from '@heyputer/puter.js';

Usa la versión CDN para prototipos, sitios estáticos, extensiones de navegador o demos rápidas. Usa NPM si tu aplicación ya tiene pipeline de build y quieres integrarlo con tu stack JavaScript.

Paso 2: Elige el modelo correcto

Selecciona el modelo según la tarea. La elección afecta latencia, calidad y coste para el usuario.

ID del modelo	Cuándo usar
`gpt-5.5-pro`	Razonamiento profundo, agentes de codificación, análisis complejo
`gpt-5.5`	Uso general diario; buen equilibrio entre calidad y coste
`gpt-5.4-nano`	Clasificación o texto de alto volumen con menor coste
`gpt-5.4-mini`	Interfaces de chat y tareas intermedias
`gpt-5.3-codex`	Tareas específicas de código
`o3`	Cadenas de razonamiento complejas
`o1-pro`	Planificación agéntica de varios pasos
`gpt-4.1`, `gpt-4o`, `gpt-4o-mini`	Base estable y conocida

Para generación de imágenes:

gpt-image-2: modelo más reciente, rápido y con salida nítida.
gpt-image-1.5, gpt-image-1, dall-e-3, dall-e-2: opciones anteriores pero estables.

Para texto a voz:

gpt-4o-mini-tts: opción más reciente y natural.
tts-1, tts-1-hd: TTS clásico con menor latencia.

Paso 3: Haz tu primera llamada a GPT-5.5

La llamada mínima de chat se hace con puter.ai.chat:

<!DOCTYPE html>
<html lang="es">
<body>
  <script src="https://js.puter.com/v2/"></script>

  <script>
    puter.ai.chat(
      "Explica WebSockets en tres frases",
      { model: "gpt-5.5" }
    ).then(response => {
      puter.print(response);
    });
  </script>
</body>
</html>

Abre el archivo en el navegador. Puter gestiona la autenticación del usuario y ejecuta la llamada al modelo. Si el usuario no tiene sesión iniciada, Puter le pedirá iniciar sesión o crear una cuenta gratuita.

No necesitas:

Clave API de OpenAI.
Backend intermedio.
Variable de entorno.
Endpoint propio para proxy.

Paso 4: Usa streaming para interfaces de chat

Para una UX de chat, no esperes a que termine toda la respuesta. Activa stream: true y consume los fragmentos conforme llegan:

const response = await puter.ai.chat(
  "Explica la teoría de la relatividad en detalle",
  {
    model: "gpt-5.5",
    stream: true,
  }
);

for await (const part of response) {
  puter.print(part?.text);
}

En una interfaz real, en vez de imprimir con puter.print, añade cada fragmento a una burbuja de chat:

const bubble = document.querySelector("#assistant-message");

for await (const part of response) {
  if (part?.text) {
    bubble.textContent += part.text;
  }
}

Esto permite que el usuario vea la respuesta aparecer progresivamente.

Paso 5: Procesa imágenes con visión

Puedes pasar una URL de imagen como segundo argumento. El modelo analizará la imagen y responderá según el prompt:

puter.ai.chat(
  "¿Qué ves en esta imagen? Describe colores, objetos y ambiente.",
  "https://assets.puter.site/doge.jpeg",
  { model: "gpt-5.5" }
).then(response => {
  puter.print(response);
});

Casos de uso prácticos:

Generación de texto alternativo.
Análisis de capturas de pantalla.
QA visual.
OCR básico.
Herramientas de accesibilidad.
Clasificación de imágenes enviada por usuarios.

Paso 6: Genera imágenes desde texto

puter.ai.txt2img devuelve un elemento <img> con la imagen generada ya cargada:

puter.ai.txt2img(
  "Una ciudad futurista de noche, estilo cinematográfico, luces neón, lluvia",
  { model: "gpt-image-2" }
).then(imageElement => {
  document.body.appendChild(imageElement);
});

Si quieres integrarlo en una UI:

<form id="image-form">
  <input id="prompt" placeholder="Describe la imagen" />
  <button type="submit">Generar</button>
</form>

<div id="result"></div>

<script src="https://js.puter.com/v2/"></script>
<script>
  const form = document.querySelector("#image-form");
  const input = document.querySelector("#prompt");
  const result = document.querySelector("#result");

  form.addEventListener("submit", async event => {
    event.preventDefault();

    result.textContent = "Generando imagen...";

    const image = await puter.ai.txt2img(input.value, {
      model: "gpt-image-2",
    });

    result.innerHTML = "";
    result.appendChild(image);
  });
</script>

El coste de generación se carga al saldo de Puter del usuario. Para aplicaciones públicas, limita prompts vacíos, evita reintentos automáticos innecesarios y muestra al usuario cuándo una acción generará consumo.

Paso 7: Convierte texto a voz

La línea TTS de OpenAI se expone mediante puter.ai.txt2speech. La función devuelve un elemento <audio>:

puter.ai.txt2speech(
  "Bienvenido de nuevo. El saldo de tu cuenta es de $1,247.50.",
  {
    provider: "openai",
    model: "gpt-4o-mini-tts",
  }
).then(audio => {
  audio.setAttribute("controls", "");
  document.body.appendChild(audio);
});

Úsalo para:

Indicaciones de voz.
Lectura de respuestas largas.
Narración de accesibilidad.
Onboarding de aplicaciones.
Locuciones de prototipos o demos.

Paso 8: Implementa llamada a funciones

Puter usa un formato compatible con el patrón de herramientas de OpenAI. Defines herramientas, el modelo solicita una llamada y tú ejecutas la función en tu aplicación.

Ejemplo:

const tools = [
  {
    type: "function",
    function: {
      name: "get_weather",
      description: "Obtiene el clima actual de una ciudad.",
      parameters: {
        type: "object",
        properties: {
          city: {
            type: "string",
            description: "Nombre de la ciudad",
          },
        },
        required: ["city"],
      },
    },
  },
];

const response = await puter.ai.chat(
  "¿Cuál es el clima en Tokio ahora mismo?",
  {
    model: "gpt-5.5",
    tools,
  }
);

const toolCalls = response.message.tool_calls;

if (toolCalls?.length) {
  const toolCall = toolCalls[0];

  console.log("Función:", toolCall.function.name);
  console.log("Argumentos:", toolCall.function.arguments);

  // Aquí ejecutas tu propia función:
  // const result = await getWeather(JSON.parse(toolCall.function.arguments));
}

La parte importante: el modelo no ejecuta tu función. Solo devuelve la intención estructurada. Tú decides qué hacer con esa solicitud, validas argumentos y ejecutas código propio.

Para probar flujos basados en herramientas en entornos de producción, consulta las pruebas de servidor MCP en Apidog.

Paso 9: Controla temperatura y `max_tokens`

Pasa los parámetros estándar en el objeto de opciones:

const response = await puter.ai.chat(
  "Háblame de Marte",
  {
    model: "gpt-5.5",
    temperature: 0.2,
    max_tokens: 200,
  }
);

Guía rápida:

temperature: 0.0 a 0.3: respuestas más deterministas y factuales.
temperature: 0.7 a 1.0: escritura más creativa.
max_tokens: límite máximo de salida.

Para una aplicación pública, define max_tokens por tipo de acción. Por ejemplo:

const LIMITS = {
  summary: 300,
  chat: 800,
  codeReview: 1200,
};

const response = await puter.ai.chat(
  userPrompt,
  {
    model: "gpt-5.5",
    temperature: 0.2,
    max_tokens: LIMITS.summary,
  }
);

Esto mantiene el consumo del usuario más predecible.

Lo que obtienes y lo que no

Puter.js cubre muchos casos de uso, pero no reemplaza toda la superficie de la API oficial de OpenAI.

Obtienes:

Catálogo GPT-5.x, incluyendo 5.5, 5.5 Pro, 5.4 mini, nano y pro.
Modelos anteriores como GPT-4.1, GPT-4o, o1 y o3.
Generación de imágenes con GPT-Image-2 y DALL-E.
Texto a voz con modelos TTS de OpenAI.
Streaming.
Entrada de imagen.
Llamada a funciones.
Parámetros como temperature y max_tokens.
Integración directa en navegador sin backend.

Puede que no obtengas:

API de Responses.
Reducción de coste por caché de prompts.
API de Files para contexto de documentos subidos.
Uso limpio del lado del servidor sin sesión de navegador.
Cabeceras directas de rate limit de OpenAI.
Modo completo de salida estructurada con validación de esquema JSON.

Para flujos de producción avanzados, la API oficial de OpenAI sigue siendo la opción más completa. Para prototipos, sitios estáticos, extensiones y aplicaciones de navegador, Puter.js reduce mucha fricción inicial.

Cuándo usar Puter vs. OpenAI oficial

Usa Puter cuando:

Estás lanzando una aplicación pública gratuita.
No quieres asumir la factura de tokens de tus usuarios.
Estás prototipando y no quieres configurar facturación en OpenAI.
Tu aplicación corre principalmente en navegador.
No necesitas backend para ejecutar las llamadas.
Tus usuarios pueden iniciar sesión en Puter.

Usa la API oficial de OpenAI cuando:

Necesitas llamadas del lado del servidor.
Ejecutas tareas programadas, webhooks o procesamiento por lotes.
Necesitas la API de Responses, Files o salidas estructuradas completas.
Quieres aprovechar caché de prompts.
Necesitas acuerdos contractuales o requisitos de cumplimiento.
No quieres introducir un login adicional de Puter para tus usuarios.

Una estrategia práctica es empezar con Puter para validar la experiencia de usuario y migrar a la API oficial cuando aparezca una necesidad clara de backend, cumplimiento o control avanzado.

Para una configuración de producción de pago, consulta Cómo usar la API de GPT-5.5.

Probando la integración en Apidog

Las llamadas de Puter ocurren en el navegador, por lo que no puedes ejecutarlas directamente como una prueba backend tradicional. Un flujo práctico es separar prototipo y producción:

Crea una página estática que use Puter.js.
Lee el prompt desde un parámetro de consulta o desde un formulario.
Usa esa página para validar el comportamiento del frontend.
Usa Apidog para preparar y probar la API oficial de OpenAI si luego migras.
Mantén dos entornos separados: uno para Puter y otro para OpenAI.

Ejemplo de entornos:

puter-prototype: URL local de tu página con Puter, por ejemplo http://localhost:5173.
openai-prod: https://api.openai.com/v1.

Descarga Apidog y configura ambos entornos en la misma colección. Así puedes comparar el prompt, la estructura de mensajes y la respuesta antes de decidir si migras desde Puter a la API oficial.

Para patrones de pruebas de API más amplios, consulta herramienta de prueba de API para ingenieros de QA.

Preguntas frecuentes

¿Es realmente ilimitado?

Desde el lado del desarrollador, sí. No tienes un límite de uso centralizado asociado a tu cuenta de OpenAI porque no estás usando tu propia clave. El consumo depende del saldo de la cuenta de Puter de cada usuario.

¿Necesito una cuenta de OpenAI?

No. Puter gestiona la conexión con OpenAI. Tu aplicación no ve ni almacena una clave de OpenAI.

¿Puedo usar esto en producción?

Sí, si tu aplicación está basada en navegador y el flujo de inicio de sesión en Puter encaja con tu producto. Si necesitas procesos backend sin usuario interactivo, usa la API oficial.

¿GPT-5.5 vía Puter funciona igual que la API oficial?

Puter llama a OpenAI en nombre del usuario. La salida del modelo debería mantener el mismo comportamiento del modelo, aunque puede existir latencia adicional por el salto intermedio.

¿Qué pasa con el caché de prompts?

Puter no expone los controles de caché de prompts de OpenAI. Si tu aplicación depende de un prompt de sistema grande y estable para reducir coste, usa la API oficial.

¿Puedo usar Puter en un servicio backend?

No de forma limpia. Puter está diseñado para navegador y asume una sesión de usuario. Para backend, usa la API oficial de OpenAI. Para alternativas gratuitas del lado del servidor, consulta Cómo usar la API de GPT-5.5 gratis.

¿Qué modelo debería usar por defecto?

Usa gpt-5.5 para razonamiento general. Usa gpt-5.4-nano para clasificación de alto volumen. Usa gpt-5.5-pro para tareas difíciles. Usa o3 cuando necesites razonamiento largo.

¿Se les cobrará mucho a mis usuarios?

Depende del uso. Las conversaciones de texto suelen tener costes bajos por sesión, pero la generación de imágenes puede consumir más saldo. Controla max_tokens, evita llamadas duplicadas y muestra acciones explícitas para operaciones costosas.

¿Puedo generar imágenes gratis con Puter?

Puedes generar imágenes con txt2img usando gpt-image-2 o DALL-E. El coste se carga al saldo de Puter del usuario. Para la guía de la API de pago, consulta Cómo usar la API de GPT-Image-2.

Conclusión

Puter.js es una forma directa de integrar modelos de OpenAI en aplicaciones de navegador sin gestionar claves, backend ni facturación propia. Añades el script, eliges un modelo y llamas a puter.ai.chat, txt2img o txt2speech según el caso.

Para prototipos, hackathons, sitios estáticos y aplicaciones públicas gratuitas, este enfoque reduce mucha complejidad. Para backend, caché de prompts, API de Responses, Files o salidas estructuradas completas, la API oficial de OpenAI sigue siendo la opción correcta.

Crea la solicitud una vez en Apidog, compara Puter con la API oficial y elige el camino que mejor encaje con tu arquitectura.

Obtén API Claude Opus 4.7 Gratis e Ilimitada

Roobia — Sat, 09 May 2026 02:30:19 +0000

La familia Claude de Anthropic es una de las líneas de modelos de código cerrado más capaces para codificación, agentes y razonamiento con contexto largo. El problema es el coste: Sonnet cuesta $3 / $15 por millón de tokens y Opus cuesta más. Puter.js cambia el modelo de facturación: expone modelos Claude como Opus 4.7, Sonnet 4.6 y Haiku 4.5 sin clave de Anthropic, y carga el uso al usuario final en lugar de al desarrollador.

Prueba Apidog hoy

En esta guía vas a implementar Claude en una app de navegador con Puter.js: instalación, selección de modelo, llamadas básicas, streaming, conversaciones multiturno, mensajes de sistema y criterios para decidir cuándo migrar a la API oficial de Anthropic.

TL;DR

Puter.js permite usar Claude desde el navegador sin clave de API de Anthropic.
El usuario final usa su propia cuenta de Puter; tú no gestionas facturación de Anthropic.
Modelos compatibles mencionados: Opus 4.7, Opus 4.6, Opus 4.6 Fast, Opus 4.5, Opus 4.1, Opus 4, Sonnet 4.6, Sonnet 4.5, Sonnet 4, Haiku 4.5.
La integración mínima requiere una etiqueta <script> y una llamada a puter.ai.chat.
Soporta streaming, mensajes de sistema y conversaciones multiturno.
Puedes usar Apidog para comparar el diseño de tus solicitudes cuando migres a la API oficial de Anthropic.

Cómo funciona el acceso gratuito para el desarrollador

Puter.js es una biblioteca de IA y nube sin servidor que se ejecuta en el navegador.

La diferencia clave está en la arquitectura:

Tu aplicación carga Puter.js.
El usuario inicia sesión en Puter.
La llamada a Claude se ejecuta usando la cuenta del usuario.
El consumo se carga al saldo del usuario en Puter.
Tú no expones claves ni pagas la factura de Anthropic.

Esto implica:

No hay claves de API en el frontend ni en el repositorio.
No gestionas límites de uso por proyecto.
No necesitas una cuenta de Anthropic para este flujo.

La contrapartida: Puter.js está pensado principalmente para aplicaciones de navegador. Si necesitas ejecutar Claude desde backend, workers, cron jobs o procesamiento por lotes, la API oficial de Anthropic suele ser la opción correcta.

Paso 1: Instala Puter.js

Para un prototipo o sitio estático, añade el script CDN:

<script src="https://js.puter.com/v2/"></script>

Ejemplo HTML mínimo:

<!DOCTYPE html>
<html lang="es">
<body>
  <script src="https://js.puter.com/v2/"></script>
</body>
</html>

Si trabajas con una app empaquetada, puedes instalarlo con NPM:

npm install @heyputer/puter.js

E importarlo en tu código:

import { puter } from '@heyputer/puter.js';

Usa el CDN si quieres validar rápido la integración. Usa NPM si estás en una aplicación con Vite, Webpack o TypeScript.

Paso 2: Elige el modelo Claude

Puter expone varios modelos Claude usando IDs compatibles con la nomenclatura de Anthropic.

ID de modelo	Cuándo usarlo
`claude-opus-4-7`	Razonamiento profundo, revisión compleja de código, agentes avanzados
`claude-opus-4-6`	Codificación robusta y tareas complejas
`claude-opus-4.6-fast`	Variante Opus con menor latencia
`claude-opus-4-5`	Agentes de producción y razonamiento estable
`claude-opus-4-1`	Modelo heredado estable
`claude-opus-4`	Línea base de Opus 4
`claude-sonnet-4-6`	Modelo recomendado para uso diario
`claude-sonnet-4-5`	Buen equilibrio para tareas generales
`claude-sonnet-4`	Línea base de Sonnet 4
`claude-haiku-4-5`	Clasificación rápida, alto volumen, baja latencia

Recomendación práctica:

Usa claude-sonnet-4-6 por defecto.
Usa claude-haiku-4-5 para tareas rápidas y repetitivas.
Usa claude-opus-4-7 cuando la calidad de razonamiento sea más importante que la latencia.

Paso 3: Haz tu primera llamada a Claude

La llamada mínima usa puter.ai.chat.

<!DOCTYPE html>
<html lang="es">
<body>
  <script src="https://js.puter.com/v2/"></script>

  <script>
    puter.ai.chat(
      "Explica la computación cuántica en términos simples",
      { model: "claude-sonnet-4-6" }
    ).then(response => {
      puter.print(response.message.content[0].text);
    });
  </script>
</body>
</html>

Qué ocurre al abrir este archivo en el navegador:

Se carga Puter.js.
El usuario inicia sesión o crea una cuenta de Puter.
Puter envía el prompt a Claude.
La respuesta se renderiza en la página.

La respuesta sigue una estructura similar a la API de mensajes de Anthropic:

response.message.content[0].text

Para respuestas de texto simple, normalmente lees el primer bloque. Si esperas contenido multiparte, itera sobre response.message.content.

for (const block of response.message.content) {
  if (block.type === "text") {
    console.log(block.text);
  }
}

Paso 4: Implementa streaming

Para respuestas largas, activa stream: true.

const response = await puter.ai.chat(
  "Escribe un análisis detallado sobre el impacto de la inteligencia artificial en la sociedad",
  {
    model: "claude-sonnet-4-6",
    stream: true
  }
);

for await (const part of response) {
  puter.print(part?.text);
}

En una interfaz de chat, el patrón típico es acumular los fragmentos en un contenedor:

<div id="output"></div>

<script>
  async function run() {
    const output = document.getElementById("output");

    const stream = await puter.ai.chat(
      "Resume los riesgos de seguridad más comunes en APIs REST",
      {
        model: "claude-sonnet-4-6",
        stream: true
      }
    );

    for await (const part of stream) {
      if (part?.text) {
        output.textContent += part.text;
      }
    }
  }

  run();
</script>

Esto mejora la percepción de velocidad porque el usuario ve la respuesta mientras se genera.

Paso 5: Crea conversaciones multiturno

Para mantener contexto, pasa un array de mensajes en lugar de un string.

const messages = [
  {
    role: "user",
    content: "Estoy construyendo una app Next.js con Postgres."
  },
  {
    role: "assistant",
    content: "Entendido. ¿En qué parte necesitas ayuda?"
  },
  {
    role: "user",
    content: "¿Cómo debería estructurar la carpeta de migraciones?"
  }
];

const response = await puter.ai.chat(messages, {
  model: "claude-opus-4-7"
});

console.log(response.message.content[0].text);

Para una app real, guarda el historial en memoria o en estado de UI:

const messages = [];

async function sendMessage(userText) {
  messages.push({
    role: "user",
    content: userText
  });

  const response = await puter.ai.chat(messages, {
    model: "claude-sonnet-4-6"
  });

  const assistantText = response.message.content[0].text;

  messages.push({
    role: "assistant",
    content: assistantText
  });

  return assistantText;
}

Claude leerá la transcripción completa enviada en cada llamada.

Paso 6: Usa mensajes de sistema

Los mensajes de sistema definen comportamiento, tono, restricciones y formato de salida.

const messages = [
  {
    role: "system",
    content: "Eres un ingeniero backend senior. Responde en viñetas numeradas y con un máximo de cinco puntos."
  },
  {
    role: "user",
    content: "¿Cómo prevengo SQL injection en una app Node.js?"
  }
];

const response = await puter.ai.chat(messages, {
  model: "claude-sonnet-4-6"
});

console.log(response.message.content[0].text);

Úsalos para instrucciones persistentes como:

idioma de respuesta;
formato JSON;
longitud máxima;
rol técnico;
estilo de explicación;
restricciones de seguridad.

Ejemplo para salida JSON:

const messages = [
  {
    role: "system",
    content: "Devuelve únicamente JSON válido. No incluyas Markdown."
  },
  {
    role: "user",
    content: "Extrae el nombre, email y empresa de este texto: Ana Pérez, ana@example.com, Acme Inc."
  }
];

const response = await puter.ai.chat(messages, {
  model: "claude-haiku-4-5"
});

const data = JSON.parse(response.message.content[0].text);
console.log(data);

Paso 7: Compara modelos con el mismo prompt

Antes de elegir un modelo para producción, ejecuta el mismo prompt contra varios modelos y mide latencia y calidad.

const models = [
  "claude-haiku-4-5",
  "claude-sonnet-4-6",
  "claude-opus-4-7"
];

const prompt = "Refactoriza este componente React para usar hooks: ...";

for (const model of models) {
  const start = performance.now();

  const response = await puter.ai.chat(prompt, { model });

  const elapsed = performance.now() - start;

  console.log(`${model}: ${elapsed.toFixed(0)}ms`);
  console.log(response.message.content[0].text);
  console.log("---");
}

Evalúa cada salida con criterios concretos:

¿Compila?
¿Respeta las instrucciones?
¿Reduce complejidad?
¿Evita cambios innecesarios?
¿Responde suficientemente rápido para tu UX?

Como regla práctica:

claude-haiku-4-5: clasificación, extracción, respuestas cortas.
claude-sonnet-4-6: tareas generales de desarrollo.
claude-opus-4-7: problemas difíciles, razonamiento largo, revisiones complejas.

Para comparar el flujo de Puter con la API oficial de Anthropic en Apidog, mantén ambos proveedores como entornos separados y reutiliza prompts equivalentes.

Lo que obtienes y lo que no

Claude vía Puter.js es útil para apps de navegador, pero no sustituye todos los casos de uso de la API oficial.

Obtienes:

acceso a modelos Claude desde el navegador;
conversaciones multiturno;
mensajes de sistema;
streaming;
integración sin clave de Anthropic en tu app;
cero exposición directa a facturación para el desarrollador.

Puede que no obtengas, según la versión de Puter:

uso avanzado de herramientas o function calling;
entrada de visión con adjuntos de imagen;
controles de caché de prompts de Anthropic;
ejecución limpia desde backend;
visibilidad directa de headers, cuotas o límites de Anthropic.

Para flujos avanzados de herramientas, la API oficial de Anthropic o las pruebas de servidor MCP en Apidog ofrecen más control.

Para un chatbot, una app de preguntas y respuestas, un generador de contenido o un prototipo público, Puter.js suele ser suficiente.

Cuándo usar Puter.js

Usa Puter.js cuando:

estás construyendo una app de navegador;
no quieres gestionar claves de Anthropic;
estás prototipando;
estás creando un proyecto de hackathon;
quieres publicar una demo estática;
tus usuarios pueden iniciar sesión en Puter;
no necesitas procesamiento backend.

Ejemplos adecuados:

chatbot embebido en una página;
asistente para documentación;
generador de snippets;
clasificador de texto en frontend;
demo interactiva de IA;
extensión de navegador con interacción del usuario.

Cuándo usar la API oficial de Anthropic

Usa la API oficial cuando:

necesitas llamadas desde servidor;
ejecutas tareas programadas;
haces procesamiento por lotes;
necesitas caché de prompts;
necesitas control completo de herramientas;
necesitas adjuntar imágenes o archivos;
tienes requisitos de cumplimiento;
no quieres depender de login de Puter para tus usuarios.

Ejemplos:

bot de Discord;
pipeline de análisis de documentos;
endpoint SaaS multiusuario;
worker de cola;
agente con herramientas internas;
sistema con auditoría y control de facturación.

La migración conceptual es directa porque el formato de mensajes es similar: role, content y lista de turnos.

Para el equivalente de GPT, consulta Cómo usar la API de GPT-5.5.

Probando la integración en Apidog

Las llamadas de Puter ocurren en el navegador, así que no se prueban igual que un endpoint backend tradicional.

Un flujo práctico es:

Crear una página estática que reciba el prompt por query string.
Ejecutar Puter.js desde esa página.
Usar Apidog para diseñar y validar la futura integración con Anthropic.
Mantener dos entornos separados: prototipo con Puter y producción con Anthropic.

Configura dos entornos en Apidog:

puter-prototype: apunta a tu página local o demo estática.
anthropic-prod: apunta a https://api.anthropic.com/v1.

Así puedes mantener el diseño de solicitudes, prompts y pruebas en una misma colección mientras decides cuándo migrar.

Preguntas frecuentes

¿Esto es realmente ilimitado?

Para el desarrollador, sí: no tienes una cuota de Anthropic asociada a tu proyecto. El uso depende del saldo de cada usuario en Puter.

¿Necesito registrarme en Anthropic?

No para el flujo con Puter.js. Puter gestiona la relación con Anthropic.

¿Puedo usar esto en producción?

Sí, si tu aplicación es de navegador y tus usuarios aceptan iniciar sesión en Puter. Si necesitas backend, usa la API oficial.

¿Claude vía Puter responde igual que la API oficial?

El modelo subyacente es Claude. Puede haber diferencias operativas como latencia o superficie de API disponible, pero el modelo no cambia por el hecho de llamarlo desde Puter.

¿Puedo usar caché de prompts?

Puter no expone necesariamente los controles de caché de prompts de Anthropic. Si dependes de esa optimización, usa la API oficial.

¿Puedo usarlo en un bot de Discord?

No es el caso ideal. Puter.js está orientado a navegador y sesión de usuario. Para bots y servicios backend, usa Anthropic directamente.

¿Qué modelo debería usar por defecto?

claude-sonnet-4-6. Cambia a claude-opus-4-7 para tareas difíciles y a claude-haiku-4-5 para tareas rápidas o de alto volumen.

Resumen

Puter.js es una forma rápida de añadir Claude a una aplicación de navegador sin gestionar claves de Anthropic ni asumir facturación directa como desarrollador.

El flujo mínimo es:

<script src="https://js.puter.com/v2/"></script>

const response = await puter.ai.chat("Tu prompt", {
  model: "claude-sonnet-4-6"
});

console.log(response.message.content[0].text);

Úsalo para prototipos, demos, sitios estáticos, hackathons y apps públicas donde el usuario pueda iniciar sesión en Puter.

Para backend, caché de prompts, herramientas avanzadas o requisitos de cumplimiento, usa la API oficial de Anthropic.

Crea la solicitud una vez en Apidog, compara el flujo con Puter y la API oficial, y elige el camino que mejor encaje con tu arquitectura.

Cómo Usar Grok 4.3 Gratis: 4 Métodos Funcionando en 2026

Roobia — Sat, 09 May 2026 02:26:10 +0000

Grok 4.3 es el modelo insignia de xAI a mayo de 2026, con una ventana de contexto de 1M de tokens, entrada de video nativa y un precio de $1.25 / $2.50 por millón de tokens. Si estás prototipando, aprendiendo o construyendo un proyecto paralelo, puedes acceder a Grok 4.3 sin pagar a través de tres rutas creíbles: créditos promocionales de xAI Console, Puter.js —donde el usuario final cubre el uso— y las interfaces gratuitas de chat en grok.com y X.

Prueba Apidog hoy

Esta guía explica cómo usar cada ruta, qué configurar, qué código ejecutar y cuándo conviene pasar a pago. Para la guía completa de la API de pago, consulta Cómo usar la API de Grok 4.3. Para el equivalente de voz, consulta Cómo usar Grok Voice gratis.

En resumen

Tres caminos gratuitos a Grok 4.3: xAI Console con créditos promocionales, Puter.js con pago por el usuario final, y las interfaces de chat en grok.com y X.
Mejor para desarrolladores: Puter.js, porque puedes desplegar sin claves de facturación propias.
Mejor para prototipos personales: xAI Console con una cuenta nueva y créditos promocionales.
Mejor para no desarrolladores: grok.com o la aplicación X.
ID del modelo en Puter: x-ai/grok-4.3.
ID del modelo en xAI: grok-4.3.
Usa Apidog para preparar la misma solicitud contra varios proveedores y comparar resultados.

Ruta 1: Créditos promocionales de xAI Console

Usa esta ruta si quieres probar la API real de producción de xAI sin pagar durante la fase inicial.

Paso 1: Crea una cuenta

Ve a console.x.ai y crea una cuenta. El inicio de sesión se realiza con tu cuenta X.

Paso 2: Revisa los créditos disponibles

xAI ejecuta ventanas promocionales que otorgan créditos gratuitos a cuentas nuevas. La cantidad y la elegibilidad cambian con el tiempo, así que revisa la sección Billing / Facturación después de registrarte.

El patrón habitual es:

recibes un pool de créditos inicial;
el crédito no se renueva automáticamente;
puedes usarlo para validar una integración completa;
cuando se agota, debes pasar a pago o migrar a otra ruta.

xAI también ha ofrecido acceso promocional gratuito a modelos específicos en ventanas anteriores, como Grok 4.1 Fast y la API de Agent Tools.

Paso 3: Llama a la API

El endpoint es compatible con el formato de OpenAI:

export XAI_API_KEY="xai-..."

curl https://api.x.ai/v1/chat/completions \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-4.3",
    "messages": [
      {
        "role": "user",
        "content": "Explain prompt caching in three sentences."
      }
    ],
    "reasoning_effort": "low"
  }'

Durante el prototipado, usa reasoning_effort: "low" para consumir menos crédito. Los valores medium y high pueden agotar el crédito más rápido.

Pros y contras

Pros	Contras
Usas la superficie real de la API de producción	El pool de créditos es finito
Puedes probar contexto de 1M, video y llamada de funciones	Los términos promocionales pueden cambiar
Migrar a pago no requiere cambiar el código principal	Estás limitado al crédito disponible

Recomendación: empieza con xAI Console si necesitas saber cómo se comporta exactamente la API de producción. Para el esquema completo de solicitud, consulta Cómo usar la API de Grok 4.3.

Ruta 2: Puter.js: el usuario paga, el desarrollador no

Puter.js es la ruta más práctica si quieres publicar una aplicación web sin asumir tú el coste de inferencia.

Cómo funciona

Puter.js expone un cliente JavaScript para llamar a varios LLMs, incluidos Grok, GPT, Claude, Gemini y DeepSeek.

La diferencia está en la facturación:

el usuario final paga desde su cuenta de Puter, no el desarrollador.

Tú insertas el script, llamas al modelo y despliegas tu app. Cuando el usuario ejecuta una llamada, Puter gestiona su inicio de sesión y el consumo asociado a su cuenta.

Paso 1: Añade el script

Incluye Puter.js en tu HTML:

<script src="https://js.puter.com/v2/"></script>

No necesitas clave API ni configurar facturación propia.

Paso 2: Llama a Grok 4.3 desde el navegador

Usa puter.ai.chat() con el modelo x-ai/grok-4.3:

<script src="https://js.puter.com/v2/"></script>

<script>
  puter.ai.chat(
    "Summarize the trade-offs between SQLite and Postgres in three bullets.",
    { model: "x-ai/grok-4.3" }
  ).then((response) => {
    document.body.innerText = response.message.content;
  });
</script>

La primera vez que el usuario ejecute la llamada, Puter le pedirá iniciar sesión o crear una cuenta. Después, las llamadas se cargan a su saldo.

Paso 3: Usa streaming

Puter sigue un patrón similar al de OpenAI, por lo que puedes trabajar con streaming:

const stream = await puter.ai.chat(
  "Walk me through migrating a React app to Next.js.",
  {
    model: "x-ai/grok-4.3",
    stream: true,
    reasoning_effort: "medium",
  }
);

for await (const chunk of stream) {
  process.stdout.write(chunk?.text || "");
}

Pros y contras

Pros	Contras
El desarrollador paga $0	El usuario debe iniciar sesión en Puter
No hay claves API en el repositorio	No es ideal para sistemas solo backend
El mismo cliente permite acceder a varios LLMs	Puede añadir algo de latencia
Encaja bien en apps web públicas	Requiere contexto de navegador

Recomendación: usa Puter.js para herramientas web públicas, proyectos personales, demos gratuitas o apps donde el usuario final sea quien realiza las consultas.

No es la mejor opción para automatizaciones internas, jobs backend o bots donde el usuario no está presente en el navegador.

Para patrones similares con otros modelos, consulta Cómo usar la API de DeepSeek V4 gratis y Cómo usar la API de GPT-5.5 gratis.

Ruta 3: grok.com y la aplicación X

Si solo quieres hablar con Grok 4.3 y no necesitas integrarlo en código, usa las interfaces de chat.

Opciones:

grok.com: chat web con inicio de sesión mediante X.
Aplicación X: Grok está disponible en las aplicaciones web y móviles de X bajo la pestaña Grok.

Estas interfaces son útiles para:

validar prompts antes de llevarlos a la API;
hacer preguntas puntuales;
evaluar si el modelo encaja con tu caso de uso;
comparar respuestas manualmente.

Limitación principal: no puedes automatizar llamadas desde estas interfaces.

El nivel gratuito en grok.com usa por defecto una variante más pequeña de Grok, como Grok 4.1. Las suscripciones Premium en X desbloquean Grok 4.3 en la interfaz de chat con cuotas más altas.

Ruta 4: OpenRouter: barato, pero no gratis para Grok 4.3

OpenRouter agrega múltiples proveedores detrás de una sola clave API y una superficie común.

Grok 4.3 en OpenRouter cuesta lo mismo que xAI directo: $1.25 / $2.50 por 1M de tokens. Por eso no es una ruta gratuita para Grok 4.3.

Sin embargo, OpenRouter sí ofrece variantes gratuitas de algunos modelos de Grok, como:

grok-4-fast:free

Úsalo si necesitas una salida de clase Grok sin pagar, pero no necesitas específicamente Grok 4.3.

Ejemplo:

curl https://openrouter.ai/api/v1/chat/completions \
  -H "Authorization: Bearer $OPENROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "x-ai/grok-4-fast:free",
    "messages": [
      {
        "role": "user",
        "content": "Hello!"
      }
    ]
  }'

Comparación rápida

Ruta	Costo para el desarrollador	Costo para el usuario final	Ideal para
xAI Console con créditos	$0 dentro del crédito	n/a	Prototipos y aprendizaje de la API real
Puter.js	$0	Pocos céntimos por sesión	Apps web públicas y herramientas gratuitas
grok.com / X	$0	$0 con cuota	Uso manual y preguntas puntuales
OpenRouter con modelo gratuito	$0	n/a	Salida tipo Grok, pero no Grok 4.3 específico

Cómo probar proveedores con Apidog

Cuando trabajas con varios proveedores, evita cambiar código a ciegas. Configura solicitudes equivalentes y compara respuestas, tokens y latencia.

Flujo recomendado:

Crea un entorno en Apidog.
Define variables como:
- XAI_API_KEY
- OPENROUTER_API_KEY
- BASE_URL
Crea una solicitud para xAI directo.
Duplica la solicitud para OpenRouter.
Cambia solo:
- la URL base;
- el header de autorización;
- el valor de model.
Ejecuta ambas con el mismo prompt.
Compara respuesta, latencia y consumo.

Ejemplo de cuerpo reutilizable:

{
  "model": "grok-4.3",
  "messages": [
    {
      "role": "user",
      "content": "Explain prompt caching in three sentences."
    }
  ],
  "reasoning_effort": "low"
}

Para xAI:

https://api.x.ai/v1

Para OpenRouter:

https://openrouter.ai/api/v1

Puedes descargar Apidog y crear una colección con ambas variantes. Para más información sobre pruebas entre proveedores, consulta Herramienta de prueba de API para ingenieros de QA.

Lo que pierdes al usar rutas gratuitas

Las rutas gratuitas son suficientes para prototipos, pero tienen límites claros.

1. Límites de tasa más estrictos

Los créditos promocionales no eliminan los límites por minuto. Si pruebas con muchas llamadas concurrentes, puedes recibir errores 429 antes de agotar el crédito.

Implementa backoff:

async function requestWithRetry(fn, retries = 3) {
  for (let i = 0; i < retries; i++) {
    try {
      return await fn();
    } catch (error) {
      if (error.status !== 429 || i === retries - 1) {
        throw error;
      }

      await new Promise((resolve) =>
        setTimeout(resolve, 1000 * Math.pow(2, i))
      );
    }
  }
}

2. El ahorro por prompt caching pesa menos

El almacenamiento en caché de prompts es útil en producción, especialmente con prompts de sistema grandes y repetidos. Pero si solo haces decenas de llamadas durante un prototipo, el ahorro será limitado.

3. El soporte es limitado

Las cuentas gratuitas suelen depender de soporte comunitario o best effort. Si estás depurando producción, necesitas un plan de pago.

Cuándo pasar a pago

Considera pasar a una ruta de pago cuando ocurra cualquiera de estas señales:

Alcanzas límites de tasa de forma frecuente.

Si ves 429 varias veces por semana, los créditos gratuitos ya no son suficientes.
Tienes prompts de sistema grandes y estables.

Si reutilizas prompts de más de 50k tokens, el prompt caching puede tener impacto real.
Necesitas requisitos de cumplimiento.

Auditorías, BAAs, residencia regional de datos o soporte empresarial no suelen estar incluidos en niveles gratuitos.

La migración suele ser simple:

en xAI Console, cambias a una clave con facturación;
en OpenRouter, cambias proveedor o modelo;
en tu código, el esquema de Chat Completions puede mantenerse igual.

Preguntas frecuentes

¿Grok 4.3 es realmente gratis o es una prueba?

Depende de la ruta:

En xAI Console, es una prueba financiada por créditos promocionales.
En Puter.js, es gratis para el desarrollador porque paga el usuario final.
En grok.com, es una cuota diaria de mensajes en la interfaz de chat.

¿Puedo usar Grok 4.3 desde backend sin pagar?

Sí, mientras duren los créditos de xAI Console.

Después de eso, debes pagar o mover el flujo a una ruta donde el usuario cubra el uso, como Puter.js en navegador.

¿Puter.js funciona en Node.js?

Puter.js está pensado principalmente para navegador. El modelo de pago por usuario depende del inicio de sesión del usuario final, por lo que encaja mejor en aplicaciones frontend.

Para backend, la ruta gratuita más directa es xAI Console con créditos.

¿Qué ID de modelo uso en Puter?

Usa:

x-ai/grok-4.3

¿Qué ID de modelo uso directamente en xAI?

Usa:

grok-4.3

¿Los créditos gratuitos cubren llamada de funciones y entrada de video?

Sí. Los créditos se aplican al uso del modelo, incluidas capacidades como contexto largo, llamada de funciones, entrada de video y esfuerzo de razonamiento.

Ten en cuenta que el video puede consumir contexto rápidamente.

¿Cómo se compara esto con Grok Voice?

Grok Voice tiene una estructura diferente y puede tener condiciones gratuitas propias. Para esa guía, consulta Cómo usar Grok Voice gratis.

¿Existe un Grok 4.3 mini gratuito?

No hay un SKU mini separado para Grok 4.3. La alternativa gratuita más cercana mencionada es grok-4-fast:free en OpenRouter, pero no es Grok 4.3.

Conclusión

Hay tres rutas prácticas para usar Grok 4.3 sin pagar durante la fase inicial:

usa xAI Console si quieres probar la API real de producción;
usa Puter.js si estás creando una app web pública y quieres que el usuario cubra su uso;
usa grok.com o X si solo necesitas interacción manual sin código.

Si ninguna encaja, Grok 4.3 sigue siendo relativamente económico a $1.25 / $2.50 por 1M de tokens. Para una implementación completa con la API de pago, consulta Cómo usar la API de Grok 4.3. Para una comparación con OpenAI en voz, consulta Grok Voice vs GPT-Realtime.

Crea la solicitud una vez en Apidog, cambia la URL base por proveedor y elige la ruta que mejor se adapte a tu carga de trabajo.

Cómo Usar la API Grok 4.3: Guía y Tutorial

Roobia — Fri, 08 May 2026 07:42:41 +0000

xAI lanzó Grok 4.3 en etapas: beta el 17 de abril de 2026, acceso a la API el 30 de abril y disponibilidad general completa el 6 de mayo. La propuesta para desarrolladores es clara: ventana de contexto de 1,000,000 de tokens, entrada de video nativa, razonamiento siempre activo y una reducción de precio de aproximadamente el 40% frente a Grok 4.20. Ocho modelos Grok heredados se retiran el 15 de mayo, así que si usa grok-3 o grok-4, planifique la migración ahora.

Prueba Apidog hoy

Esta guía muestra cómo llamar a Grok 4.3 desde código: endpoint, autenticación, URL base compatible con OpenAI, reasoning_effort, entrada de video, llamada a funciones y una configuración reproducible en Apidog.

Para el aspecto de voz de la misma versión, consulte Cómo usar Grok Voice gratis. Para la comparación directa con el modelo de voz insignia de OpenAI, consulte Grok Voice vs GPT-Realtime.

TL;DR

Grok 4.3 tuvo disponibilidad general el 6 de mayo de 2026.
Ocho modelos heredados se retiran el 15 de mayo de 2026.
Precios:
- $1.25 por 1M de tokens de entrada
- $2.50 por 1M de tokens de salida
- $0.20 por 1M de tokens de entrada en caché
Ventana de contexto: 1M de tokens.
Soporta entrada de video nativa.
El razonamiento está siempre activo.
reasoning_effort: low, medium, high. Valor por defecto: medium.
Endpoint: https://api.x.ai/v1/chat/completions.
URL base compatible con OpenAI: https://api.x.ai/v1.
Rendimiento anunciado: ~159 tokens/segundo en niveles estándar.
Índice de Inteligencia 53 según Análisis Artificial, puesto 10 de 146 modelos.
Use Apidog para guardar variantes de solicitud, comparar latencia y reproducir pruebas con distintas configuraciones de razonamiento.

Qué cambió en Grok 4.3

Las actualizaciones más relevantes para implementación son:

Precio más bajo
- Entrada: baja un 37.5% frente a Grok 4.20.
- Salida: baja un 58.3%.
- Entrada en caché: $0.20/1M, útil para prompts de sistema largos y estables.
Contexto de 1M de tokens
- Sube desde 256k en Grok 4.20.
- Permite enviar bases de código medianas, contratos extensos, transcripts largos o historiales completos de conversación.
Entrada de video nativa
- Primera vez en la línea Grok.
- Puede pasar una URL de video y pedir análisis sobre el contenido.
Razonamiento siempre activo
- Cada solicitud incluye razonamiento base.
- reasoning_effort controla la profundidad, pero el modelo nunca baja de low.
Mejor comportamiento agéntico
- +300 puntos Elo en GDPval-AA frente a Grok 4.20.
- Impacta especialmente en llamada a herramientas y flujos de varios pasos.

El Índice de Inteligencia de 53 según Análisis Artificial sitúa a Grok 4.3 por encima del promedio de 35 para su nivel de precio y en el décimo lugar de 146 modelos monitoreados.

Requisitos previos

Antes de hacer la primera llamada, prepare lo siguiente:

Una cuenta en la consola de xAI: console.x.ai.
Una clave API con facturación activa.
El SDK de OpenAI o el SDK de xAI.
Un cliente API para guardar y repetir solicitudes durante las pruebas.

Exporte la clave API:

export XAI_API_KEY="xai-..."

Si usa Windows PowerShell:

$env:XAI_API_KEY="xai-..."

Endpoint y autenticación

Grok 4.3 usa la superficie de Chat Completions compatible con OpenAI.

POST https://api.x.ai/v1/chat/completions

Encabezados requeridos:

Authorization: Bearer $XAI_API_KEY
Content-Type: application/json

La compatibilidad con OpenAI permite usar el SDK de OpenAI y cambiar solo la base_url.

Ejemplo en Python

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["XAI_API_KEY"],
    base_url="https://api.x.ai/v1",
)

response = client.chat.completions.create(
    model="grok-4.3",
    messages=[
        {
            "role": "user",
            "content": "Resume las diferencias entre GraphQL y REST en tres puntos."
        }
    ],
    reasoning_effort="medium",
)

print(response.choices[0].message.content)

Ejemplo en Node.js

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.XAI_API_KEY,
  baseURL: "https://api.x.ai/v1",
});

const response = await client.chat.completions.create({
  model: "grok-4.3",
  messages: [
    {
      role: "user",
      content: "Resume las diferencias entre GraphQL y REST en tres puntos.",
    },
  ],
  reasoning_effort: "medium",
});

console.log(response.choices[0].message.content);

Parámetros de la solicitud

Parámetro	Tipo	Valores	Notas
`model`	string	`grok-4.3`	Obligatorio.
`messages`	array	OpenAI message shape	Obligatorio. Soporta `system`, `user` y `assistant`.
`reasoning_effort`	string	`low`, `medium`, `high`	Opcional. Por defecto: `medium`.
`max_tokens`	int	`1–32768`	Limita la salida.
`temperature`	float	`0.0–2.0`	Por defecto: `1.0`.
`top_p`	float	`0.0–1.0`	Muestreo de núcleo.
`stream`	bool	`true`, `false`	Activa streaming vía server-sent events.
`tools`	array	OpenAI tool shape	Para llamada a funciones.
`tool_choice`	string/object	`auto`, `none` o herramienta específica	Semántica estándar de OpenAI.
`response_format`	object	`{ "type": "json_object" }`	Salida estructurada.
`seed`	int	any	Útil para reproducibilidad con `temperature: 0`.

Primera solicitud con curl

curl https://api.x.ai/v1/chat/completions \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-4.3",
    "messages": [
      {
        "role": "system",
        "content": "Eres un ingeniero backend senior."
      },
      {
        "role": "user",
        "content": "Revisa este plan de consulta y señala el cuello de botella."
      }
    ],
    "reasoning_effort": "high"
  }'

La respuesta mantiene la forma estándar de OpenAI:

{
  "choices": [
    {
      "message": {
        "role": "assistant",
        "content": "..."
      }
    }
  ],
  "usage": {
    "prompt_tokens": 123,
    "completion_tokens": 456,
    "reasoning_tokens": 78,
    "total_tokens": 657
  }
}

Cómo elegir `reasoning_effort`

Use el parámetro según el tipo de carga:

`low`

Úselo para:

Clasificación.
Extracción simple.
Resúmenes cortos.
Preguntas frecuentes.
Reformateo de texto.

Ejemplo:

{
  "model": "grok-4.3",
  "messages": [
    {
      "role": "user",
      "content": "Clasifica este ticket como billing, bug o feature request: ..."
    }
  ],
  "reasoning_effort": "low"
}

`medium`

Úselo para:

Soporte al cliente.
Llamada a funciones.
Análisis de datos moderado.
Flujos de una o dos herramientas.
Tráfico general de producción.

Es el valor por defecto.

{
  "model": "grok-4.3",
  "messages": [
    {
      "role": "user",
      "content": "Analiza estos logs y sugiere la causa probable del error."
    }
  ],
  "reasoning_effort": "medium"
}

`high`

Úselo para:

Agentes de varios pasos.
Revisión de código larga.
Matemáticas complejas.
Planificación.
Decisiones donde el error es costoso.

{
  "model": "grok-4.3",
  "messages": [
    {
      "role": "user",
      "content": "Diseña un plan de migración de esta arquitectura monolítica a servicios separados."
    }
  ],
  "reasoning_effort": "high"
}

El razonamiento siempre activo significa que no existe un modo “sin razonamiento”. Si necesita reducir latencia y tokens, use low.

Llamada a funciones

Grok 4.3 usa la forma estándar de herramientas compatible con OpenAI.

Flujo básico:

Declare las herramientas en tools.
Envíe la solicitud.
Lea tool_calls.
Ejecute la función en su backend.
Devuelva el resultado con un mensaje role: "tool".
Pida al modelo la respuesta final.

Declarar una herramienta

tools = [
    {
        "type": "function",
        "function": {
            "name": "lookup_user",
            "description": "Busca un usuario por ID.",
            "parameters": {
                "type": "object",
                "properties": {
                    "user_id": {
                        "type": "string"
                    }
                },
                "required": ["user_id"]
            }
        }
    }
]

Solicitar una llamada a herramienta

response = client.chat.completions.create(
    model="grok-4.3",
    messages=[
        {
            "role": "user",
            "content": "Busca el usuario u_42 y dime su último inicio de sesión."
        }
    ],
    tools=tools,
    reasoning_effort="medium",
)

message = response.choices[0].message
tool_calls = message.tool_calls

print(tool_calls)

Ejecutar la herramienta y devolver el resultado

import json

def lookup_user(user_id: str):
    return {
        "user_id": user_id,
        "last_login": "2026-05-05T14:22:00Z"
    }

messages = [
    {
        "role": "user",
        "content": "Busca el usuario u_42 y dime su último inicio de sesión."
    },
    message,
]

for call in tool_calls:
    if call.function.name == "lookup_user":
        args = json.loads(call.function.arguments)
        result = lookup_user(args["user_id"])

        messages.append({
            "role": "tool",
            "tool_call_id": call.id,
            "content": json.dumps(result)
        })

final_response = client.chat.completions.create(
    model="grok-4.3",
    messages=messages,
    tools=tools,
    reasoning_effort="medium",
)

print(final_response.choices[0].message.content)

La mejora de 300 puntos Elo en GDPval-AA se nota especialmente en flujos de herramientas: mejor selección de funciones, menos llamadas redundantes y mejor recuperación ante errores. Si prueba flujos MCP, consulte las pruebas de servidor MCP en Apidog.

Entrada de video

Grok 4.3 es el primer modelo Grok con entrada de video nativa. Envíe una URL de video dentro de un bloque de contenido.

response = client.chat.completions.create(
    model="grok-4.3",
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "Describe qué ocurre en este clip y señala anomalías."
                },
                {
                    "type": "video_url",
                    "video_url": {
                        "url": "https://example.com/clip.mp4"
                    }
                }
            ]
        }
    ],
    reasoning_effort="medium",
)

print(response.choices[0].message.content)

Notas prácticas:

Los tokens de video cuentan como entrada.
Los clips largos pueden consumir contexto rápidamente.
Recorte o reduzca la muestra si el costo importa.
No necesita extraer fotogramas clave manualmente; el modelo razona sobre el video de forma nativa.

Entrada de imágenes

Grok 4.3 también soporta imágenes. Use un bloque de contenido con URL de imagen.

response = client.chat.completions.create(
    model="grok-4.3",
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "Identifica posibles problemas de accesibilidad en esta interfaz."
                },
                {
                    "type": "image_url",
                    "image_url": {
                        "url": "https://example.com/screenshot.png"
                    }
                }
            ]
        }
    ],
)

print(response.choices[0].message.content)

Contexto de 1M de tokens

La ventana de contexto de 1M permite patrones que antes requerían chunking agresivo.

Casos comunes:

Revisión de código amplia
- Envíe el diff, archivos modificados, salida del linter y notas de arquitectura.
QA sobre documentos largos
- Inserte contratos, documentación técnica o transcripts completos.
Memoria de agente
- Mantenga historiales largos de conversación para personalización.
Análisis de incidentes
- Combine logs, métricas, timeline y postmortems anteriores.

Ejemplo de prompt para revisión de código:

Eres un revisor de código senior.

Contexto:
- Este cambio toca autenticación y facturación.
- Prioriza bugs de seguridad, condiciones de carrera y errores de compatibilidad.

Archivos:
<pegar diff completo aquí>

Salida del linter:
<pegar salida aquí>

Responde con:
1. Riesgos críticos
2. Riesgos medios
3. Sugerencias no bloqueantes
4. Pruebas que faltan

La entrada en caché a $0.20/1M hace viable mantener prompts de sistema grandes. Por ejemplo, un prompt estable de 400k tokens cuesta $0.08 por llamada en caché frente a $0.50 si se procesa como entrada nueva.

Migración desde modelos Grok heredados

Ocho modelos Grok heredados se retiran el 15 de mayo de 2026, 12:00 PM PT.

Si usa un modelo heredado, el cambio mínimo suele ser:

- model="grok-4"
+ model="grok-4.3"

O en JSON:

{
-  "model": "grok-4"
+  "model": "grok-4.3"
}

La mayoría de las llamadas siguen funcionando porque la forma de la solicitud no cambia.

Revise estos puntos antes de migrar

Latencia
- Grok 4.3 siempre razona.
- Si dependía de una ruta rápida sin razonamiento, pruebe reasoning_effort: "low".
Formato de salida
- Grok 4.3 tiende a generar respuestas más estructuradas.
- Si usa regex para postprocesamiento, vuelva a probar.
Costos
- El precio por token baja, pero el contexto más grande puede llevar a enviar más entrada.
- Mida usage.prompt_tokens, usage.completion_tokens y usage.reasoning_tokens.
Herramientas
- Si usa function calling, valide que las llamadas generadas siguen coincidiendo con su contrato interno.

Para la comparación de precios completa de la línea OpenAI, consulte Precios de GPT-5.5. Para modelos de razonamiento cara a cara, consulte Cómo usar la API de GPT-5.5.

Pruebas en Apidog

Una forma práctica de validar Grok 4.3 es crear una colección con variantes controladas.

1. Cree un entorno

En Apidog, cree variables:

XAI_API_KEY = xai-...
BASE_URL = https://api.x.ai/v1
MODEL = grok-4.3

2. Cree la solicitud base

POST {{BASE_URL}}/chat/completions
Authorization: Bearer {{XAI_API_KEY}}
Content-Type: application/json

Body:

{
  "model": "{{MODEL}}",
  "messages": [
    {
      "role": "system",
      "content": "Eres un ingeniero backend senior."
    },
    {
      "role": "user",
      "content": "Analiza este error de producción y sugiere la causa raíz: {{incident_log}}"
    }
  ],
  "reasoning_effort": "medium"
}

3. Duplique la solicitud en tres variantes

Cree tres copias con el mismo prompt:

"reasoning_effort": "low"

"reasoning_effort": "medium"

"reasoning_effort": "high"

Compare:

Latencia.
Calidad de respuesta.
usage.reasoning_tokens.
usage.total_tokens.
Costo estimado.

4. Compare contra otro proveedor

Puede crear otra variante cambiando:

BASE_URL = https://api.openai.com/v1
MODEL = gpt-5.5

Así mantiene la misma estructura de prueba y cambia solo proveedor/modelo.

Descargue Apidog para ejecutar la comparación. Para una estrategia más amplia de pruebas de API, consulte Herramienta de pruebas de API para ingenieros de QA.

Streaming

Para respuestas largas, active stream.

stream = client.chat.completions.create(
    model="grok-4.3",
    messages=[
        {
            "role": "user",
            "content": "Genera un plan técnico para migrar este servicio a una arquitectura event-driven."
        }
    ],
    reasoning_effort="medium",
    stream=True,
)

for event in stream:
    delta = event.choices[0].delta
    if delta.content:
        print(delta.content, end="")

Use streaming cuando:

La salida sea larga.
La experiencia de usuario necesite respuesta progresiva.
Quiera reducir tiempo percibido hasta el primer token.

Salida JSON estructurada

Para integraciones backend, use response_format.

response = client.chat.completions.create(
    model="grok-4.3",
    messages=[
        {
            "role": "user",
            "content": "Extrae prioridad, categoría y resumen de este ticket: ..."
        }
    ],
    response_format={
        "type": "json_object"
    },
    temperature=0,
)

print(response.choices[0].message.content)

Ejemplo de salida esperada:

{
  "priority": "high",
  "category": "billing",
  "summary": "El usuario no puede completar el pago por un error de validación."
}

Límites de velocidad

Los límites dependen del nivel configurado en la consola de xAI. Van desde unos pocos miles de solicitudes por minuto en niveles iniciales hasta cientos de miles en niveles empresariales.

Puntos importantes:

Consulte los límites exactos en el panel de xAI.
Los ~159 tokens/segundo son velocidad de salida por stream, no throughput agregado.
Las solicitudes concurrentes escalan dentro del límite de su nivel.
Si supera el límite, la API devuelve 429.

Ejemplo de manejo básico con backoff:

import time
from openai import RateLimitError

for attempt in range(5):
    try:
        response = client.chat.completions.create(
            model="grok-4.3",
            messages=[
                {
                    "role": "user",
                    "content": "Resume este documento."
                }
            ],
        )
        break
    except RateLimitError:
        wait = 2 ** attempt
        time.sleep(wait)

Checklist de producción

Antes de mover tráfico real a Grok 4.3:

[ ] Cambie base_url a https://api.x.ai/v1.
[ ] Cambie model a grok-4.3.
[ ] Defina reasoning_effort explícitamente.
[ ] Mida usage.reasoning_tokens.
[ ] Valide outputs si usa regex o parsers estrictos.
[ ] Pruebe function calling con casos felices y errores.
[ ] Active streaming para respuestas largas.
[ ] Use caché cuando el prompt de sistema sea estable.
[ ] Configure reintentos para 429.
[ ] Migre antes del 15 de mayo si usa modelos heredados.

Preguntas frecuentes

¿Grok 4.3 es compatible con OpenAI de principio a fin?

Para Chat Completions, sí. Puede usar el SDK de OpenAI, cambiar base_url y cambiar model. Function calling, salida estructurada y streaming usan formas compatibles.

¿Soporta la API de Responses?

La superficie de xAI es Chat Completions actualmente. La API de Responses es de OpenAI.

¿Cuál es el límite de contexto real?

1,000,000 de tokens. Aun con el precio reducido, las entradas largas cuestan dinero real. Use caché si su prompt es estable.

¿Cómo afecta el razonamiento siempre activo a la latencia?

La latencia hasta el primer token puede ser superior a modelos sin razonamiento. A cambio, Grok 4.3 transmite salida a ~159 tokens/segundo y mejora en cargas donde la precisión importa.

¿Puedo usar Grok 4.3 con Grok Voice?

Sí. El agente de voz grok-voice-think-fast-1.0 llama a Grok 4.3 internamente cuando razona. También puede llamar a Grok 4.3 directamente desde un loop de voz construido con TTS y STT.

¿Qué pasa con llamadas antiguas a Grok 3 o Grok 4 después del 15 de mayo?

Fallarán con un 410 por modelo retirado. Migre antes de la fecha límite.

¿Grok 4.3 soporta imágenes?

Sí. Además de video, puede enviar imágenes usando un bloque image_url.

Conclusión

Grok 4.3 combina menor precio, contexto de 1M, razonamiento siempre activo y video nativo. Para equipos que ya usan una interfaz compatible con OpenAI, la migración suele ser un cambio de base_url y model, no una reescritura completa.

La ruta más rápida: cree tres variantes en Apidog con reasoning_effort en low, medium y high, ejecute sus prompts reales, mida latencia y tokens, y migre antes del 15 de mayo.

Grok Voice vs GPT-Realtime: ¿Qué Modelo de Voz es Mejor en 2026?

Roobia — Fri, 08 May 2026 07:36:21 +0000

xAI lanzó Grok Voice la misma semana que OpenAI presentó GPT-Realtime-2. Si estás eligiendo un modelo de voz para 2026, ahora tienes dos opciones creíbles: ambos son modelos voz-a-voz con razonamiento, funcionan por WebSocket, admiten herramientas y generan habla con inflexión humana. La decisión práctica se reduce a cinco variables: latencia, precio, catálogo de voces, profundidad de razonamiento y si necesitas SIP, entrada de imagen o clonación de voz.

Prueba Apidog hoy

En esta guía comparo ambos modelos desde el punto de vista de implementación: qué elegir, cuándo elegirlo y cómo probarlos lado a lado antes de comprometerte.

Para guías independientes, consulta Cómo usar GPT-Realtime-2 y Cómo usar Grok Voice gratis. Para pruebas de estrés con sesiones WebSocket, Apidog gestiona conexiones WebSocket de forma nativa.

En resumen

Grok Voice (grok-voice-think-fast-1.0) gana en latencia, acceso gratuito a la consola, catálogo de voces y clonación de voz.
GPT-Realtime-2 gana en profundidad de razonamiento, entrada de imagen, SIP nativo, MCP y madurez para producción.
Para uso de pago, GPT-Realtime-2 cuesta $32/$64 por 1M de tokens de audio. Grok Voice no cobra audio por minuto en la consola; pagas el razonamiento de Grok 4.3 a $1.25/$2.50 por 1M de tokens.
Elige Grok Voice para aplicaciones de consumo de alto volumen, baja latencia y clonación de voz.
Elige GPT-Realtime-2 para razonamiento complejo, agentes multimodales y centros de llamadas con SIP.
Puedes construir una comparación una vez con Apidog y cambiar de modelo modificando la URL WebSocket.

Los dos modelos en una tabla

Capacidad	Grok Voice (`grok-voice-think-fast-1.0`)	GPT-Realtime-2
Tiempo hasta el primer audio	< 1 segundo; xAI afirma ~5 veces más rápido que el competidor más cercano	Sub-segundo con razonamiento `low`; más lento en `high` / `xhigh`
Niveles de razonamiento	Bajo / medio / alto, con Grok 4.3 como base	Mínimo / bajo / medio / alto / muy alto
Inteligencia subyacente	Grok 4.3, Índice de Inteligencia 53	Clase GPT-5
Ventana de contexto	1.000.000 de tokens, vía Grok 4.3	128.000 tokens
Voces preestablecidas	80+; 5 personajes de agente: Eve, Ara, Rex, Sal, Leo	10; Cedar, Marin y 8 voces reajustadas
Idiomas TTS	28	No contados oficialmente
Idiomas STT	25	Heredados de GPT-Realtime
Clonación de voz	Sí; muestra de 1 minuto, entrenamiento de <2 minutos	No
Entrada de imagen	No; texto + audio	Sí; foto o captura de pantalla
Servidores MCP remotos	Herramientas sí; MCP nativo no anunciado	Sí
SIP nativo / llamadas telefónicas	Requiere proveedor SIP propio	Sí, endpoint `?call_id={call_id}`
Formatos de audio	PCM16, MP3, μ-law	PCM16, G.711 μ-law, A-law
Modelo de precios	Gratis en consola para voz; pagas razonamiento de Grok 4.3	$32/1M audio input, $64/1M audio output, $4/$24 por 1M de texto
Cumplimiento	SOC 2 Tipo II, elegible para HIPAA con BAA, GDPR	SOC 2, GDPR según OpenAI Enterprise

Latencia: Grok gana por un margen claro

La afirmación de xAI de que grok-voice-think-fast-1.0 es "casi 5 veces más rápido que el competidor más cercano" viene de sus propios benchmarks, así que conviene tratar el multiplicador con cautela.

Aun así, la dirección es clara: Grok suele entregar el primer audio por debajo de un segundo. GPT-Realtime-2 suele moverse entre 800 ms y 1500 ms, según el nivel de razonamiento.

En una aplicación de voz, esta diferencia se nota. Entre 600 ms y 1200 ms hay una diferencia perceptible: el agente puede sentirse natural o puede sentirse como un bot esperando turno.

Regla práctica:

Si el usuario final está hablando desde un móvil y la experiencia debe sentirse instantánea, empieza con Grok Voice.
Si el agente necesita razonar más antes de responder, acepta más latencia y prueba GPT-Realtime-2.

Precios: no comparan igual

Aquí no basta con mirar una sola tabla de precios porque los modelos cobran de forma distinta.

GPT-Realtime-2

GPT-Realtime-2 mide la voz como tokens de audio:

Audio de entrada: $32 por 1M de tokens
Audio de salida: $64 por 1M de tokens
Texto: $4/$24 por 1M de tokens

Un segundo de audio equivale aproximadamente a 50 tokens. Una conversación de 5 minutos con turnos equilibrados puede consumir unos 30.000 tokens de audio, lo que da un coste aproximado de $1.50 en entrada/salida de audio. La entrada en caché reduce el coste de prompts del sistema estables.

Grok Voice

Grok Voice no cobra por minuto ni por token de voz en la Consola xAI para:

TTS
STT
Agente de voz
Voces personalizadas

Pagas solo el razonamiento de Grok 4.3:

Entrada: $1.25 por 1M de tokens
Salida: $2.50 por 1M de tokens

Para una llamada equivalente de 5 minutos, los tokens de razonamiento suelen ser mucho menos que los tokens de audio, por lo que el coste puede quedar por debajo de $0.10.

Recomendación:

Para más de 10.000 minutos/día, Grok Voice suele tener mejor economía unitaria.
Para bajo volumen y alto valor por llamada, deja que decida la calidad de razonamiento, no el precio.

Más detalles: Cómo usar la API de Grok 4.3 y Precios de GPT-5.5.

Profundidad de razonamiento: OpenAI gana

GPT-Realtime-2 es el primer modelo voz-a-voz que OpenAI describe como clase GPT-5. En Big Bench Audio obtuvo 96.6%, frente al 81.4% del modelo anterior. En Audio MultiChallenge obtuvo 48.5%, frente al 34.7%.

Además, ofrece cinco niveles de razonamiento:

minimal
low
medium
high
xhigh

Esto permite controlar el intercambio entre latencia y calidad por solicitud.

Grok Voice funciona sobre Grok 4.3. Grok 4.3 alcanzó Índice de Inteligencia 53 en Artificial Analysis, ocupando el puesto 10 de 146 modelos a nivel mundial. Es fuerte, especialmente en tareas de agente, pero los benchmarks publicados todavía favorecen a GPT-Realtime-2 en razonamiento voz-a-voz.

Implementación recomendada:

Usa GPT-Realtime-2 para flujos con desambiguación, múltiples herramientas o contexto largo.
Usa Grok Voice para soporte directo, respuestas rápidas, flujos guiados y ventas con guion.

Catálogo de voces: Grok gana en cantidad, OpenAI en consistencia

Grok ofrece más de 80 voces preestablecidas en 28 idiomas. El agente de voz usa cinco personajes curados:

Eve
Ara
Rex
Sal
Leo

Además, Grok ofrece clonación de voz mediante voces personalizadas.

GPT-Realtime-2 ofrece 10 voces:

Cedar
Marin
alloy
ash
ballad
coral
echo
sage
shimmer
verse

La biblioteca es más pequeña, pero la consistencia entre voces es alta. Todas usan la misma pila de audio y el control de entonación se comporta de forma más predecible.

Recomendación:

Si necesitas una voz concreta, un acento regional o una voz de marca, prueba Grok.
Si necesitas una voz de alta calidad y comportamiento uniforme, GPT-Realtime-2 es suficiente.

Clonación de voz: solo Grok la ofrece

Las voces personalizadas de xAI permiten crear un voice_id a partir de aproximadamente un minuto de habla limpia. El entrenamiento tarda menos de dos minutos y el mismo voice_id funciona en TTS y en el agente de voz.

OpenAI no expone clonación de voz en la API Realtime.

Si tu caso de uso necesita clonación de voz, la decisión es directa: Grok Voice.

Entrada de imagen: solo OpenAI la ofrece

GPT-Realtime-2 acepta texto, audio e imágenes. Puedes enviar una captura de pantalla o una foto dentro de un turno de usuario y hacer que el agente responda en voz.

Casos donde esto importa:

Soporte técnico en campo
QA por voz
Accesibilidad
Agentes que guían al usuario viendo la misma pantalla

Grok Voice no puede igualar esto hoy porque trabaja con texto y audio.

Para más contexto sobre visión en OpenAI, consulta Cómo usar la API de GPT-Image-2.

SIP y telefonía: OpenAI lo trae nativo, Grok necesita puente

La API Realtime de OpenAI tiene soporte SIP nativo. Puedes dirigir un troncal SIP a la puerta de enlace de OpenAI y abrir una sesión WebSocket con:

wss://api.openai.com/v1/realtime?call_id={call_id}

Esto elimina la necesidad de mantener tu propia capa de puente.

Grok Voice admite salida μ-law para telefonía, pero necesitas traer tu proveedor SIP, por ejemplo:

Twilio
Telnyx
Plivo

Después debes ejecutar el puente entre telefonía y WebSocket por tu cuenta.

Recomendación:

Para un agente de centro de llamadas con integración rápida, GPT-Realtime-2 es más directo.
Para un producto con infraestructura SIP propia, Grok sigue siendo viable, pero requiere más ingeniería.

MCP y uso de herramientas

Ambos modelos admiten invocación de funciones, pero no con el mismo nivel de integración.

GPT-Realtime-2

GPT-Realtime-2 admite servidores MCP remotos de forma nativa. Configuras:

URL del servidor MCP
Lista de herramientas permitidas
Política de ejecución

La API Realtime puede ejecutar las herramientas sin que tu servidor esté en el bucle crítico de cada llamada.

Grok Voice

Grok Voice admite invocación de funciones y ofrece una herramienta web_search incorporada. MCP nativo todavía no está anunciado como primitiva de primera clase.

Regla práctica:

Si tu agente usa más de 50 herramientas, GPT-Realtime-2 con MCP es más cómodo.
Si tu agente usa 5 herramientas o menos, la invocación de funciones simple es suficiente en cualquiera de los dos.

Para probar servidores MCP por separado, consulta Pruebas de servidor MCP en Apidog.

Decisión rápida por caso de uso

Aplicación de voz para consumidores, alto volumen y latencia crítica: Grok Voice.
Clonación de voz, voz de marca o voces de personajes: Grok Voice.
TTS multilingüe a escala con más de 10 idiomas: Grok Voice.
Agente que necesita interpretar capturas de pantalla: GPT-Realtime-2.
Centro de llamadas con SIP: GPT-Realtime-2.
Agente con razonamiento de múltiples pasos y más de 50 herramientas: GPT-Realtime-2.
Conversaciones con más de 50k tokens de historial: GPT-Realtime-2 si priorizas Realtime; Grok 4.3 tiene contexto mayor si puedes asumir el coste del flujo.
Agente de voz de producción más barato: Grok Voice en consola.
Razonamiento intensivo con benchmarks más fuertes: GPT-Realtime-2 con xhigh.

Cómo probar ambos antes de comprometerte

No elijas uno a ciegas. Construye una prueba reproducible y mide durante una semana.

1. Define una conversación de prueba

Incluye como mínimo:

10 turnos de diálogo
1 llamada a herramienta
1 caso de desambiguación
1 respuesta larga
Audio real de usuarios, no solo texto sintético

Ejemplo de flujo:

Usuario: Tengo un problema con mi factura.
Agente: ¿Puedes confirmar el número de cuenta?
Usuario: Sí, es 12345.
Agente: Llama a herramienta get_invoice(account_id).
Agente: Explica el resultado y ofrece siguiente acción.

2. Configura variables de entorno

Usa claves separadas para cada proveedor:

XAI_API_KEY=...
OPENAI_API_KEY=...

3. Crea dos URLs WebSocket

Para Grok Voice:

wss://api.x.ai/v1/realtime?model=grok-voice-think-fast-1.0

Para GPT-Realtime-2:

wss://api.openai.com/v1/realtime?model=gpt-realtime-2

4. Ejecuta la misma secuencia de mensajes

Mantén idénticos:

Prompt del sistema
Audio de entrada
Herramientas disponibles
Orden de turnos
Métricas capturadas

5. Mide resultados comparables

Registra por ejecución:

Tiempo hasta el primer audio
Duración total de respuesta
Errores WebSocket
Interrupciones manejadas correctamente
Tokens usados
Coste estimado
Calidad subjetiva de la respuesta
Precisión en llamadas a herramientas

Puedes descargar Apidog para ejecutar la comparación lado a lado. El formato de colección es portátil, así que puedes versionar el artefacto de prueba junto al código.

Preguntas frecuentes

¿Puedo usar ambos modelos en la misma aplicación?

Sí. Puedes enrutar en tiempo de ejecución según intención, idioma, coste o complejidad.

Ejemplo de estrategia:

Consulta simple + latencia crítica -> Grok Voice
Consulta compleja + muchas herramientas -> GPT-Realtime-2
Usuario envía imagen -> GPT-Realtime-2
Voz personalizada requerida -> Grok Voice

El coste de una capa de enrutamiento suele ser pequeño comparado con el coste total de la conversación.

¿Cuál tiene mejor calidad de voz en idiomas no ingleses?

Grok gana en cobertura: más de 80 voces y 28 idiomas en TTS. En idiomas que ambos cubren, la diferencia práctica depende del idioma, acento y tipo de conversación. Lo correcto es probar los idiomas específicos que necesitas.

¿Vale la pena GPT-Realtime-2 si cuesta más?

Depende del flujo.

Para un agente de preguntas frecuentes, probablemente no. Para un agente de ventas o soporte que debe leer un CRM, llamar herramientas, recuperarse de interrupciones y razonar sobre contexto, la diferencia puede justificarse.

¿Alguno permite clonar voces de figuras públicas?

No. Ambos proveedores filtran la clonación a muestras consentidas. Clonar una figura pública sin permiso viola los términos de servicio de ambas plataformas.

¿Cómo migro de uno a otro más tarde?

Los nombres de eventos difieren, pero la estructura general es parecida:

session.update
user audio input
assistant audio output
tool call
tool result
session end

Planifica una migración de aproximadamente un día para ajustar payloads, eventos y controladores. Si construyes las pruebas con Apidog, la colección de solicitudes se puede portar de forma limpia.

Conclusión

No hay una respuesta universal entre Grok Voice y GPT-Realtime-2. Hay una respuesta correcta por caso de uso.

Elige Grok Voice si estás construyendo una aplicación de voz rápida, de alto volumen, orientada al consumidor o con clonación de voz.

Elige GPT-Realtime-2 si necesitas razonamiento más profundo, entrada de imagen, MCP, SIP nativo o una integración más directa para centros de llamadas.

Para el resto de casos, construye una prueba reproducible en Apidog, ejecuta ambos modelos durante una semana y decide con datos.

Cómo Usar Grok Voice Gratis: Configuración, Clonación de Voz y Agentes de Voz en Tiempo Real

Roobia — Fri, 08 May 2026 07:31:26 +0000

xAI lanzó Grok Voice con Grok 4.3, y lo importante para desarrolladores es directo: está disponible gratis desde la Consola xAI. No hay cargo por minuto ni por token para el agente de voz, texto a voz, voz a texto o Voces Personalizadas. El único recurso facturable es el uso subyacente de tokens de Grok 4.3 cuando el agente razona, y la consola incluye asignación gratuita para pruebas.

Prueba Apidog hoy

En esta guía vas a levantar Grok Voice sin costo, clonar una voz, abrir una sesión WebSocket y validar el flujo completo con Apidog antes de integrarlo en una aplicación.

Si también necesitas la guía completa de la API de Grok 4.3, o una comparación directa contra OpenAI en Grok Voice vs GPT-Realtime, esas publicaciones cubren el resto de la superficie.

En resumen

Grok Voice es gratis para usuarios de la Consola xAI (console.x.ai): sin cargo por minuto ni por token para TTS, STT, agente de voz o Voces Personalizadas.
Modelo principal: grok-voice-think-fast-1.0.
Tiempo hasta el primer audio: menos de 1 segundo; xAI afirma que es aproximadamente 5 veces más rápido que el competidor más cercano.
Más de 80 voces preestablecidas en 28 idiomas.
5 personas de agente de voz integradas: Eve, Ara, Rex, Sal y Leo.
Clonación de voz personalizada desde aproximadamente 1 minuto de habla.
Voz lista para producción en menos de 2 minutos.
Endpoint WebSocket:

wss://api.x.ai/v1/realtime?model=grok-voice-think-fast-1.0

Los endpoints REST para TTS, STT y Voces Personalizadas comparten una única superficie de API.
Puedes usar Apidog para preparar, ejecutar y repetir sesiones WebSocket sin volver a grabar audio.

Lo que Grok Voice ofrece gratis

La Consola xAI es el punto de entrada. Inicia sesión en console.x.ai, genera una clave de API y podrás llamar a estas cuatro superficies sin cargos asociados a las funciones de voz.

Superficies disponibles

Agente de Voz: conversación habla-a-habla en tiempo real, con uso de herramientas, detección de actividad de voz del lado del servidor y gestión de turnos.
Texto a Voz: más de 80 voces preestablecidas en 28 idiomas, con salida MP3 o μ-law para telefonía.
Voz a Texto: transcripción en streaming y por lotes en 25 idiomas de entrada, con marcas de tiempo por palabra y diarización de hablantes.
Voces Personalizadas: clonación de voz desde una muestra corta; el voice_id resultante funciona en TTS y en el agente de voz.

El único medidor que se activa es el uso de tokens de Grok 4.3 cuando el agente necesita razonar sobre una solicitud. La consola incluye crédito gratuito para probar esta parte, suficiente para validar flujos de extremo a extremo antes de pasar a producción.

Paso 1: Obtén una clave de consola

Ve a console.x.ai e inicia sesión con tu cuenta de X. En la página API Keys, crea una clave nueva con los alcances voice y chat habilitados.

Exporta la clave como variable de entorno:

export XAI_API_KEY="xai-..."

Para verificar que tu entorno está configurado:

echo $XAI_API_KEY

Si vas a construir una aplicación web, no expongas esta clave en el navegador. En su lugar, genera un token efímero desde la configuración de la consola o desde el endpoint:

/v1/realtime/sessions

Los tokens efímeros tienen el mismo alcance, pero expiran en minutos. Úsalos para conectar clientes web sin filtrar la clave principal.

Paso 2: Elige una voz

Tienes dos opciones: usar una voz preestablecida o clonar una voz personalizada.

Opción A: usar voces preestablecidas

El agente de voz incluye cinco personas nombradas:

Eve: femenina, enérgica. Útil para soporte con tono optimista.
Ara: femenina, cálida. Buena opción para asistencia general.
Rex: masculino, seguro. Útil para guiones comerciales.
Sal: neutral, suave. Adecuada para narración y lecturas largas.
Leo: masculino, autoritario. Útil para cumplimiento y flujos formales.

Para TTS, la biblioteca es mayor: más de 80 voces en 28 idiomas. Se seleccionan con el parámetro voice en el endpoint de texto a voz.

Opción B: clonar una voz personalizada

Prepara un archivo WAV con aproximadamente un minuto de habla limpia de un solo hablante. Luego súbelo al endpoint de Voces Personalizadas:

curl https://api.x.ai/v1/custom-voices \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -F "name=narrator-jane" \
  -F "language=en" \
  -F "audio=@sample.wav"

La respuesta incluye un voice_id. Ese mismo ID puede usarse en TTS y en el agente de voz.

Buenas prácticas para la muestra:

Usa una habitación silenciosa.
Graba una sola voz.
Evita música o ruido de fondo.
Mantén volumen y distancia constantes.
No asumas que más duración mejora el resultado; el máximo es 120 segundos, pero una muestra limpia de 60 segundos suele ser más útil que una muestra larga con ruido.

Paso 3: Abre una sesión WebSocket

El agente de voz funciona como una única sesión WebSocket:

Abres la conexión.
Configuras la sesión.
Envías audio de entrada.
Recibes audio de salida en streaming.

Endpoint:

wss://api.x.ai/v1/realtime?model=grok-voice-think-fast-1.0

Cliente mínimo en Node.js:

import WebSocket from "ws";

const ws = new WebSocket(
  "wss://api.x.ai/v1/realtime?model=grok-voice-think-fast-1.0",
  {
    headers: {
      Authorization: `Bearer ${process.env.XAI_API_KEY}`,
    },
  }
);

ws.on("open", () => {
  ws.send(JSON.stringify({
    type: "session.update",
    session: {
      voice: "ara",
      instructions: "You are a friendly support agent. Keep replies under two sentences.",
      input_audio_format: "pcm16",
      output_audio_format: "pcm16",
      turn_detection: {
        type: "server_vad",
      },
    },
  }));
});

ws.on("message", (raw) => {
  const event = JSON.parse(raw.toString());

  if (event.type === "response.audio.delta") {
    process.stdout.write(Buffer.from(event.delta, "base64"));
  }

  if (event.type === "response.audio.done") {
    console.error("Turno completado");
  }
});

El audio del usuario se envía como eventos input_audio_buffer.append, usando tramas PCM16 codificadas en base64. El servidor responde con eventos response.audio.delta mientras genera audio, y con response.audio.done cuando termina el turno.

Formato recomendado:

Usa pcm16 a 24 kHz para navegador o escritorio.
Usa mulaw cuando conectes el flujo a telefonía.

Paso 4: Envía audio al WebSocket

El patrón de envío es:

ws.send(JSON.stringify({
  type: "input_audio_buffer.append",
  audio: base64Pcm16Frame,
}));

Después de enviar suficiente audio, puedes pedir una respuesta:

ws.send(JSON.stringify({
  type: "response.create",
}));

En una integración real, base64Pcm16Frame vendrá del micrófono, de un archivo de prueba o de una capa de telefonía. Para pruebas automatizadas, conviene usar siempre el mismo fragmento de audio y comparar los eventos de salida entre ejecuciones.

Paso 5: Añade uso de herramientas

El agente de voz soporta invocación de funciones. Esto permite que el modelo consulte tus APIs durante una conversación.

Primero declara una herramienta en la sesión:

ws.send(JSON.stringify({
  type: "session.update",
  session: {
    tools: [
      {
        type: "function",
        name: "lookup_order",
        description: "Look up the status of a customer order by order number.",
        parameters: {
          type: "object",
          properties: {
            order_id: {
              type: "string",
            },
          },
          required: ["order_id"],
        },
      },
    ],
  },
}));

Cuando el modelo quiera invocar la herramienta, emitirá un evento:

response.function_call_arguments.done

Tu aplicación debe:

Leer los argumentos generados por el modelo.
Ejecutar la función en tu backend.
Enviar el resultado de vuelta con un conversation.item.create de tipo function_call_output.
Permitir que el modelo continúe y narre la respuesta al usuario.

También existe una herramienta incorporada web_search, útil cuando necesitas respuestas basadas en información reciente sin construir tu propia capa de recuperación.

Paso 6: Usa TTS sin el agente de voz

Si solo necesitas convertir texto a audio, no abras WebSocket. Usa el endpoint REST de TTS.

Ejemplo:

curl https://api.x.ai/v1/tts \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-tts-1",
    "voice": "ara",
    "input": "Welcome back to your account. Your last login was Tuesday at 3pm.",
    "format": "mp3"
  }' \
  --output greeting.mp3

Formatos disponibles:

mp3: alta fidelidad.
mulaw: 8 kHz, útil para telefonía.

Este endpoint es síncrono: envías texto y recibes bytes de audio. No necesitas streaming.

Paso 7: Prueba el flujo completo en Apidog

Depurar WebSockets desde la terminal es incómodo porque la conversación tiene estado. Un flujo más práctico es preparar una colección reproducible en Apidog.

Patrón recomendado:

Crea una solicitud WebSocket con esta URL:

wss://api.x.ai/v1/realtime?model=grok-voice-think-fast-1.0

Guarda XAI_API_KEY como variable de entorno.
Añade el header:

Authorization: Bearer {{XAI_API_KEY}}

Prepara mensajes JSON en secuencia:

{
  "type": "session.update",
  "session": {
    "voice": "ara",
    "instructions": "You are a concise support agent.",
    "input_audio_format": "pcm16",
    "output_audio_format": "pcm16",
    "turn_detection": {
      "type": "server_vad"
    }
  }
}

{
  "type": "input_audio_buffer.append",
  "audio": "BASE64_PCM16_AUDIO_FRAME"
}

{
  "type": "response.create"
}

Ejecuta la sesión y captura los eventos del servidor.
Repite la misma sesión cambiando voice o instructions.
Compara las salidas para detectar cambios en tono, latencia, turnos o comportamiento de herramientas.

Descarga Apidog, crea una solicitud WebSocket y guarda la clave en variables de entorno. La misma colección puede incluir TTS y STT porque son endpoints REST simples. Para más patrones de prueba de APIs con estado, consulta Herramienta de pruebas de API para ingenieros de QA.

Límites de la capa gratuita

La consola da acceso completo sin cargo por minuto ni por token para las funciones de voz. Los límites relevantes son:

Límites de tasa: la consola impone límites de solicitudes por minuto por endpoint para prevenir abusos. Sirven para construir y hacer demos, no para producción de alto volumen.
Cuota de Voces Personalizadas: una cuenta puede mantener un número finito de clones personalizados a la vez. Puedes eliminar clones antiguos para liberar espacio.
Tokens de razonamiento: cuando el agente usa Grok 4.3 para razonar, ese consumo se descuenta del crédito de consola. El crédito gratuito cubre prototipos; producción requiere plan de pago.

Si recibes errores de límite de tasa, agrupa solicitudes, reduce concurrencia o cambia a un nivel de pago. El comportamiento de la API no cambia; solo cambian los límites.

Cómo comparar voces antes de producción

Antes de elegir una voz, ejecuta la misma lista de frases con cada preset.

Usa al menos:

Un saludo de dos frases.
Una confirmación corta: “Entendido, todo listo”.
Una frase larga con número, fecha y coma.
Una respuesta de error.
Una frase con tono urgente.

Ejemplo de texto de prueba:

Hola, soy tu asistente de soporte. Puedo ayudarte a revisar el estado de tu pedido o actualizar la información de tu cuenta.

Entendido, todo listo.

Tu pedido número 48291 fue actualizado el martes 14 de mayo, y debería llegar antes de las 5 de la tarde.

La prueba práctica es reproducir el mismo mensaje en tres estilos: calmado, normal y urgente. Escucha si la voz mantiene claridad, ritmo e intención. Las voces preestablecidas de Grok manejan bien estos cambios, pero conviene auditar antes de salir en vivo.

Preguntas frecuentes

¿La API es realmente gratuita?

Las funciones de voz —TTS, STT, agente de voz y Voces Personalizadas— no tienen cargo por minuto ni por token en la consola. El modelo de razonamiento subyacente se factura contra el crédito de consola. La asignación gratuita es suficiente para prototipos.

¿Necesito una cuenta de X?

Sí. El inicio de sesión en la consola utiliza una cuenta de X.

¿Puedo usar Grok Voice desde un navegador?

Sí. Usa un token efímero. Genéralo desde tu backend mediante /v1/realtime/sessions, entrégalo al navegador y conecta el WebSocket directamente. La clave principal debe quedarse en tu servidor.

¿Qué calidad de audio puedo esperar?

TTS puede devolver MP3 de alta fidelidad o μ-law de 8 kHz. El agente de voz usa PCM16 a 24 kHz internamente. La calidad está al nivel de motores comerciales de TTS; la latencia es el diferenciador.

¿Funciona con telefonía?

Sí. La salida μ-law es estándar para puentes SIP y PSTN. Aun así, necesitas un proveedor SIP externo; xAI no ofrece actualmente una pasarela SIP propia.

¿Cómo se compara la clonación con otras herramientas?

La calidad depende más de la limpieza del audio de referencia que de la duración. Una muestra limpia de 60 segundos en una habitación silenciosa supera a una muestra ruidosa de 120 segundos. El voice_id resultante funciona tanto en TTS como en el agente de voz.

¿Puedo usar Grok Voice para personajes de IA en un juego?

Sí. El endpoint TTS es lo suficientemente rápido para generación en tiempo de ejecución, y las Voces Personalizadas permiten que cada personaje tenga su propio clon. Para líneas largas, usa generación por fragmentos para controlar latencia.

Conclusión

Grok Voice es una de las rutas más directas para prototipar agentes de voz en tiempo real en 2026: acceso gratuito desde la consola, baja latencia, WebSocket para conversación y clonación de voz integrada.

La forma más rápida de validarlo es:

Crear una clave en console.x.ai.
Probar una voz preestablecida.
Abrir una sesión WebSocket.
Ejecutar el mismo flujo en Apidog con varias voces.
Medir latencia, calidad y comportamiento de turnos.

Cuando quieras conectarlo con razonamiento más amplio, revisa la guía de la API de Grok 4.3. Para comparar contra OpenAI, consulta Grok Voice vs GPT-Realtime.

Qué es GPT-Realtime-2 y Cómo Usar la API de GPT-Realtime-2

Roobia — Fri, 08 May 2026 07:25:57 +0000

OpenAI lanzó una nueva generación de modelos de voz el 6 de noviembre de 2026. El lanzamiento principal es GPT-Realtime-2: un modelo voz a voz con razonamiento de clase GPT-5, ventana de contexto de 128,000 tokens y esfuerzo de razonamiento configurable para equilibrar latencia y calidad. Si ya usa gpt-realtime, la migración consiste principalmente en cambiar el ID del modelo y ajustar algunos campos de sesión y herramientas.

Prueba Apidog hoy

Esta guía explica qué es GPT-Realtime-2, qué cambió frente al modelo anterior, cómo se factura y cómo conectarlo por WebSocket o SIP. También incluye un flujo práctico con Apidog para reproducir sesiones en tiempo real sin volver a grabar audio en cada prueba.

Para contexto sobre la línea de modelos de OpenAI para 2026, consulte Qué es GPT-5.5. Para el modelo multimodal de imagen, consulte Cómo usar la API de GPT-Image-2.

TL;DR

GPT-Realtime-2 es el modelo voz a voz insignia de OpenAI con razonamiento de clase GPT-5, contexto de 128k y hasta 32k tokens de salida.
El audio cuesta $32 por 1 millón de tokens de entrada y $64 por 1 millón de tokens de salida. La entrada en caché cuesta $0.40/1M.
Hay dos voces nuevas exclusivas de Realtime: Cedar y Marin.
Los niveles de razonamiento son minimal, low, medium, high y xhigh. El predeterminado es low.
Para WebSocket use: wss://api.openai.com/v1/realtime?model=gpt-realtime-2.
También puede recibir llamadas entrantes por SIP.
Modelos relacionados:
- GPT-Realtime-Translate: traducción en vivo, 70 idiomas de entrada, $0.034/min.
- GPT-Realtime-Whisper: STT en streaming, $0.017/min.
Use Apidog para guardar sesiones WebSocket, reproducir eventos y comparar ejecuciones.

¿Qué es GPT-Realtime-2?

GPT-Realtime-2 es un modelo único de voz a voz. Recibe audio, texto o imágenes como entrada y genera texto o audio como salida.

La diferencia clave es que no necesita una cadena separada de:

STT → LLM → TTS

El modelo procesa la transcripción, el razonamiento, la selección de herramientas y la generación de voz en una sola sesión Realtime.

La nueva modalidad importante es la entrada de imagen. Puede insertar una captura de pantalla o una foto durante una conversación de voz y pedirle al agente que explique lo que ve.

Ejemplo de caso de uso:

Usuario: “Estoy viendo este error en pantalla. ¿Qué significa?”
Agente: analiza la imagen, responde en voz y puede pedir más contexto.

Esto permite construir copilotos de voz que ven lo mismo que el usuario.

Especificaciones

Atributo	Valor
ID del modelo	`gpt-realtime-2`
Ventana de contexto	128,000 tokens
Salida máxima	32,000 tokens
Modalidades de entrada	texto, audio, imagen
Modalidades de salida	texto, audio
Fecha límite de conocimiento	2024-09-30
Niveles de razonamiento	minimal, low, medium, high, xhigh
Llamada a funciones	yes
Servidores MCP remotos	yes
Entrada de imagen	yes
Llamadas telefónicas SIP	yes

¿Qué cambió con respecto a `gpt-realtime`?

Frente a gpt-realtime-1.5, GPT-Realtime-2 mejora en benchmarks de audio:

Big Bench Audio: 81.4% → 96.6%.
Audio MultiChallenge: 34.7% → 48.5%.

Estas puntuaciones se obtuvieron con razonamiento high y xhigh. En producción, el valor predeterminado es low para reducir latencia.

Cambios prácticos para implementar agentes:

Preámbulos de voz

El modelo puede decir frases como “déjame verificar eso” mientras razona o espera resultados de herramientas.
Llamadas de herramientas en paralelo

Puede ejecutar varias funciones al mismo tiempo y narrar el progreso.
Recuperación más robusta

Maneja mejor turnos ambiguos, interrupciones o solicitudes incompletas.
Mejor control del tono

Puede ajustar estilo, formalidad, velocidad y terminología durante la sesión.

El contexto también crece de 32k a 128k tokens, lo que permite sesiones largas para soporte, banca, tutorías o agentes telefónicos.

Precios

GPT-Realtime-2 se factura por token, con tarifas separadas por modalidad.

Tipo de token	Entrada	Entrada en caché	Salida
Texto	$4.00 / 1M	$0.40 / 1M	$24.00 / 1M
Audio	$32.00 / 1M	$0.40 / 1M	$64.00 / 1M
Imagen	$5.00 / 1M	$0.50 / 1M	n/a

La entrada en caché reduce el costo para contexto repetido, como prompts de sistema, documentos base o instrucciones estables. Si su agente reutiliza el mismo contexto en muchas sesiones, active caché siempre que sea posible.

Para comparar con otros modelos, consulte precios de GPT-5.5.

Modelos complementarios:

GPT-Realtime-Translate: $0.034 por minuto. Admite 70 idiomas de entrada y 13 de salida.
GPT-Realtime-Whisper: $0.017 por minuto. Voz a texto en streaming para subtítulos en vivo y transcripción continua.

Use:

GPT-Realtime-2 si necesita razonamiento y generación de voz.
GPT-Realtime-Translate si necesita interpretación multilingüe en vivo.
GPT-Realtime-Whisper si solo necesita transcripción.

Puntos finales y autenticación

GPT-Realtime-2 está disponible en varias superficies de API:

POST https://api.openai.com/v1/chat/completions
POST https://api.openai.com/v1/responses
WSS  wss://api.openai.com/v1/realtime?model=gpt-realtime-2
WSS  wss://api.openai.com/v1/realtime?call_id={call_id}   # SIP
POST https://api.openai.com/v1/realtime/translations
POST https://api.openai.com/v1/realtime/transcription_sessions

Para agentes de voz interactivos, use WebSocket:

wss://api.openai.com/v1/realtime?model=gpt-realtime-2

Autenticación:

Authorization: Bearer $OPENAI_API_KEY
OpenAI-Beta: realtime=v1

Configure la variable de entorno:

export OPENAI_API_KEY="sk-proj-..."

Conexión por WebSocket

Instale ws en Node.js:

npm install ws

Cliente mínimo:

import WebSocket from "ws";

const ws = new WebSocket(
  "wss://api.openai.com/v1/realtime?model=gpt-realtime-2",
  {
    headers: {
      Authorization: `Bearer ${process.env.OPENAI_API_KEY}`,
      "OpenAI-Beta": "realtime=v1",
    },
  }
);

ws.on("open", () => {
  ws.send(JSON.stringify({
    type: "session.update",
    session: {
      voice: "cedar",
      instructions: "You are a friendly support agent for a fintech app.",
      input_audio_format: "pcm16",
      output_audio_format: "pcm16",
      turn_detection: { type: "server_vad" },
      reasoning: { effort: "low" },
    },
  }));
});

ws.on("message", (raw) => {
  const event = JSON.parse(raw.toString());

  if (event.type === "response.audio.delta") {
    // Fragmento de audio PCM16 en base64.
    // En producción, envíelo al speaker, navegador o pipeline de audio.
    process.stdout.write(Buffer.from(event.delta, "base64"));
  }

  if (event.type === "response.done") {
    console.log("Respuesta completada");
  }
});

ws.on("error", console.error);

La sesión funciona por eventos:

Usted envía audio con input_audio_buffer.append.
El servidor responde con eventos como response.audio.delta.
Puede usar server_vad para detección de turnos del lado del servidor.

Formato recomendado:

PCM16 a 24 kHz

También se admiten G.711 mu-law y A-law, útiles para telefonía.

Para comparar Realtime con Responses API, consulte Cómo usar la API de GPT-5.5.

Configurar la sesión

Una configuración inicial práctica:

ws.send(JSON.stringify({
  type: "session.update",
  session: {
    voice: "cedar",
    instructions: `
      Eres un agente de soporte técnico.
      Responde de forma breve.
      Si necesitas datos externos, usa herramientas.
      Si no estás seguro, pide aclaración.
    `,
    input_audio_format: "pcm16",
    output_audio_format: "pcm16",
    turn_detection: {
      type: "server_vad"
    },
    reasoning: {
      effort: "low"
    }
  }
}));

Para cambiar el nivel de razonamiento durante una sesión:

ws.send(JSON.stringify({
  type: "session.update",
  session: {
    reasoning: {
      effort: "medium"
    }
  }
}));

Use low como valor inicial. Suba a medium, high o xhigh solo si mide problemas reales de calidad.

Enviar audio al modelo

El flujo típico es:

1. Capturar audio del micrófono.
2. Convertirlo a PCM16.
3. Codificar cada fragmento en base64.
4. Enviar input_audio_buffer.append.
5. Confirmar el turno con input_audio_buffer.commit si controla los turnos manualmente.
6. Crear respuesta con response.create.

Ejemplo de envío de un fragmento:

function sendAudioChunk(pcm16Buffer) {
  ws.send(JSON.stringify({
    type: "input_audio_buffer.append",
    audio: pcm16Buffer.toString("base64"),
  }));
}

Si no usa VAD del servidor, cierre el turno manualmente:

ws.send(JSON.stringify({
  type: "input_audio_buffer.commit"
}));

ws.send(JSON.stringify({
  type: "response.create"
}));

Voces

GPT-Realtime-2 incluye dos voces nuevas:

Cedar: voz masculina cálida de rango medio. Buena opción predeterminada para agentes generales.
Marin: voz femenina brillante y clara. Útil para traducción y anuncios.

También siguen disponibles:

alloy
ash
ballad
coral
echo
sage
shimmer
verse

Para cambiar la voz durante una sesión:

ws.send(JSON.stringify({
  type: "session.update",
  session: {
    voice: "marin"
  }
}));

Entrada de imagen

Puede adjuntar una imagen en cualquier turno del usuario.

Ejemplo:

ws.send(JSON.stringify({
  type: "conversation.item.create",
  item: {
    type: "message",
    role: "user",
    content: [
      {
        type: "input_image",
        image_url: "https://example.com/screenshot.png"
      },
      {
        type: "input_text",
        text: "What does this error mean?"
      }
    ],
  },
}));

ws.send(JSON.stringify({
  type: "response.create"
}));

Patrones comunes:

QA por voz: un tester muestra una UI con error y el agente dicta el reporte.
Soporte en campo: un técnico envía una foto de un panel o equipo.
Accesibilidad: el agente describe una pantalla durante una llamada.

Para más detalle sobre imágenes, consulte Cómo usar la API de GPT-Image-2.

Llamada a funciones y MCP

GPT-Realtime-2 admite herramientas de función y servidores MCP remotos en la misma sesión.

Llamada a funciones estándar

El flujo es:

1. Declare herramientas en session.update.
2. El modelo emite argumentos de llamada.
3. Su aplicación ejecuta la función.
4. Usted devuelve function_call_output.
5. El modelo continúa la conversación.

Ejemplo de herramienta:

ws.send(JSON.stringify({
  type: "session.update",
  session: {
    tools: [
      {
        type: "function",
        name: "lookup_account",
        description: "Busca información básica de una cuenta de usuario.",
        parameters: {
          type: "object",
          properties: {
            account_id: {
              type: "string"
            }
          },
          required: ["account_id"]
        }
      }
    ]
  }
}));

GPT-Realtime-2 puede ejecutar llamadas en paralelo y narrar el progreso mientras espera resultados.

Servidores MCP remotos

También puede configurar un servidor MCP remoto:

ws.send(JSON.stringify({
  type: "session.update",
  session: {
    tools: [{
      type: "mcp",
      server_url: "https://mcp.example.com/sse",
      allowed_tools: ["lookup_account", "list_transactions"],
    }],
  },
}));

Esto reduce la lógica que debe mantener en su cliente WebSocket, especialmente si su agente usa muchas herramientas.

Para pruebas de MCP, consulte pruebas de servidor MCP en Apidog.

Llamadas telefónicas SIP

GPT-Realtime-2 también puede recibir llamadas telefónicas reales.

Flujo general:

1. Configure su tronco SIP hacia la puerta de enlace SIP de OpenAI.
2. Una llamada entrante crea un call_id.
3. Su aplicación abre una conexión:
   wss://api.openai.com/v1/realtime?call_id={call_id}
4. El modelo procesa audio telefónico y responde en voz.

El modelo acepta G.711 mu-law y A-law directamente, por lo que no necesita transcodificación adicional en muchos sistemas telefónicos.

Esto es especialmente útil para centros de llamadas, donde el agente suele necesitar:

responder en tiempo real,
consultar herramientas,
recuperar datos de cuenta,
transferir o escalar casos,
mantener contexto durante una llamada larga.

Niveles de razonamiento

Los niveles controlan la relación entre latencia y calidad:

Nivel	Caso de uso	Costo de latencia aprox.
`minimal`	Respuestas simples de sí/no	ninguno
`low`	Soporte general y conversaciones diarias	pequeño
`medium`	Desambiguación y herramientas complejas	moderado
`high`	Razonamiento multi-paso o revisión de código por voz	alto
`xhigh`	Preguntas analíticas difíciles y benchmarks	más alto

Recomendación práctica:

Empiece con low.
Mida latencia, calidad y tasa de resolución.
Suba a medium o high solo en flujos donde low falle.

Probar la API de Realtime en Apidog

Las sesiones WebSocket son difíciles de depurar porque tienen estado. Con Apidog puede guardar y reproducir una sesión completa.

Flujo recomendado:

Cree una nueva solicitud WebSocket.
Use la URL:

   wss://api.openai.com/v1/realtime?model=gpt-realtime-2

Configure headers:

   Authorization: Bearer {{OPENAI_API_KEY}}
   OpenAI-Beta: realtime=v1

Guarde un mensaje session.update.
Añada mensajes input_audio_buffer.append y response.create.
Ejecute la sesión y capture los eventos del servidor.
Compare ejecuciones cambiando reasoning.effort, voice o herramientas.

Descargue Apidog, cree una solicitud WebSocket y guarde su token en un entorno. Puede usar variables como:

{{OPENAI_API_KEY}}
{{voice}}
{{reasoning_effort}}

Esto facilita reproducir pruebas sin reescribir JSON en cada ejecución.

Para comparar con otro modelo multimodal rápido, consulte Cómo usar la API de Gemini 3 Flash Preview.

Preguntas frecuentes

¿Qué ID de modelo debo usar?

Use:

gpt-realtime-2

El modelo anterior sigue disponible como:

gpt-realtime

También existe la versión ligera:

gpt-realtime-2-mini

¿Puedo enviar audio mientras el modelo todavía habla?

Sí. La API de Realtime usa VAD del lado del servidor por defecto, por lo que el modelo puede interrumpirse cuando el usuario empieza a hablar.

También puede desactivar VAD y controlar los límites de turno desde el cliente.

¿El contexto de 128k incluye audio?

Sí. El audio se tokeniza. Un segundo de audio equivale aproximadamente a 50 tokens, según el formato.

En llamadas largas, mida el uso real antes de asumir que 128k será suficiente.

¿Se admite fine-tuning?

Todavía no. Según la tarjeta del modelo, GPT-Realtime-2 aún no admite fine-tuning, salidas predichas ni streaming de texto en Chat Completions.

El punto final Realtime transmite audio de forma nativa.

¿Cómo se compara con GPT-5.5 más TTS?

GPT-5.5 con TTS no ofrece razonamiento de voz de extremo a extremo.

Un modelo voz a voz puede reaccionar a tono, vacilación, énfasis e interrupciones. Para agentes que deben responder a cómo habla el usuario, GPT-Realtime-2 es más adecuado.

Para razonamiento textual, consulte Cómo usar la API de GPT-5.5.

¿Qué límites de tasa aplican?

El Nivel 1 empieza en 40,000 tokens por minuto y escala hasta 15M TPM en el Nivel 5.

Los límites son por modelo, por lo que la cuota existente de GPT-5 no se transfiere automáticamente.

Resumen

GPT-Realtime-2 permite construir agentes de voz con contexto largo, razonamiento de clase GPT-5, entrada de imagen, herramientas, MCP y soporte SIP dentro de una sesión WebSocket.

Ruta práctica para empezar:

Cree una conexión WebSocket a gpt-realtime-2.
Configure session.update con voz, instrucciones, formato de audio y reasoning.effort.
Empiece con low.
Añada herramientas solo cuando tenga un flujo claro.
Use Apidog para reproducir sesiones, capturar eventos y comparar cambios.
Suba el razonamiento únicamente cuando mida una brecha de calidad.

Mejores LLMs Locales de 2026

Roobia — Fri, 08 May 2026 06:41:47 +0000

En resumen

El “mejor” LLM local en 2026 depende de tres variables prácticas: VRAM disponible, latencia objetivo y caso de uso principal: codificación, razonamiento, multilingüe, visión o llamadas a herramientas.

Prueba Apidog hoy

Para GPUs de 24 GB, Qwen 3.6 32B y DeepSeek V4 Flash son los dos todoterrenos más potentes.
Para 8 GB o menos, las opciones más razonables son Gemma 4 9B y Llama 5.1 8B.
Para razonamiento o codificación puros, DeepSeek V4 Pro cuantizado o GLM 5 lideran la clasificación abierta.
Usa Ollama, vLLM o LM Studio para exponer un endpoint HTTP compatible con OpenAI.
Después, prueba ese endpoint local con Apidog igual que probarías una API alojada.
Descarga Apidog para simular, reproducir y comparar tráfico de modelos locales sin gastar tokens de tu presupuesto de LLM alojado.

Esta guía resume qué modelos locales vale la pena ejecutar en 2026, qué hardware necesitan y cómo probarlos como APIs HTTP. Si ya estás evaluando DeepSeek, revisa también la guía de instalación local de DeepSeek V4 y la descripción general de DeepSeek V4.

Por qué los LLM locales vuelven a ser importantes en 2026

Hace tres años, ejecutar un LLM local implicaba aceptar una caída clara de calidad. Eso ya no es necesariamente cierto. Los modelos de peso abierto alcanzaron a muchos sistemas alojados de clase GPT-4 durante 2024 y mejoraron de forma importante el costo por token a mediados de 2025.

Hoy, para tareas como extracción, clasificación, llamadas a herramientas y muchas cargas de trabajo de codificación, la diferencia práctica puede ser pequeña. La pregunta ya no es solo “¿el modelo es suficientemente bueno?”, sino:

¿Cabe en mi hardware?
¿Responde con la latencia que necesito?
¿Puedo probarlo y cambiarlo sin romper mi aplicación?

El hardware también cambió. Una GPU de consumo de 24 GB puede ejecutar modelos de 32B parámetros con cuantificación de 4 bits y rendimiento usable. Un Mac Studio con memoria unificada suficiente puede servir modelos más grandes como DeepSeek V4 Flash a velocidades razonables.

Para equipos que se preocupan por residencia de datos, bloqueo de proveedor o costos de inferencia altos, ejecutar modelos locales ya es una opción práctica.

Cómo seleccionamos estos modelos

La lista no es un simple ranking. Los criterios usados fueron:

Pesos abiertos con licencia permisiva o comunitaria usable en producción.
Mantenimiento activo en 2026.
Ruta de servicio compatible con OpenAI mediante Ollama, vLLM o LM Studio.
Buen rendimiento real en al menos una categoría: razonamiento, código, multilingüe, visión, contexto largo o llamadas a herramientas.
Requisitos de hardware razonables para desarrolladores y equipos pequeños.

También se contrastaron los resultados con referencias públicas como LMSYS Chatbot Arena y el Open LLM Leaderboard de Hugging Face, cuando aplicaba.

Los LLM locales que vale la pena ejecutar en 2026

1. DeepSeek V4 Pro

DeepSeek V4 Pro es el modelo insignia de la familia DeepSeek V4. Está disponible como GGUF y AWQ de 4 bits en Hugging Face.

El modelo completo tiene 1.6T parámetros con 49B activos, por lo que entra en territorio de centro de datos. Cuantizado a Q4, puede requerir hardware como dos H100 de 80 GB o un Mac Studio M3 Ultra con 192 GB de memoria unificada.

Para la mayoría de desarrolladores, V4 Pro local será una opción exigente. Aun así, es relevante porque sus variantes y destilaciones más pequeñas heredan parte de su comportamiento de razonamiento.

Si prefieres usar los mismos pesos mediante API alojada, consulta cómo usar la API de DeepSeek V4.

Ideal para: agentes con razonamiento pesado, investigación, workloads avanzados.

Hardware: 192 GB de memoria unificada o 2 GPUs de 80 GB.

Dónde conseguirlo: DeepSeek V4 Pro en Hugging Face.

2. DeepSeek V4 Flash

DeepSeek V4 Flash es la variante más pequeña de V4: 284B parámetros totales y 13B activos. Con cuantificación de 4 bits, cabe en 24 GB de VRAM con espacio para una ventana de contexto de 64K.

En una RTX 4090, el rendimiento promedio observado fue de unos 28 tokens por segundo en generación de formato largo.

V4 Flash es probablemente el modelo que más equipos podrán ejecutar localmente. Su calidad de razonamiento quedó cerca de V4 Pro en los prompts probados, aunque la codificación se queda algo por detrás.

La guía de instalación local de DeepSeek V4 cubre la configuración con Ollama de principio a fin.

Ideal para: agente local general, asistente de codificación, generador RAG.

Hardware: 24 GB VRAM en Q4, 16 GB en Q3 con pérdida de calidad.

Dónde conseguirlo:

ollama pull deepseek-v4-flash

O desde DeepSeek V4 Flash en Hugging Face.

3. Qwen 3.6

Qwen, de Alibaba, ha sido una de las familias de peso abierto más consistentes. Qwen 3.6 en Q4 cabe en 24 GB y supera a modelos Llama 3 70B más antiguos en varios benchmarks de razonamiento y llamadas a herramientas.

Su punto fuerte es el soporte multilingüe. Qwen maneja chino, japonés, coreano y árabe con calidad alta, donde muchos modelos occidentales son menos consistentes.

Si tu producto opera fuera de EE. UU. o necesita un único modelo para razonamiento, herramientas y salida multilingüe, Qwen 3.6 32B es una opción fuerte.

Ideal para: productos multilingües, salida estructurada, llamadas a herramientas, costo equilibrado.

Hardware: 24 GB VRAM en Q4.

Dónde conseguirlo:

ollama pull qwen3.6:32b

O desde Qwen 3.6 en Hugging Face.

4. GLM 5.1

GLM 5.1 destaca especialmente en llamadas a herramientas. Se sitúa entre los modelos abiertos más fuertes para flujos agentic, extracción estructurada y seguimiento de esquemas JSON.

La codificación no es su punto más fuerte. En cambio, razonamiento, clasificación y extracción estructurada son sus mejores áreas.

GLM 5.1 es una buena opción si tu carga de trabajo depende de:

llamadas a herramientas;
workflows de agentes;
extracción de datos;
respuestas en JSON;
validación contra esquemas.

Ideal para: agentes con tool calling, extracción estructurada, pipelines JSON.

Servicio local: Ollama o vLLM.

Cómo servirlos como una API alojada

Una vez que el modelo funciona, tu aplicación sigue necesitando un endpoint HTTP. Lo ideal es que el modelo local tenga la misma forma de API que un proveedor alojado.

En 2026, las rutas más prácticas son:

Opción 1: Ollama

Ollama es la forma más simple para empezar.

ollama serve

Expone un endpoint compatible con OpenAI en:

http://localhost:11434/v1

Esto permite cambiar de:

https://api.openai.com/v1

http://localhost:11434/v1

sin reescribir todo el cliente.

Opción 2: vLLM

vLLM es mejor para producción. Ofrece mejor rendimiento, procesamiento por lotes continuo y un endpoint compatible con OpenAI normalmente expuesto en:

http://localhost:8000/v1

Úsalo cuando importen latencia, concurrencia y throughput.

Opción 3: LM Studio

LM Studio es útil si quieres una GUI. Permite descargar modelos, probarlos localmente y activar un servidor HTTP desde la configuración.

Es una buena opción para desarrollo individual o prototipos rápidos.

Ejemplo: llamar un modelo local con el cliente de OpenAI

Los tres enfoques anteriores pueden usar el formato OpenAI Chat Completions. Eso significa que el mismo cliente puede apuntar a un modelo alojado o local cambiando solo base_url y model.

from openai import OpenAI

client = OpenAI(
    api_key="ollama",  # cualquier string; Ollama lo ignora
    base_url="http://localhost:11434/v1",
)

resp = client.chat.completions.create(
    model="qwen3.6:32b",
    messages=[
        {
            "role": "user",
            "content": "Resume las diferencias entre modelos MoE y dense en tres bullets."
        }
    ],
    temperature=0.3,
)

print(resp.choices[0].message.content)

Para probar otro modelo, cambia solo el nombre:

model="deepseek-v4-flash"

model="llama5.1:8b"

Este patrón también se explica en cómo usar DeepSeek V4 gratis.

Probando modelos locales con Apidog

La diferencia más importante entre un LLM alojado y uno local no es solo la calidad. Es la depuración.

Cuando una API alojada falla, consultas su página de estado. Cuando Ollama, vLLM o tu GPU fallan, el problema es tuyo.

Necesitas poder:

inspeccionar la solicitud cruda;
reproducir el mismo prompt;
cambiar parámetros como temperature o max_tokens;
comparar modelos;
medir latencia;
simular respuestas para CI.

Apidog trata tu endpoint de Ollama o vLLM como cualquier otra API HTTP.

1. Guarda solicitudes canónicas

Crea una colección por modelo con prompts realistas:

{
  "model": "qwen3.6:32b",
  "messages": [
    {
      "role": "user",
      "content": "Extrae los campos principales de este contrato y responde en JSON."
    }
  ],
  "temperature": 0.2,
  "max_tokens": 1024
}

Después de cambiar modelo, cuantización o hardware, reproduce la misma colección y compara resultados.

2. Compara salidas entre modelos

Ejecuta el mismo prompt contra:

Qwen 3.6;
DeepSeek V4 Flash;
Llama 5.1;
Gemma 4;
GLM 5.1.

Esto ayuda a detectar regresiones antes de mover tráfico real.

3. Simula el endpoint en CI

No conviene que tus pipelines de CI dependan de una GPU local de 24 GB. Si el proceso cae por OOM o el driver falla, tus tests se vuelven inestables.

Con Apidog puedes simular el endpoint con respuestas JSON realistas para que las pruebas unitarias sigan siendo deterministas.

4. Mide rendimiento

Para modelos locales, mide al menos:

latencia total;
tiempo hasta el primer token;
tokens por segundo;
variación entre Q4 y Q5;
impacto del tamaño de contexto.

Esto te permite decidir si un modelo más grande realmente compensa.

5. Documenta tu API local

Los proyectos de Apidog pueden exportar OpenAPI 3.1. Así, cualquier compañero puede ver cómo llamar al modelo interno, qué formato acepta y qué respuesta debe esperar.

Este flujo también se cubre en Apidog como alternativa a Postman.

Errores comunes al ejecutar LLM locales

Elegir el modelo más grande que cabe en la GPU

Un modelo de 32B en Q3 puede comportarse peor que uno de 14B en Q5. La calidad de cuantización importa mucho una vez que trabajas en 4 bits o menos.

Olvidar que el contexto consume VRAM

Una ventana de 32K tokens en un modelo de 32B puede requerir varios GB adicionales para la caché KV. Reserva memoria para el contexto antes de cargar el modelo.

Ejecutar fine-tunes desconocidos

No ejecutes cualquier subida aleatoria de Hugging Face en producción. Usa modelos base oficiales o fine-tunes de autores conocidos. Un fine-tune envenenado es un riesgo real.

Saltarse la simulación

Los modelos locales pueden fallar por drivers, OOM, procesos terminados o throttling de GPU. Si tus tests golpean directamente el modelo, CI se vuelve frágil.

Simula el endpoint con Apidog para que las pruebas no dependan del estado del hardware.

Ignorar diferencias en tool calling

Llama 5.1, Qwen 3.6 y DeepSeek V4 pueden soportar llamadas a herramientas, pero no siempre emiten JSON con la misma forma exacta.

Antes de cambiar modelos en producción, prueba:

nombres de herramientas;
argumentos;
schemas;
errores de validación;
streaming;
respuestas parciales.

Casos de uso reales

Una startup que ejecuta un agente de atención al cliente pasó de GPT-5.5 a Qwen 3.6 32B en una única 4090. La latencia se mantuvo por debajo de 800 ms, la factura mensual de inferencia bajó de $9,400 a $0 y el equipo usa simulaciones de Apidog para mantener CI determinista.

Un desarrollador individual que construye un asistente de voz ejecuta Gemma 4 9B en un M2 Pro con 16 GB de memoria unificada. Los borradores de predicción multi-token le dan unos 60 tokens por segundo, suficiente para una experiencia que se siente nativa.

Un equipo de investigación fintech ejecuta DeepSeek V4 Flash en dos 4090 para generar resúmenes nocturnos por lotes de documentos regulatorios. El costo por resumen es la electricidad más el mantenimiento del equipo.

Conclusión

El mejor LLM local en 2026 es el que encaja con tu VRAM, tu latencia objetivo y el estándar de calidad de tu producto.

Como regla práctica:

usa Qwen 3.6 32B o DeepSeek V4 Flash si tienes 24 GB de VRAM;
usa Llama 5.1 8B o Gemma 4 9B para hardware más pequeño;
usa GLM 5.1 si tu carga principal son llamadas a herramientas;
usa DeepSeek V4 Pro si tienes hardware de gama alta y necesitas razonamiento fuerte.

Cinco ideas clave:

La calidad local ya es suficiente para muchas tareas de producción.
Ollama más un cliente compatible con OpenAI es la ruta más rápida.
La cuantización importa tanto como el tamaño del modelo.
Trata el endpoint local como una API de producción.
Apidog ayuda a guardar, reproducir, simular, comparar y documentar esas llamadas.

Siguiente paso:

ollama pull qwen3.6:32b
ollama serve

Después apunta Apidog a:

http://localhost:11434/v1

y empieza a comparar respuestas como si fuera una API alojada.

Preguntas frecuentes

¿Cuál es el mejor LLM local para una GPU de 24 GB en 2026?

Para la mayoría de cargas de trabajo, Qwen 3.6 32B en Q4 o DeepSeek V4 Flash en Q4.

Elige Qwen para tareas multilingües o con muchas herramientas. Elige DeepSeek V4 Flash para razonamiento y codificación. La configuración está cubierta en la guía local de DeepSeek V4.

¿Puedo ejecutar un LLM local en un Mac?

Sí. Un Mac con Apple Silicon y 16 GB o más de memoria unificada puede ejecutar Llama 5.1 8B y Gemma 4 9B cómodamente. Un M3 Ultra con 192 GB puede ejecutar DeepSeek V4 Pro en Q4. Usa Ollama o LM Studio.

¿Cómo pruebo un LLM local igual que OpenAI?

Dirige tu cliente compatible con OpenAI y tu proyecto de Apidog a la URL local.

Ollama:

http://localhost:11434/v1

vLLM:

http://localhost:8000/v1

La forma de solicitud es la misma; cambia la URL base.

¿La calidad local está realmente a la par con la alojada?

En razonamiento, codificación, clasificación, extracción y llamadas a herramientas, los mejores modelos abiertos están cerca de los alojados en muchas tareas. En visión, QA de documentos de contexto largo y escritura creativa, los modelos alojados todavía pueden liderar por margen notable.

¿Cuánto cuesta ejecutar un LLM local?

Una RTX 4090 puede ejecutar DeepSeek V4 Flash por el costo de la electricidad, aproximadamente $30 al mes con uso típico. Un equivalente alojado al mismo volumen puede costar cientos o miles al mes. El punto de equilibrio suele aparecer alrededor de 5 millones de tokens mensuales.

¿Cómo cambio una app de producción entre un modelo alojado y uno local?

Mantén el cliente de OpenAI y cambia:

base_url;
model;
credenciales si aplica.

Antes de enviar tráfico real, reproduce prompts críticos y compara respuestas. Este enfoque también se cubre en pruebas de API sin Postman.

¿Dónde puedo ver clasificaciones actualizadas?

Consulta el Open LLM Leaderboard de Hugging Face y LMSYS Chatbot Arena. Usa ambos, porque miden cosas diferentes.

Forem: Roobia

Guía para Pruebas de Servidor MCP: Manuales y Automatizadas con Apidog

TL;DR

Qué es MCP realmente

Qué debería probar en un servidor MCP

1. Conformidad del protocolo

2. Corrección del esquema

3. Comportamiento de herramientas

4. Acceso a recursos

5. Renderizado de prompts

6. Modos de fallo

Pruebas manuales con stdio

Dos detalles importantes

De manual a automatizado con Apidog

1. Cree un proyecto de Apidog para su servidor MCP

2. Guarde solicitudes canónicas

3. Añada aserciones

4. Simule APIs ascendentes con mocks

5. Ejecute el conjunto en CI

Cómo se ve una buena cobertura

Errores comunes al probar MCP

Saltarse initialize

Afirmar cadenas de error exactas

Dejar que el mock se desvíe de producción

Olvidar streaming

No probar concurrencia

Mezclar errores de protocolo y de herramienta

Casos de uso reales

Conclusión

Preguntas frecuentes

¿Qué es MCP?

¿Puedo probar un servidor MCP sin wrapper HTTP?

¿Cómo simulo APIs ascendentes?

¿Qué pasa con resultados de herramientas en streaming?

¿Debo probar la versión del protocolo?

¿Puedo probar con Claude Desktop real?

¿Dónde puedo ver ejemplos reales de servidores MCP?

Qué es Maigret: Escáner OSINT Que No Se Rompe

En resumen

Qué es y qué no es Maigret

La base de datos de firmas de sitios

Cómo Maigret detecta “usuario encontrado” vs. “usuario no encontrado”

Búsqueda recursiva y extracción de información

Manejo de captcha y límite de tasa

El problema de la deriva de firmas

El modo de resumen opcional con IA

Casos de uso legítimos

1. Recuperación de cuentas propias

2. Monitoreo de abuso de marca

3. Búsqueda de personas desaparecidas

4. Red-team autorizado

5. Periodismo de investigación

Patrones de Maigret aplicables a pruebas de API

1. Firmas como datos, no como código

2. Aserciones multi-señal

3. Firmas sincronizadas

4. Detección de desviaciones

5. LLM como postprocesador

Errores comunes al ejecutar Maigret

Ejecutar sin -a y asumir que el escaneo fue completo

Ignorar etiquetas

No actualizar firmas

Usar Tor sin interpretar bloqueos correctamente

Tratar los hallazgos como prueba final

Casos de uso en el mundo real

Conclusión

Preguntas frecuentes

Cómo Solucionar Error 'Invalid custom3p enterprise config' en Código Claude

En resumen

Qué significa realmente custom3p

Por qué aparece este error ahora

Causa raíz 1: ANTHROPIC_BASE_URL termina en /v1

Incorrecto

Correcto

Verifica el endpoint real

Causa raíz 2: variable de credencial incorrecta

OpenRouter

LiteLLM

Pasarela DeepSeek o vLLM con API key

Causa raíz 3: settings.json malformado

Pruebas manuales con `stdio`

Saltarse `initialize`

Ejecutar sin `-a` y asumir que el escaneo fue completo

Qué significa realmente `custom3p`

Causa raíz 1: `ANTHROPIC_BASE_URL` termina en `/v1`

Causa raíz 3: `settings.json` malformado

Si no puedes reenviar `anthropic-beta`

`config.yaml` de LiteLLM

`~/.claude/settings.json`

Mi `curl` funciona, pero Claude Code falla. ¿Qué cambia?