Vibe Coding Forem: Roobia

Ghostty Deja GitHub: Implicaciones para Creadores de Herramientas de Desarrollo

Roobia — Thu, 30 Apr 2026 03:56:46 +0000

El 28 de abril de 2026, Mitchell Hashimoto anunció que Ghostty, su emulador de terminal de código abierto, dejará GitHub. Hashimoto es el usuario 1299 de GitHub, se unió en febrero de 2008 y usó la plataforma casi todos los días durante más de 18 años. Pero el día del anuncio, una falla de GitHub Actions bloqueó sus revisiones de PR durante dos horas. Su conclusión fue directa: “Este ya no es un lugar para un trabajo serio si te bloquea durante horas al día, todos los días.”

Prueba Apidog hoy

Si desarrollas herramientas para desarrolladores, este anuncio merece una lectura operativa, no solo anecdótica. Hashimoto no es un usuario casual: cofundó HashiCorp sobre GitHub y lanzó Terraform, Vagrant, Vault, Consul y Boundary usando esa plataforma. Cuando un perfil así migra por fiabilidad, el problema no es solo “qué forja usará Ghostty”, sino cómo diseñar tu propia pila para no quedar bloqueado por un proveedor crítico.

Para contexto adicional sobre flujos de trabajo de desarrollo en la era de la IA, consulta cómo escribir archivos AGENTS.md, el uso de GitHub Copilot y la API de facturación para equipos y la descripción del bot de triaje Clawsweeper.

En resumen

Mitchell Hashimoto anunció el 28 de abril de 2026 que Ghostty dejará GitHub por una forja aún sin nombre.
La razón principal fue la fiabilidad: interrupciones recurrentes de GitHub Actions y de la plataforma, documentadas por él en un diario donde “casi todos los días tienen una X”.
El día del anuncio, una interrupción de Actions bloqueó sus revisiones de PR durante dos horas.
El repositorio de Ghostty en GitHub seguirá como espejo de solo lectura.
El desarrollo activo migrará de forma incremental a otra forja.
Sus otros proyectos seguirán en GitHub por ahora.
La lección para equipos de herramientas de desarrollo y APIs: desacopla proveedores, simula dependencias externas y prueba rutas de migración antes de necesitarlas.
Apidog sigue ese patrón para flujos de trabajo de APIs: definición, pruebas, mocks y entornos separados.

Lo que dijo Hashimoto

La publicación del anuncio es breve y clara. No es un manifiesto contra Microsoft ni una promoción de otra forja. Hashimoto explica tres hechos:

Empezó a registrar interrupciones de GitHub.
El registro se llenó más rápido de lo esperado.
Una falla de GitHub Actions bloqueó su trabajo el mismo día en que escribió la publicación.

La interrupción del 27 de abril de 2026 afectó Actions, paquetes y la superficie de la API. Según Hashimoto, el diario ya existía antes de ese incidente, por lo que la decisión no fue una reacción a un solo mal día. La interrupción influyó en el momento del anuncio, no en el motivo de fondo.

También aclaró el alcance:

Ghostty migra.
Sus otros proyectos permanecen en GitHub por ahora.
El repositorio de Ghostty seguirá disponible como espejo de solo lectura.
Issues, PRs y CI se moverán a una nueva forja.
La migración será incremental.

La parte importante: no se fue por características, precios o dirección de producto. Se fue porque la plataforma dejó de ser lo suficientemente fiable para su flujo de trabajo.

Por qué la fiabilidad importa más que la migración

La pregunta útil no es “¿a dónde se va Ghostty?”. La pregunta útil es:

¿Qué pasa cuando una herramienta crítica deja de funcionar durante las horas en que tus usuarios más productivos la necesitan?

Para equipos que construyen herramientas de desarrollo, hay tres señales relevantes.

1. El usuario que se va importa

Hashimoto ha construido herramientas de infraestructura usadas en empresas grandes. Su opinión sobre fiabilidad llega a personas que toman decisiones sobre dónde alojar código, CI, issues y lanzamientos.

2. La razón es difícil de rebatir

No se trata de una discusión ideológica. La queja es operativa:

“No puedo trabajar porque la plataforma no responde.”

Si tus usuarios empiezan a medir interrupciones por su cuenta, tu página de estado ya perdió autoridad.

3. El tono es de post-mortem

La publicación no es agresiva. Parece escrita por alguien que intentó quedarse y concluyó que el coste operativo ya no compensaba.

Para un producto de desarrollo, ese es el peor escenario: un usuario experto que se va sin drama, con datos y sin necesidad de exagerar.

Cómo evaluar si tu herramienta está en la misma trayectoria

Si tu producto está en la ruta crítica de otros desarrolladores, ejecuta esta revisión.

Paso 1: calcula horas perdidas por cliente

No mires solo disponibilidad global. Cruza incidentes con horas reales de uso.

Ejemplo de tabla mínima:

Incidente	Duración	Componente	Clientes afectados	Horas de trabajo bloqueadas
CI degradado	2 h	Builds	12	24 h
API lenta	45 min	API pública	8	6 h
Login caído	30 min	Auth	20	10 h

Si tus usuarios intensivos pierden tiempo todas las semanas, tienes un problema aunque tu SLA agregado se vea bien.

Paso 2: mide tendencia, no solo uptime

Un 99.9% estable puede ser aceptable. Un 99.95% que empeora mes a mes puede ser una alerta.

Mide por componente:

componente: ci
slo: 99.9%
presupuesto_error_mensual: 43.2 min
incidentes_mes_actual: 68 min
estado: excedido
tendencia: peor que mes anterior

Si no tienes presupuesto de error por componente, no sabes si tu fiabilidad mejora o empeora.

Paso 3: publica degradaciones parciales

Una página de estado útil no debe limitarse a “operativo” o “caído”.

Publica estados como:

Builds con retraso.
API con latencia elevada.
Webhooks en cola.
Región degradada.
Autenticación intermitente.

Los usuarios empiezan diarios privados cuando la señal pública no coincide con su experiencia.

Paso 4: mide disponibilidad contra la curva de uso del cliente

Dos horas de caída a las 03:00 pueden ser irrelevantes para algunos equipos. Dos horas durante revisión de PR, despliegue o release pueden bloquear todo el flujo.

Mide fiabilidad así:

disponibilidad_global = tiempo_ok / tiempo_total

disponibilidad_ponderada =
  tiempo_ok_durante_uso_real / tiempo_total_durante_uso_real

Para herramientas de desarrollo, la segunda métrica suele ser más honesta.

El coste real del “siempre GitHub”

Hashimoto escribió que para él “nunca fue una pregunta” dónde poner sus proyectos: siempre GitHub.

Ese hábito tiene coste.

Git es portable, pero el flujo de trabajo completo no lo es. Puedes clonar un repositorio, pero no migras con un solo comando:

Issues.
PRs.
Reviews.
Comentarios.
Discusiones.
Secrets.
Workflows de GitHub Actions.
Packages.
Releases.
CODEOWNERS.
Permisos.
OAuth apps.
Integraciones del Marketplace.

El lock-in no está solo en el código. Está en todo lo que rodea al código.

Patrón práctico: trata GitHub como proveedor, no como infraestructura única

Si tu herramienta depende de GitHub, pon una capa de abstracción desde el inicio.

Ejemplo simple en TypeScript:

interface ForgeClient {
  getPullRequest(repo: string, id: number): Promise<PullRequest>;
  listIssues(repo: string): Promise<Issue[]>;
  createComment(repo: string, issueId: number, body: string): Promise<void>;
}

class GitHubClient implements ForgeClient {
  async getPullRequest(repo: string, id: number) {
    // llamada a GitHub API
  }

  async listIssues(repo: string) {
    // llamada a GitHub API
  }

  async createComment(repo: string, issueId: number, body: string) {
    // llamada a GitHub API
  }
}

class ForgejoClient implements ForgeClient {
  async getPullRequest(repo: string, id: number) {
    // llamada a Forgejo API
  }

  async listIssues(repo: string) {
    // llamada a Forgejo API
  }

  async createComment(repo: string, issueId: number, body: string) {
    // llamada a Forgejo API
  }
}

Luego selecciona el proveedor por configuración:

function createForgeClient(provider: string): ForgeClient {
  switch (provider) {
    case "github":
      return new GitHubClient();
    case "forgejo":
      return new ForgejoClient();
    default:
      throw new Error(`Proveedor no soportado: ${provider}`);
  }
}

El objetivo no es soportar todas las forjas desde el día uno. El objetivo es no acoplar todo tu producto a una API específica.

Alternativas de forja mencionadas en el debate

Hashimoto no anunció destino. Las alternativas creíbles a finales de abril de 2026 incluyen:

Forgejo: hard fork de Gitea, FOSS, mantenido por Codeberg e.V. La federación vía ActivityPub está en la hoja de ruta y parcialmente implementada.
Codeberg: instancia gestionada de Forgejo, sin fines de lucro y gratuita para proyectos de código abierto.
GitLab: CI/CD fuerte, amplia paridad funcional con GitHub y respaldo comercial.
Sourcehut: flujo basado en correo, minimalista y rápido.
Forgejo o Gitea autoalojado: máximo control, mayor carga operativa.
Radicle: enfoque peer-to-peer sin host central, aún temprano para muchos proyectos públicos.

La señal importante es que ninguna opción reemplaza todo GitHub de forma perfecta. Esa es precisamente la consecuencia de concentrar repositorios, CI, issues, paquetes, identidad y releases en una sola plataforma.

Lección para equipos de API

Si trabajas con APIs, cambia los nombres:

“GitHub Actions” → “API ascendente de la que depende tu producto”.
“Issues y PRs” → “canales donde tus clientes reportan problemas”.
“Forja” → “proveedor externo crítico”.

La pregunta es la misma:

¿Qué puede seguir haciendo tu equipo cuando un servicio que no controlas falla durante cuatro horas?

Tres patrones ayudan.

1. Simula todo proveedor crítico

Tus tests y tu desarrollo local no deberían depender siempre de una llamada real a red.

Flujo recomendado:

Define el contrato de la API.
Genera un mock server.
Ejecuta tests contra el mock en local.
Ejecuta tests de contrato contra el proveedor real en CI.
Cambia de entorno sin modificar código.

Ejemplo de configuración:

API_ENV=mock
API_BASE_URL=http://localhost:4010
API_KEY=test

Para staging:

API_ENV=staging
API_BASE_URL=https://sandbox.provider.com
API_KEY=${STAGING_API_KEY}

Para producción:

API_ENV=prod
API_BASE_URL=https://api.provider.com
API_KEY=${PROD_API_KEY}

Apidog permite definir APIs, generar mocks y reutilizar esas definiciones para pruebas. Para un ejemplo de ecosistema multiproveedor, consulta cómo usar la API GPT-5.5.

2. Prueba contra múltiples proveedores

Si tu producto depende de modelos o APIs con formas similares, evita diseñar solo para uno.

Ejemplo conceptual:

interface ChatProvider {
  complete(input: ChatRequest): Promise<ChatResponse>;
}

class OpenAIProvider implements ChatProvider {
  async complete(input: ChatRequest) {
    // llamada a OpenAI
  }
}

class AnthropicProvider implements ChatProvider {
  async complete(input: ChatRequest) {
    // llamada a Anthropic
  }
}

class FallbackChatProvider implements ChatProvider {
  constructor(
    private primary: ChatProvider,
    private fallback: ChatProvider
  ) {}

  async complete(input: ChatRequest) {
    try {
      return await this.primary.complete(input);
    } catch (error) {
      return await this.fallback.complete(input);
    }
  }
}

El fallback no debe improvisarse durante un incidente. Debe estar probado antes.

3. Desacopla el pipeline de release

Si tu release depende 100% de GitHub Actions, una caída de Actions bloquea tu entrega.

Opciones prácticas:

Replica el pipeline crítico en otro runner.
Mantén un flujo manual documentado.
Autoaloja jobs críticos.
Publica artefactos en más de un destino.
Prueba el flujo alternativo cada trimestre.

Ejemplo de checklist para release manual:

[ ] Ejecutar tests localmente
[ ] Construir artefactos
[ ] Firmar release
[ ] Publicar paquete
[ ] Crear tag
[ ] Actualizar changelog
[ ] Notificar canal interno

Si este procedimiento no existe, tu plan real durante una caída es esperar.

Flujo de trabajo resiliente con Apidog

Un flujo práctico para equipos de API:

Descarga Apidog.
Crea un proyecto por cada API ascendente crítica.
Define esquemas de request y response una sola vez.
Genera mocks desde esos esquemas.
Crea entornos separados: dev, mock, staging, prod.
Guarda credenciales como secretos por entorno.
Escribe pruebas de contrato.
Ejecuta las mismas pruebas contra mock, sandbox y proveedor real.
Documenta cómo cambiar de proveedor o entorno durante una degradación.

Ejemplo de estructura de entornos:

dev
  base_url = http://localhost:4010
  auth = none

staging
  base_url = https://sandbox.api.example.com
  auth = staging_secret

prod
  base_url = https://api.example.com
  auth = prod_secret

El punto no es eliminar dependencias externas. El punto es que tu equipo pueda seguir desarrollando, probando y entregando aunque una dependencia falle.

Qué están leyendo los desarrolladores del anuncio

Las reacciones se agrupan así:

“Bien por él”: usuarios avanzados que ya estaban frustrados con interrupciones y ven el anuncio como validación.
“Es solo una interrupción”: desarrolladores que comparan uptime agregado y recuerdan que toda plataforma grande tiene incidentes.
“Migrar es difícil”: equipos que entienden que mover issues, PRs y CI cuesta más que clonar un repositorio.
“¿Qué pasa con mis repos?”: mantenedores pequeños que evalúan si el riesgo aplica a su escala.

La conversación importante ocurre dentro de equipos de ingeniería:

¿Tenemos espejo de repositorios?
¿Podemos lanzar si GitHub Actions cae?
¿Tenemos backup de issues?
¿Qué integraciones dependen exclusivamente de GitHub?
¿Cuál es nuestro plan de salida?

Checklist para reducir dependencia de una sola plataforma

Usa esta lista como punto de partida.

Repositorios

[ ] Crear espejo en una segunda forja.
[ ] Automatizar sincronización semanal o diaria.
[ ] Verificar que los tags también se sincronicen.
[ ] Documentar cómo cambiar el remoto principal.

Ejemplo:

git remote add backup git@codeberg.org:org/repo.git
git push backup main --tags

CI/CD

[ ] Identificar jobs críticos.
[ ] Separar build, test y publish.
[ ] Replicar jobs críticos fuera de GitHub Actions.
[ ] Documentar release manual.
[ ] Probar el flujo alternativo.

APIs externas

[ ] Listar proveedores en ruta crítica.
[ ] Definir mocks para cada API.
[ ] Añadir timeouts explícitos.
[ ] Añadir retries con backoff.
[ ] Añadir fallback cuando tenga sentido.

Ejemplo de timeout:

const controller = new AbortController();

const timeout = setTimeout(() => {
  controller.abort();
}, 5000);

try {
  const response = await fetch(url, {
    signal: controller.signal,
  });

  return await response.json();
} finally {
  clearTimeout(timeout);
}

Observabilidad

[ ] Medir errores por componente.
[ ] Medir latencia por proveedor.
[ ] Separar incidentes internos de incidentes de terceros.
[ ] Publicar degradaciones parciales.
[ ] Revisar tendencia mensual.

Producto

[ ] Mostrar mensajes claros cuando un proveedor externo falla.
[ ] Permitir modo degradado.
[ ] Evitar que una falla externa bloquee todo el flujo.
[ ] Cachear datos no críticos.
[ ] Diseñar integraciones como adaptadores reemplazables.

Para un ejemplo aplicado a herramientas de API y proveedores de IA, consulta la construcción de flujos de trabajo duraderos que sobreviven a las interrupciones del proveedor.

Preguntas frecuentes

¿A dónde se muda Ghostty?

Hashimoto no anunció destino. Dijo que está conversando con múltiples proveedores, comerciales y FOSS, y que la migración será incremental. El repositorio actual en GitHub seguirá como espejo de solo lectura.

¿GitHub es tan poco fiable?

GitHub mantiene números de disponibilidad competitivos frente a plataformas similares. El punto de Hashimoto no es solo el uptime agregado, sino el patrón de interrupciones parciales que bloquean trabajo real durante horas.

¿Debería sacar mis repositorios de GitHub ahora?

No necesariamente. Pero duplicarlos en una segunda forja es una medida barata y útil. Para muchos equipos, el primer paso no es migrar por completo, sino tener una copia funcional y un plan probado.

¿Esto afecta GitHub Copilot o GitHub Actions?

La publicación no se centra en Copilot. El detonante inmediato fue una interrupción de GitHub Actions. Si tu equipo usa Copilot y necesita entender cambios de facturación, revisa el uso de GitHub Copilot y la API de facturación para equipos.

¿Qué significa esto para herramientas de IA que dependen de GitHub?

Bots de revisión, triage de issues, servidores MCP e integraciones similares heredan parte de la fiabilidad de GitHub. Mitigaciones básicas:

Cachear respuestas.
Fallar en abierto cuando sea posible.
Simular GitHub en tests.
Separar lógica de negocio del cliente de GitHub.
Preparar adaptadores para otras forjas.

La descripción del bot de triaje Clawsweeper muestra un ejemplo de este tipo de integración.

¿Es una tendencia de “abandonar GitHub”?

Probablemente será lenta. Migrar un proyecto no trivial fuera de GitHub implica mover mucho más que código. Pero el anuncio cambia la conversación: si un usuario histórico decide que el coste de migrar es menor que el coste de seguir bloqueado, otros equipos empezarán a hacer el mismo cálculo.

¿Qué significa “creador de herramientas para desarrolladores”?

Cualquier persona que construye software usado por otros desarrolladores para entregar software. Incluye:

Terminales.
Editores.
CI/CD.
Clientes de API.
Herramientas de monitoreo.
Registros de paquetes.
Bots de revisión.
Asistentes de IA.
Plataformas de documentación.

Si tu herramienta está en la ruta crítica de un desarrollador, la fiabilidad no es una característica más. Es el producto.

¿Cómo Usar la API de Mistral Medium 3.5?

Roobia — Thu, 30 Apr 2026 03:48:21 +0000

Mistral lanzó Medium 3.5 el 29 de abril de 2026. El ID del modelo API es mistral-medium-3.5, el endpoint es https://api.mistral.ai/v1/chat/completions, y la estructura de la solicitud es suficientemente compatible con el estándar de OpenAI como para migrar cambiando la URL base y el nombre del modelo. Sus datos principales: ventana de contexto de 256K, visión nativa, llamada a funciones, soporte para 24 idiomas y 77.6% en SWE-Bench Verified. Para equipos que construyen agentes, revisores de código o flujos multimodales, Medium 3.5 entra en la misma categoría práctica que GPT-5.5 y DeepSeek V4.

Prueba Apidog hoy

Esta guía muestra cómo autenticarte, configurar parámetros, llamar a la API desde Python y Node, usar visión, herramientas, JSON estructurado, streaming, manejo de errores y un flujo de trabajo con Apidog para iterar prompts sin perder visibilidad de costos. Para modelos comparables, revisa cómo usar la API de DeepSeek V4 y cómo usar la API de GPT-5.5.

En resumen

Endpoint: POST https://api.mistral.ai/v1/chat/completions.
Autenticación: bearer token en el encabezado Authorization.
Modelo: mistral-medium-3.5.
Contexto: 256K tokens.
Precios: $1.5 por millón de tokens de entrada y $7.5 por millón de tokens de salida.
Capacidades: razonamiento, visión, llamada nativa a funciones, salida JSON estructurada y cobertura de 24 idiomas.
Pesos abiertos: mistralai/Mistral-Medium-3.5-128B en Hugging Face bajo una Licencia MIT Modificada con una excepción para grandes ingresos.
Benchmarks destacados: 77.6% en SWE-Bench Verified y 91.4 en τ³-Telecom.
Puedes descargar Apidog para comparar Medium 3.5 contra tu modelo actual, guardar la clave como variable secreta y calcular el costo por llamada.

¿Qué cambió en Medium 3.5?

Medium 3 se lanzó como un modelo solo de texto con contexto de 128K. Medium 3.5 cambia el perfil: es el primer modelo insignia fusionado de Mistral. Seguimiento de instrucciones, razonamiento y codificación viven en un único conjunto de pesos, por lo que no tienes que elegir entre un checkpoint de chat y uno de razonamiento.

Los cambios que más afectan a implementación:

Contexto duplicado: de 128K a 256K.
Visión nativa.
Llamada a funciones integrada en el modelo.
Mejor rendimiento en tareas de código: 77.6% en SWE-Bench Verified.
Mejor rendimiento en flujos agénticos: 91.4 en τ³-Telecom.

El cambio de precio también importa. Medium 3 costaba $0.40 por millón de tokens de entrada y $2.00 por millón de salida. Medium 3.5 sube a $1.5 de entrada y $7.5 de salida. Úsalo como nivel de mayor precisión para tareas donde el razonamiento, el código, la visión o el contexto largo justifiquen el costo.

Requisitos previos

Antes de hacer la primera llamada, prepara:

Una cuenta en console.mistral.ai con método de pago. Sin saldo, la API puede devolver 402 Payment Required.
Una clave API asociada al proyecto que recibirá la facturación.
Un SDK:
- mistralai para Python o JavaScript.
- SDK de OpenAI si quieres reutilizar código compatible cambiando base_url.
Un cliente API. curl sirve para probar, pero para iterar prompts, guardar entornos y revisar costos por respuesta, usa Apidog.

Exporta la clave:

export MISTRAL_API_KEY="..."

Endpoint y autenticación

El endpoint de chat completions es:

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

La autenticación usa un bearer token:

curl https://api.mistral.ai/v1/chat/completions \
  -H "Authorization: Bearer $MISTRAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "mistral-medium-3.5",
    "messages": [
      {
        "role": "user",
        "content": "Explain dense merged checkpoints in two sentences."
      }
    ]
  }'

Una respuesta correcta incluye:

choices: respuestas generadas.
usage.prompt_tokens: tokens de entrada.
usage.completion_tokens: tokens de salida.
usage.total_tokens: total facturable.
id: identificador útil para trazabilidad.

Los errores vienen en un objeto error con code y message.

Parámetros principales

Parámetro	Tipo	Valores	Uso
`model`	string	`mistral-medium-3.5`	Requerido.
`messages`	array	roles y contenido	Requerido. Compatible con el esquema estilo OpenAI.
`temperature`	float	`0` a `1.5`	Usa `0.3` para código y `0.7` para uso general.
`top_p`	float	`0` a `1`	Muestreo nucleus. Por defecto `1.0`.
`max_tokens`	int	hasta el límite de contexto	Limita la salida. Clave para controlar costos.
`stream`	bool	`true` / `false`	Activa streaming SSE.
`tools`	array	especificación de funciones	Define herramientas invocables.
`tool_choice`	string u objeto	`auto`, `any`, `none` o herramienta específica	En Mistral, `any` fuerza una llamada a herramienta.
`response_format`	object	JSON object o JSON schema	Controla salida estructurada.
`random_seed`	int	entero	Reproducibilidad.
`safe_prompt`	bool	`true` / `false`	Añade el preámbulo de seguridad de Mistral.
`presence_penalty`	float	`-2` a `2`	Penaliza repetición de temas.
`frequency_penalty`	float	`-2` a `2`	Penaliza repetición de tokens.

Dos diferencias al migrar desde OpenAI:

OpenAI:  tool_choice="required"
Mistral: tool_choice="any"

OpenAI:  seed
Mistral: random_seed

Cliente Python

Instala el SDK oficial:

pip install mistralai

Ejemplo básico:

import os
from mistralai import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])

response = client.chat.complete(
    model="mistral-medium-3.5",
    messages=[
        {"role": "system", "content": "Reply in code only."},
        {"role": "user", "content": "Write a Rust function that debounces events."},
    ],
    temperature=0.3,
    max_tokens=2048,
)

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

prompt_cost = response.usage.prompt_tokens * 1.5 / 1_000_000
completion_cost = response.usage.completion_tokens * 7.5 / 1_000_000

print("Total tokens:", response.usage.total_tokens)
print("Estimated cost USD:", prompt_cost + completion_cost)

Si ya usas el SDK de OpenAI, cambia la URL base:

import os
from openai import OpenAI

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

response = client.chat.completions.create(
    model="mistral-medium-3.5",
    messages=[
        {"role": "user", "content": "Hello, Mistral."}
    ],
)

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

Usa el SDK nativo si quieres aprovechar características específicas de Mistral de forma más directa. Usa el SDK de OpenAI si tu código ya es agnóstico del proveedor.

Cliente Node.js

Instala el SDK nativo:

npm install @mistralai/mistralai

Ejemplo:

import { Mistral } from "@mistralai/mistralai";

const client = new Mistral({
  apiKey: process.env.MISTRAL_API_KEY,
});

const response = await client.chat.complete({
  model: "mistral-medium-3.5",
  messages: [
    {
      role: "user",
      content: "Explain dense merged checkpoints in plain English.",
    },
  ],
  temperature: 0.7,
});

console.log(response.choices[0].message.content);
console.log("Usage:", response.usage);

Con el SDK de OpenAI:

import OpenAI from "openai";

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

const response = await client.chat.completions.create({
  model: "mistral-medium-3.5",
  messages: [
    { role: "user", content: "Hello, Mistral." },
  ],
});

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

Streaming

Activa stream: true para recibir fragmentos SSE.

import os
from mistralai import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])

stream = client.chat.stream(
    model="mistral-medium-3.5",
    messages=[
        {
            "role": "user",
            "content": "Stream a 300-word essay on merged checkpoints.",
        }
    ],
)

for chunk in stream:
    delta = chunk.data.choices[0].delta.content or ""
    print(delta, end="", flush=True)

El contenido llega en choices[].delta.content, con una forma compatible con el patrón de streaming de OpenAI.

Para comparar latencia, tokens y costo por ejecución, puedes usar el visor de respuestas de Apidog.

Llamada a herramientas

Medium 3.5 soporta llamada nativa a funciones mediante tools.

tools = [
    {
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "Return the current weather for a city.",
            "parameters": {
                "type": "object",
                "properties": {
                    "city": {"type": "string"},
                    "unit": {
                        "type": "string",
                        "enum": ["c", "f"],
                    },
                },
                "required": ["city"],
            },
        },
    }
]

response = client.chat.complete(
    model="mistral-medium-3.5",
    messages=[
        {
            "role": "user",
            "content": "Weather in Lagos in Celsius?",
        }
    ],
    tools=tools,
    tool_choice="auto",
)

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

print(tool_call.function.name)
print(tool_call.function.arguments)

Flujo recomendado:

Envía el prompt con tools.
Lee message.tool_calls.
Ejecuta la función en tu backend.
Añade el resultado como mensaje role: "tool".
Llama de nuevo a la API para que el modelo continúe con contexto del resultado.

El patrón es equivalente al bucle de herramientas de OpenAI, con la diferencia de tool_choice="any" si quieres forzar una llamada.

Modo JSON y salida estructurada

Para respuestas validadas por esquema, pasa response_format.

schema = {
    "type": "json_schema",
    "json_schema": {
        "name": "release_note",
        "schema": {
            "type": "object",
            "properties": {
                "title": {"type": "string"},
                "date": {"type": "string"},
                "bullets": {
                    "type": "array",
                    "items": {"type": "string"},
                },
            },
            "required": ["title", "date", "bullets"],
            "additionalProperties": False,
        },
        "strict": True,
    },
}

response = client.chat.complete(
    model="mistral-medium-3.5",
    messages=[
        {
            "role": "system",
            "content": "Reply with a single JSON object matching the schema.",
        },
        {
            "role": "user",
            "content": "Summarize today's Mistral Medium 3.5 release.",
        },
    ],
    response_format=schema,
)

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

Para casos más simples, usa:

response_format = {"type": "json_object"}

Luego valida con Pydantic, Zod o tu validador preferido en el cliente.

Entrada de visión

Medium 3.5 acepta imágenes junto con texto dentro de messages.

response = client.chat.complete(
    model="mistral-medium-3.5",
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "What is in this image and what is it doing wrong?",
                },
                {
                    "type": "image_url",
                    "image_url": "https://example.com/diagram.png",
                },
            ],
        }
    ],
)

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

Las imágenes se facturan como tokens de entrada a $1.5 por millón. El conteo exacto depende de la resolución y aparece en usage.prompt_tokens.

Para cargas multimodales de alto volumen:

Recorta la región relevante antes de enviar.
Reduce resolución cuando sea posible.
Registra prompt_tokens por imagen.
Evita enviar frames redundantes en video o capturas secuenciales.

Crea una colección en Apidog

Para evitar prompts dispersos en terminal y tener costos visibles, crea una colección reutilizable:

Descarga Apidog y crea un proyecto.
Crea un entorno con:
- BASE_URL=https://api.mistral.ai/v1
- MISTRAL_API_KEY=...
Guarda MISTRAL_API_KEY como variable secreta.
Crea una solicitud:

   POST {{BASE_URL}}/chat/completions

Añade encabezados:

   Authorization: Bearer {{MISTRAL_API_KEY}}
   Content-Type: application/json

Usa un body parametrizable:

{
  "model": "mistral-medium-3.5",
  "temperature": 0.3,
  "max_tokens": 2048,
  "messages": [
    {
      "role": "user",
      "content": "Review this function and suggest improvements."
    }
  ]
}

Revisa usage en cada respuesta.
Añade un cálculo de costo:

const usage = response.json().usage;

const cost =
  usage.prompt_tokens * 1.5 / 1_000_000 +
  usage.completion_tokens * 7.5 / 1_000_000;

console.log(`Estimated cost USD: ${cost}`);

Si ya tienes una colección para DeepSeek V4, duplícala y cambia:

- https://api.deepseek.com/v1
- deepseek-v4-pro
+ https://api.mistral.ai/v1
+ mistral-medium-3.5

El mismo patrón sirve para comparar con GPT-5.5.

Manejo de errores

Errores frecuentes:

Código	Significado	Acción
`400`	Solicitud incorrecta	Valida `messages`, `tools` y el JSON enviado.
`401`	Clave inválida	Regenera la clave en console.mistral.ai.
`402`	Pago requerido	Añade saldo o método de pago.
`403`	Modelo no permitido	Revisa permisos del proyecto y el ID del modelo.
`422`	Parámetro fuera de rango	Revisa `max_tokens`, `tool_choice` o esquema JSON.
`429`	Rate limit	Reintenta con retroceso exponencial.
`500`	Error del servidor	Reintenta una vez y registra el fallo.
`503`	Sobrecarga	Espera o usa otro nivel temporalmente.

Implementa reintentos solo para 429 y 5xx:

import time
from mistralai import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])

def complete_with_retry(payload, retries=3):
    for attempt in range(retries):
        try:
            return client.chat.complete(**payload)
        except Exception as exc:
            status = getattr(exc, "status_code", None)

            if status not in [429, 500, 502, 503, 504]:
                raise

            if attempt == retries - 1:
                raise

            sleep_seconds = 2 ** attempt
            time.sleep(sleep_seconds)

No reintentes automáticamente errores 4xx que no sean 429: normalmente indican un problema de payload, permisos o facturación.

Control de costos

Medium 3.5 es más caro que Medium 3, así que evita enviarlo todo al modelo más potente por defecto.

Patrones prácticos:

Usa Medium 3 por defecto y escala a Medium 3.5 cuando haga falta.

Por ejemplo, usa Medium 3 para clasificación o borradores y Medium 3.5 cuando falle un validador o se requiera razonamiento más fuerte.
Limita max_tokens.

La salida cuesta $7.5 por millón. Si esperas respuestas cortas, no dejes el máximo abierto.
Reduce prompts de sistema largos.

Un preámbulo de 2K tokens se factura en cada llamada. Si puedes bajarlo a 500 tokens, reduces ese costo de entrada en 75%.
Registra usage siempre.

Envía prompt_tokens, completion_tokens, total_tokens y costo estimado a tu observabilidad.
Usa visión selectivamente.

Recorta o comprime imágenes antes de enviarlas. No mandes pantallas completas si solo necesitas una tabla o un diagrama.

Ejemplo de cálculo:

def estimate_cost_usd(prompt_tokens, completion_tokens):
    return (
        prompt_tokens * 1.5 / 1_000_000 +
        completion_tokens * 7.5 / 1_000_000
    )

Comparación con otros modelos de Mistral

Modelo	Contexto	Entrada $/M	Salida $/M	Visión	Mejor para
`mistral-small`	32K	$0.10	$0.30	No	Clasificación de alto volumen, chat ligero
`mistral-medium-3`	128K	$0.40	$2.00	No	Rendimiento masivo, chat largo
`mistral-medium-3.5`	256K	$1.5	$7.5	Sí	Razonamiento, código, visión, agentes
`mistral-large`	128K	$2.00	$6.00	Limitada	Razonamiento de texto de nivel frontera

Medium 3.5 es el nivel que combina contexto largo, visión y razonamiento fusionado. No lo elijas solo por nombre: úsalo cuando esas capacidades sean necesarias para la tarea.

Migración desde otro proveedor

La migración suele ser un cambio de URL base y modelo.

Desde OpenAI:

- base_url="https://api.openai.com/v1"
- model="gpt-5.5"
+ base_url="https://api.mistral.ai/v1"
+ model="mistral-medium-3.5"

Desde DeepSeek:

- base_url="https://api.deepseek.com/v1"
- model="deepseek-v4-pro"
+ base_url="https://api.mistral.ai/v1"
+ model="mistral-medium-3.5"

Ajustes a revisar:

- tool_choice="required"
+ tool_choice="any"

- seed=123
+ random_seed=123

Antes de mover tráfico de producción:

Ejecuta tu suite de pruebas actual.
Compara respuestas para prompts críticos.
Registra usage y costo por llamada.
Si es posible, ejecuta modo sombra durante un día y compara resultados en Apidog.

Casos de uso prácticos

Medium 3.5 encaja especialmente bien en:

Revisión de código a nivel PR.

El contexto de 256K permite incluir diffs grandes y archivos relacionados.
QA sobre documentos largos.

Contratos, RFPs y políticas pueden procesarse en una sola llamada cuando caben en la ventana.
Extracción multimodal.

Puedes extraer campos estructurados desde recibos, capturas o diagramas sin encadenar OCR y otro modelo de texto.
Agentes con herramientas.

La llamada nativa a funciones reduce fricción en flujos donde el modelo debe decidir entre responder, pedir información o invocar una herramienta.

Preguntas frecuentes

¿Cuál es el ID del modelo?

Para la API alojada:

mistral-medium-3.5

En Hugging Face:

mistralai/Mistral-Medium-3.5-128B

Si sirves los pesos abiertos con vLLM o Unsloth, usa el ID del checkpoint de Hugging Face.

¿Medium 3.5 es compatible con OpenAI?

Es compatible en la forma general del endpoint, encabezados y muchos parámetros. Los SDKs de OpenAI para Python y Node funcionan cambiando base_url.

Diferencias clave:

tool_choice="any" en lugar de tool_choice="required".
random_seed en lugar de seed.

¿Puedo ejecutar Medium 3.5 localmente?

Sí. Los pesos están abiertos bajo una Licencia MIT Modificada con una excepción para grandes ingresos. El modelo tiene 128B parámetros, por lo que requiere memoria GPU significativa. Las builds GGUF cuantificadas de unsloth/Mistral-Medium-3.5-128B-GGUF pueden ejecutarse en una tarjeta de consumo de gama alta.

Los patrones de cómo ejecutar DeepSeek V4 localmente se aplican de forma similar.

¿Soporta streaming con herramientas?

Sí. El streaming puede devolver fragmentos incrementales de llamadas a herramientas en delta.tool_calls. Debes acumular esos fragmentos hasta formar el JSON completo antes de ejecutar la función.

¿Cómo cuento tokens antes de enviar?

Usa el tokenizador del paquete Python mistral-common. Es el mismo tokenizador que usa la API, por lo que los conteos deberían alinearse con usage.prompt_tokens.

¿Qué longitud de contexto debería usar en producción?

256K es el límite, no el objetivo. Una llamada de 200K tokens cuesta $0.30 solo en entrada antes de generar salida. Para producción, intenta mantener la mayoría de las llamadas por debajo de 32K y usa contexto largo solo cuando la tarea lo requiera.

¿Hay un nivel gratuito?

Mistral no anuncia un nivel gratuito permanente, aunque las cuentas nuevas pueden incluir crédito de prueba. Para experimentar con modelos comparables sin costo sostenido, revisa cómo usar la API de DeepSeek V4 de forma gratuita.

Plataforma API para Flujo de Trabajo API Design-First

Roobia — Thu, 30 Apr 2026 03:30:45 +0000

En resumen

El enfoque de diseño-primero consiste en escribir la especificación de tu API antes del código de implementación. Esa especificación se convierte en la fuente de verdad para mocks, documentación, pruebas y stubs de cliente. Si eliges una plataforma que conecte todo el flujo, reduces la fricción de mantener código, contrato y documentación sincronizados. En este artículo verás cómo aplicar diseño-primero en la práctica y cómo encaja Apidog como plataforma completa para este flujo.

Prueba Apidog hoy

Apidog

Prueba Apidog gratis

Introducción

La mayoría de los desarrolladores empiezan creando APIs con un enfoque de código-primero:

Escribes una ruta.
Añades anotaciones o decoradores.
Ejecutas un generador.
Obtienes documentación.

Funciona bien al principio. El problema aparece cuando la implementación cambia y la documentación no.

Ejemplo típico:

[
  "foo",
  "bar"
]

La documentación dice que la API devuelve un array de strings, pero la implementación real termina devolviendo esto:

[
  {
    "value": "foo"
  },
  {
    "value": "bar"
  }
]

Ese desajuste rompe integraciones, genera bugs en frontend y hace que los consumidores de la API pierdan confianza en la documentación.

El diseño-primero invierte el flujo:

Especificación OpenAPI
        ↓
Mocks
        ↓
Documentación
        ↓
Pruebas
        ↓
Implementación

La especificación es la fuente de verdad. El código, los mocks y la documentación se derivan de ella o se validan contra ella.

Esto no es una diferencia teórica. En equipos frontend/backend, el diseño-primero permite trabajar en paralelo desde el primer día: frontend consume mocks, backend implementa contra el contrato y las pruebas validan que ambos coincidan.

La condición clave es que la herramienta haga que escribir la especificación sea rápido. Si definir un endpoint tarda más que implementarlo, el equipo terminará saltándose el diseño. Por eso una buena plataforma de diseño-primero debe hacer que la especificación sea fácil de crear, revisar y usar.

Qué significa diseño-primero en la práctica

Diseño-primero no es una tecnología específica. Es un flujo de trabajo.

1. Antes de escribir código

Primero defines el contrato de la API, normalmente como una especificación OpenAPI.

Debe incluir:

Rutas y métodos HTTP.
Parámetros de path, query y headers.
Esquemas de request body para POST, PUT y PATCH.
Esquemas de respuesta para códigos como 200, 400, 401, 422 y 500.
Reglas de autenticación.
Descripciones de campos.
Ejemplos de request y response.

Ejemplo simplificado de OpenAPI:

paths:
  /users/{id}:
    get:
      summary: Obtener usuario por ID
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: "Usuario encontrado"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UserProfile"
        "404":
          description: "Usuario no encontrado"

components:
  schemas:
    UserProfile:
      type: object
      required:
        - id
        - email
      properties:
        id:
          type: integer
          example: 123
        email:
          type: string
          format: email
          example: user@example.com

Esta fase es donde se toman decisiones importantes:

Nombres de campos.
Estructura de recursos.
Formato de errores.
Reglas de paginación.
Códigos de estado.
Compatibilidad hacia atrás.

2. Durante el desarrollo

La especificación se publica en un servidor mock.

El frontend puede consumir una URL simulada como si fuera la API real:

const response = await fetch("https://mock.example.com/users/123");
const user = await response.json();

console.log(user.email);

Mientras tanto, backend implementa contra el contrato:

app.get("/users/:id", async (req, res) => {
  const user = await userRepository.findById(req.params.id);

  if (!user) {
    return res.status(404).json({
      code: "USER_NOT_FOUND",
      message: "User not found"
    });
  }

  return res.json({
    id: user.id,
    email: user.email
  });
});

Frontend y backend ya no se bloquean mutuamente.

3. Después de implementar

Las pruebas validan que la respuesta real coincida con la especificación.

Por ejemplo, una prueba de contrato debería fallar si la API devuelve:

{
  "id": 123,
  "emailAddress": "user@example.com"
}

cuando la especificación exige:

{
  "id": 123,
  "email": "user@example.com"
}

El objetivo no es solo comprobar que la API responde, sino que responde con el contrato correcto.

4. Cuando cambian los requisitos

El cambio empieza en la especificación:

Se actualiza el contrato.
El equipo revisa el cambio.
Los mocks se actualizan.
La documentación refleja la nueva versión.
Backend ajusta la implementación.
Las pruebas detectan cualquier desviación.

Así evitas que la implementación se convierta en una fuente de verdad oculta.

Qué necesita una plataforma de diseño-primero

No todas las herramientas de API soportan bien este flujo. Una plataforma útil para diseño-primero debe cubrir estas piezas.

Editor visual de API

Editar YAML manualmente puede ser lento y propenso a errores de indentación.

Un buen editor visual debe permitir definir:

Método HTTP.
Ruta.
Parámetros.
Headers.
Request body.
Responses.
Schemas reutilizables.
Ejemplos.
Reglas de validación.

También debe generar OpenAPI válido y permitir reutilizar componentes.

Ejemplo de componente reutilizable:

components:
  schemas:
    ErrorResponse:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: string
        message:
          type: string

Luego puedes usarlo en varios endpoints:

responses:
  "400":
    description: Solicitud inválida
    content:
      application/json:
        schema:
          $ref: "#/components/schemas/ErrorResponse"

Validación de OpenAPI

La especificación debe validarse mientras la editas.

La herramienta debería detectar errores como:

Campos requeridos faltantes.
$ref rotos.
Tipos inválidos.
Responses sin descripción.
Schemas mal estructurados.

Cuanto antes aparezca el error, más barato es corregirlo.

Generación automática de mocks

El flujo ideal es:

Definir endpoint → Guardar especificación → Obtener mock funcional

Sin configuración manual adicional.

El mock debe respetar:

Tipos de datos.
Formatos (email, date-time, etc.).
Enumeraciones.
Rangos minimum / maximum.
Objetos anidados.
Arrays.
Referencias $ref.

Vista previa de documentación

La especificación debe poder renderizarse como documentación legible.

Esto permite revisar el contrato con:

Frontend.
Backend.
QA.
Product managers.
Stakeholders no técnicos.

Una buena vista previa debe mostrar:

Descripciones.
Parámetros.
Ejemplos.
Schemas.
Códigos de estado.
Reglas de autenticación.

Flujo de revisión en equipo

Los cambios en la especificación deben tratarse como cambios en código.

Un flujo práctico sería:

Alguien propone un cambio.
El equipo comenta.
Se ajusta la especificación.
Se aprueba.
Se implementa.

La plataforma debe soportar comentarios, historial y trazabilidad.

Exportación a OpenAPI estándar

La especificación tiene que ser portable.

Debes poder exportarla como OpenAPI 3.x y usarla con otras herramientas:

Generadores de código.
Gateways API.
Frameworks de prueba.
Validadores de contrato.
Herramientas de documentación.

Apidog como plataforma de diseño-primero

Apidog está organizado alrededor de la especificación como artefacto principal. La pestaña de diseño, el servidor mock, el ejecutor de pruebas y la documentación se conectan a la misma definición de API.

Editor visual de OpenAPI

La interfaz de diseño de Apidog usa edición basada en formularios.

Para cada endpoint puedes definir:

Ruta.
Método.
Parámetros.
Request body.
Responses.
Schemas.
Descripciones.
Reglas de validación.
Datos de mock.

No necesitas escribir YAML si no quieres. También puedes abrir una vista raw para editar YAML o JSON directamente. Los cambios entre la vista visual y la vista raw se sincronizan.

Los componentes de esquema son reutilizables. Puedes definir un esquema UserProfile una vez y referenciarlo desde múltiples endpoints con $ref.

Ejemplo:

components:
  schemas:
    UserProfile:
      type: object
      properties:
        id:
          type: integer
        email:
          type: string
          format: email
        displayName:
          type: string

Luego lo reutilizas:

schema:
  $ref: "#/components/schemas/UserProfile"

Si cambias UserProfile, todos los endpoints que lo referencian reflejan ese cambio.

Vista previa de documentación en tiempo real

Mientras diseñas un endpoint, la documentación se actualiza en tiempo real.

Esto te permite comprobar si el contrato es entendible antes de implementar.

Revisa especialmente:

Si los nombres de campos son claros.
Si las descripciones explican el comportamiento.
Si los ejemplos son realistas.
Si los errores están documentados.
Si los códigos de estado son correctos.

Puedes compartir un enlace de documentación con producto o frontend durante la fase de diseño. No necesitan instalar nada para revisarlo.

Smart Mock: de especificación a mock funcional

Cuando guardas un endpoint nuevo en Apidog, el servidor mock queda disponible de inmediato. La URL del mock aparece en la interfaz.

El mock genera respuestas basadas en los schemas:

Los strings con format: email devuelven emails válidos.
Los enteros con minimum y maximum devuelven valores dentro del rango.
Los enums devuelven valores permitidos.
Los objetos y arrays anidados siguen la estructura definida.
Los componentes $ref se resuelven correctamente.

Ejemplo de schema:

UserProfile:
  type: object
  properties:
    id:
      type: integer
      minimum: 1
      maximum: 9999
    email:
      type: string
      format: email
    role:
      type: string
      enum:
        - admin
        - member
        - viewer

El mock puede devolver algo como:

{
  "id": 42,
  "email": "user@example.com",
  "role": "member"
}

También puedes configurar reglas personalizadas. Por ejemplo:

Devolver 404 cuando el parámetro id sea 0.
Devolver una respuesta específica para ?status=inactive.
Simular errores de validación para pruebas de frontend.

Revisión en equipo y seguimiento de cambios

En Apidog, los cambios en la especificación son visibles para los miembros del workspace.

El equipo puede:

Comentar endpoints.
Comentar campos específicos.
Revisar cambios.
Ver quién modificó qué y cuándo.

Para diseño-primero, esto evita procesos paralelos. La revisión del contrato ocurre en la misma herramienta donde se diseña, documenta, prueba y simula la API.

Diseño-primero vs. código-primero: compensaciones reales

Diseño-primero no siempre es la mejor opción. Depende del tipo de proyecto y del equipo.

Ventajas del diseño-primero

Frontend y backend pueden trabajar en paralelo.
La documentación es precisa porque nace del contrato.
Los problemas de integración aparecen antes.
El contrato de API es explícito y verificable.
Los cambios pasan por revisión.
Los mocks están disponibles desde el inicio.

Desventajas del diseño-primero

Requiere tiempo inicial para definir la especificación.
La herramienta de especificación tiene curva de aprendizaje.
Exige disciplina para mantener implementación y contrato sincronizados.
Puede llevar a especificar demasiado pronto si el dominio aún no está claro.

Ventajas del código-primero

Más rápido para prototipos pequeños.
Menos proceso para desarrolladores individuales.
No necesitas aprender una herramienta adicional.
Útil cuando la API cambia constantemente durante exploración.

Desventajas del código-primero

La documentación es secundaria y puede quedar obsoleta.
Frontend suele esperar a backend para integrar.
El contrato es implícito.
Los breaking changes son más difíciles de detectar.
Refactorizar la API requiere actualizar documentación manualmente.

Para equipos con más de un ingeniero trabajando en una API, diseño-primero suele dar mejores resultados. La inversión inicial se compensa cuando hay coordinación real entre frontend, backend, QA y producto.

Herramientas que soportan flujos de diseño-primero

Apidog

Apidog ofrece una plataforma completa para diseño-primero: editor visual, mocks instantáneos, documentación, pruebas y revisión en equipo en una sola herramienta. El nivel gratuito cubre el conjunto completo de funciones. Su generación de mocks es uno de sus diferenciadores principales.

Stoplight Studio

Stoplight Studio es un editor OpenAPI sólido con linting Spectral para aplicar reglas de estilo. No incluye servidor mock ni ejecutor de pruebas incorporados. Es útil para organizaciones que necesitan gobernanza de APIs, aunque puede resultar caro para equipos pequeños.

SwaggerHub

SwaggerHub es una plataforma madura para edición y colaboración sobre OpenAPI. Se usa mucho en empresas. Su capacidad de mock es limitada y no incluye pruebas. Encaja bien en organizaciones centradas en especificaciones dentro del ecosistema Swagger.

Postman con API Builder

Postman incluye una pestaña para diseño de APIs que genera especificaciones OpenAPI. Sin embargo, los flujos de diseño y colecciones pueden sentirse desconectados. El servidor mock requiere configuración manual a partir de colecciones, en lugar de generarse automáticamente desde la especificación. Funciona para equipos código-primero que quieren añadir documentación.

Insomnia con modo documento

Insomnia soporta edición de especificaciones OpenAPI y proporciona mock básico. Es menos completo que herramientas dedicadas a diseño-primero, pero puede servir para desarrolladores individuales que buscan una opción ligera.

Cómo configurar un flujo diseño-primero en Apidog

Paso 1: Empieza con la especificación, no con una colección

Crea un proyecto nuevo y abre la pestaña de diseño.

Antes de enviar una sola request, define como mínimo:

Ruta.
Método.
Parámetros principales.
Response esperado.
Schema de error.

Ejemplo de checklist para un endpoint:

[ ] Método HTTP definido
[ ] Ruta definida
[ ] Parámetros documentados
[ ] Response 200 definido
[ ] Response de error definido
[ ] Schema reutilizable si aplica
[ ] Ejemplo de respuesta incluido

Paso 2: Define componentes compartidos primero

Antes de añadir muchos endpoints, define los schemas reutilizables.

Por ejemplo:

ErrorResponse
PaginationMeta
UserProfile
Address
CreatedResourceResponse

Ejemplo:

components:
  schemas:
    PaginationMeta:
      type: object
      properties:
        page:
          type: integer
        pageSize:
          type: integer
        total:
          type: integer

Esto evita que cada endpoint invente su propio formato de paginación.

Paso 3: Obtén la URL del mock temprano

Cuando guardes el endpoint, copia la URL del mock y compártela con frontend.

Frontend puede empezar a integrar con algo como:

const API_BASE_URL = "https://mock.example.com";

export async function getUser(id) {
  const response = await fetch(`${API_BASE_URL}/users/${id}`);

  if (!response.ok) {
    throw new Error("Failed to fetch user");
  }

  return response.json();
}

Cuando backend esté listo, solo se cambia el API_BASE_URL.

Paso 4: Revisa la documentación antes de implementar

Abre la vista previa de documentación y valida:

¿La descripción del endpoint explica qué hace?
¿Los parámetros tienen significado claro?
¿Los ejemplos ayudan a consumir la API?
¿Los errores esperados están definidos?
¿El schema refleja lo que frontend necesita?

Si algo no se entiende en la documentación, tampoco será claro para quien consuma la API.

Paso 5: Bloquea la especificación para el sprint

Cuando el diseño esté revisado, trata la especificación como bloqueada para ese sprint.

Si backend descubre que necesita cambiar el contrato, el flujo debería ser:

Proponer cambio → Revisar con frontend/producto → Actualizar especificación → Implementar

No cambies silenciosamente la respuesta real.

Paso 6: Ejecuta validación de schema en CI

Configura pruebas para comprobar que la implementación real coincide con la especificación.

El objetivo es detectar automáticamente cambios como:

Campos faltantes.
Tipos incorrectos.
Códigos de estado no documentados.
Estructuras de error inconsistentes.
Responses incompatibles con el schema.

Esta es la barrera que mantiene sincronizados contrato e implementación.

Preguntas frecuentes

¿El diseño-primero es solo para APIs REST?

No. El principio aplica a cualquier protocolo donde puedas definir un contrato:

REST con OpenAPI.
GraphQL con schema-first.
gRPC con protobuf.
Sistemas event-driven con AsyncAPI.

Apidog soporta diseño REST y GraphQL. Para gRPC, los archivos proto cumplen el mismo rol de contrato primero.

¿Tenemos que definir todos los endpoints antes de empezar?

No. Puedes adoptar diseño-primero por funcionalidad.

Por ejemplo, si vas a construir una nueva pantalla de perfil de usuario, define primero los endpoints necesarios para esa pantalla, aunque otras partes del sistema sigan siendo código-primero.

La adopción incremental funciona bien.

¿Cómo encaja diseño-primero con sprints ágiles?

Al inicio del sprint, el equipo define el contrato de API para las funcionalidades planificadas.

Luego:

Frontend trabaja contra mocks.
Backend implementa contra la especificación.
QA revisa escenarios desde el contrato.
La documentación queda lista como parte del flujo.

La revisión de especificación pasa a formar parte de la planificación técnica del sprint.

¿Qué pasa si la implementación necesita diferir de la especificación original?

Puede pasar.

El proceso correcto es:

Actualizar la especificación.
Revisar el cambio con los interesados.
Actualizar mocks y documentación.
Modificar la implementación.
Ejecutar pruebas de contrato.

Así la especificación sigue siendo la fuente de verdad.

¿Podemos generar stubs de servidor desde la exportación OpenAPI de Apidog?

Sí. Puedes exportar la especificación de Apidog como OpenAPI 3.x y usar generadores estándar para crear stubs de servidor.

Por ejemplo, con openapi-generator puedes generar código base para distintos lenguajes y frameworks.

Flujo típico:

Exportar OpenAPI → Ejecutar generador → Implementar handlers → Validar contra contrato

¿Cómo manejamos el versionado de la especificación?

Apidog mantiene historial de cambios dentro del proyecto.

Para versiones mayores que conviven en paralelo, como v1 y v2, puedes usar proyectos o ramas separadas.

Ejemplo:

api-users-v1
api-users-v2

O bien:

main
v2-design

según el flujo de trabajo del equipo.

Conclusión

El diseño-primero exige una pequeña inversión inicial: definir el contrato antes de implementar. A cambio, reduce costos de integración, mejora la colaboración entre frontend y backend y mantiene la documentación alineada con la API real.

La herramienta importa. Si escribir la especificación es lento o incómodo, el equipo la evitará. Un editor visual, mocks instantáneos, documentación en tiempo real y pruebas de contrato hacen que diseño-primero sea práctico.

Apidog combina esas piezas en un flujo único, lo que ayuda a convertir la especificación en el centro del desarrollo de APIs, no en una tarea secundaria al final del sprint.

Actualizaciones de APIDOG Abril: Depurador de Agente IA, Depurador A2A y Migración Sencilla a Postman

Roobia — Wed, 29 Apr 2026 08:48:20 +0000

El lanzamiento de abril se centra en un objetivo práctico: facilitar la inspección y depuración del desarrollo de Agentes de IA.

Prueba Apidog hoy

Si estás construyendo agentes, el problema no suele estar solo en la respuesta final. También necesitas entender qué ocurrió antes: qué interpretó el agente, qué herramienta llamó, qué devolvió esa herramienta y si el fallo estuvo en el prompt, en la configuración del modelo o en la lógica de negocio.

Este mes, Apidog añade nuevas herramientas para ese flujo de trabajo: Depurador de Agentes de IA, Depurador A2A, importación de API de Postman para migraciones grandes, una mejor experiencia de “Preguntar a la IA” en documentos publicados y soporte para proveedores de modelos personalizados.

Esto es lo que cambió 👇

⭐ Nuevas Actualizaciones

🔥 Depurador de Agentes de IA: inspecciona la ejecución completa del agente

Apidog ya soportaba depuración visual para endpoints SSE, útil para respuestas en streaming, actualizaciones de progreso, notificaciones en tiempo real y otras APIs basadas en eventos.

Pero depurar agentes requiere más que ver una transmisión.

Una respuesta del modelo solo muestra dónde terminó el agente. Para depurar un sistema real, necesitas ver los pasos intermedios:

Turnos de conversación.
Llamadas al modelo.
Llamadas a herramientas MCP.
Ejecución de Habilidades personalizadas.
Resultados devueltos por herramientas.
Salida final.

El nuevo Depurador de Agentes de IA está diseñado para inspeccionar esa ruta de ejecución dentro de Apidog.

En lugar de revisar únicamente la respuesta final, puedes seguir la ejecución completa del agente en un solo lugar. Esto ayuda a responder preguntas concretas de depuración:

¿El prompt dio suficiente contexto al modelo?
¿El agente eligió la herramienta correcta?
¿La herramienta MCP devolvió el resultado esperado?
¿El error viene de la configuración del modelo?
¿El problema está en los parámetros de la herramienta?
¿La lógica de negocio produjo una salida incorrecta?

Un flujo típico de depuración puede verse así:

Usuario
  ↓
Prompt del agente
  ↓
Llamada al modelo
  ↓
Selección de herramienta
  ↓
Llamada MCP o Habilidad personalizada
  ↓
Resultado de herramienta
  ↓
Respuesta final

Con el depurador, el objetivo es no tratar ese flujo como una caja negra. Puedes revisar cada paso y localizar en qué punto se desvió el comportamiento esperado.

🤝 Depurador A2A: prueba la comunicación agente-a-agente

Los sistemas multiagente son cada vez más comunes. Cuando varios agentes colaboran, necesitas validar que puedan:

Pasar tareas correctamente.
Intercambiar mensajes.
Recibir parámetros válidos.
Devolver resultados interpretables.
Manejar respuestas entre agentes sin romper el flujo.

Apidog ahora soporta depuración para el protocolo A2A de Google, es decir, Agent-to-Agent.

Desde Apidog puedes enviar solicitudes A2A directamente, inspeccionar los parámetros de solicitud, revisar respuestas y validar el resultado de la interacción. Esto evita tener que alternar entre herramientas separadas o revisar manualmente los detalles del protocolo durante cada prueba.

La diferencia entre las dos nuevas herramientas es directa:

Herramienta	Qué depura
Depurador de Agentes de IA	Lo que ocurre dentro de un agente durante una tarea
Depurador A2A	La comunicación entre un agente y otro agente

En la práctica, si estás construyendo agentes para producción, probablemente necesitarás ambas capacidades: una para entender el comportamiento interno y otra para validar la colaboración entre agentes.

📦 Importa datos de Postman a través de la API de Postman

La migración desde Postman ahora tiene una opción más cómoda para equipos grandes.

Apidog ya soportaba la importación de archivos locales de Postman. Ahora también puedes importar:

Workspaces.
Collections.
Environments.

Todo esto puede hacerse a través de la API de Postman.

Este flujo está pensado para migraciones masivas al crear nuevos proyectos. En lugar de exportar archivos locales uno por uno, puedes mover una estructura más completa desde Postman hacia Apidog.

Si tu cuenta de Postman tiene varios Workspaces, Apidog creará proyectos correspondientes después de la importación.

Para migraciones pequeñas, los archivos locales siguen siendo una opción válida. Para migraciones grandes, la importación mediante API reduce pasos repetitivos como:

Exportar colecciones manualmente.
Descargar entornos.
Subir archivos uno por uno.
Reorganizar proyectos después de la importación.

Un flujo de migración más práctico sería:

Postman Workspace
  ↓
API de Postman
  ↓
Importación en Apidog
  ↓
Proyecto correspondiente en Apidog

Esto hace que el proceso sea más manejable cuando el equipo trabaja con múltiples espacios, colecciones y entornos.

📄 “Preguntar a la IA” en documentos publicados ahora se abre en la barra lateral

La función “Preguntar a la IA” en documentación publicada ahora se abre en una barra lateral.

Esto mejora el flujo de lectura de documentación técnica porque puedes mantener la página actual abierta mientras haces preguntas sobre su contenido.

Por ejemplo, puedes:

Leer un endpoint en la documentación publicada.
Abrir “Preguntar a la IA” en la barra lateral.
Consultar detalles sobre parámetros, respuestas o uso esperado.
Seguir leyendo sin perder tu posición en la página.

El cambio es pequeño a nivel de interfaz, pero útil en documentos largos. Evita alternar entre vistas y reduce el tiempo necesario para encontrar información específica dentro de una página extensa.

🧠 Proveedores de modelos de IA personalizados

Los equipos ahora pueden conectar proveedores personalizados usando una URL Base personalizada.

Esto resulta útil si tu organización ya trabaja con:

Un servicio de modelo autoalojado.
Una pasarela interna de modelos.
Una configuración corporativa específica para IA.

En lugar de cambiar de herramienta cada vez que necesitas depurar un flujo relacionado con IA, puedes integrar esa configuración en Apidog y mantener el flujo de trabajo en el mismo entorno.

Un caso típico sería:

Apidog
  ↓
URL Base personalizada
  ↓
Proveedor de modelo interno o autoalojado
  ↓
Respuesta del modelo

Esto da más flexibilidad a los equipos que no dependen exclusivamente de proveedores públicos o que necesitan trabajar con infraestructura interna.

🐞 Corrección de errores y pequeñas mejoras

También se lanzaron varias correcciones y mejoras de calidad de vida este mes:

Se corrigió un problema donde la fusión inteligente de OpenAPI no mantenía los ejemplos de respuesta del endpoint.
Se corrigió un problema donde la fusión de una rama secundaria a una rama principal protegida podía incluir endpoints que no estaban seleccionados.
Se corrigió la visualización incorrecta del desplegable al crear versiones de endpoints desde ramas.
Se corrigió un problema donde TestData y TestCases no funcionaban al ejecutar pruebas a través de la CLI.
Se corrigió un problema donde la exportación de OpenAPI incluía componentes de respuesta de módulos no relacionados.
Se corrigió el formato de exportación de Markdown para JSON con comentarios.
Se corrigió un error de exportación de Word causado por crypto is not defined.
Se corrigió un problema donde la importación de Knife4j con Basic Auth habilitado no mostraba los campos de nombre de usuario y contraseña.
Se corrigió un error de filtrado de endpoints cuando las etiquetas eran números.
Se corrigió un problema donde apidog endpoint list --branch no devolvía datos para la rama especificada.
Se corrigieron varios problemas de parámetros, filtrado y mensajes de error de la herramienta MCP.
Se corrigió un problema donde el código generado no incluía la opción de configuración typescriptThreePlus.

🌟 Qué significa esto para equipos que construyen agentes

Este lanzamiento está orientado a flujos de trabajo reales de desarrollo de Agentes de IA.

En resumen:

Usa el Depurador de Agentes de IA para inspeccionar una ejecución completa de un agente.
Usa el Depurador A2A para validar comunicación entre agentes.
Usa la importación mediante API de Postman para migraciones grandes.
Usa la barra lateral de “Preguntar a la IA” para consultar documentación publicada sin perder contexto.
Usa proveedores de modelos personalizados si tu equipo trabaja con modelos internos o autoalojados.

No son cambios pensados solo para demos. Son herramientas útiles cuando el desarrollo de agentes pasa a proyectos más complejos, donde necesitas trazabilidad, migración ordenada y depuración más precisa.

💬 Únete a la conversación

Conéctate con otros ingenieros de API y el equipo de Apidog:

Únete a nuestra comunidad de Discord para discusiones y soporte en tiempo real.
Participa en nuestra comunidad de Slack para conversaciones técnicas.
Síguenos en X (Twitter) para las últimas actualizaciones.

P.D. Para todos los detalles sobre las actualizaciones, consulta el Changelog de Apidog.

Saludos cordiales,

El equipo de Apidog

Facturación del Uso de GitHub Copilot: Qué Esperar para Equipos API

Roobia — Wed, 29 Apr 2026 07:08:30 +0000

El modelo de facturación de GitHub Copilot cambió dos veces el año pasado y volvió a cambiar este mes. Desde ahora, la revisión de código de Copilot en pull requests consume minutos de GitHub Actions de la cuenta de facturación propietaria del repositorio. Para equipos de API, esto significa gestionar tres medidores en paralelo: licencias de Copilot, solicitudes premium y minutos de Actions. Esta guía muestra qué mide cada uno, por qué los repositorios de API suelen consumir más y cómo estimar el costo antes de que aparezca en la factura.

Prueba Apidog hoy

Al final, lo conectamos con un flujo de trabajo en Apidog para mantener especificaciones de API, pruebas de contrato y revisión de IA en un solo pipeline, en lugar de repartir el control entre varios paneles de facturación.

Si también está modelando los costos de las API que su equipo consume directamente, estas guías sobre precios de GPT-5.5 y precios de DeepSeek V4 cubren el lado por token de la misma conversación.

En resumen: TL;DR

Copilot ahora tiene tres medidores relevantes: licencia por usuario, solicitudes premium y minutos de Actions para la revisión de código.
La revisión de código en PR se ejecuta internamente como una GitHub Action y consume minutos de la cuota normal de Actions de la organización.
Los repositorios de API suelen consumir más porque las PR incluyen especificación, clientes generados, handlers y pruebas.
Las solicitudes premium aplican a flujos como Workspace, modo agente, Copilot Spaces y selección de modelos.
Configure límites de gasto antes del siguiente ciclo de facturación.
Como punto inicial, presupueste entre 400 y 800 minutos de Actions al mes por repositorio de API activo y revise los datos después de 30 días.

Los tres medidores de Copilot

Copilot dejó de ser una única línea de costo. Ahora conviene separarlo en tres partes.

Medidor 1: licencia por usuario

Este es el costo fijo.

Copilot Business: 10 USD por usuario al mes.
Copilot Enterprise: 19 USD por usuario al mes.

La licencia cubre chat, completions en línea, sugerencias multilínea, integraciones IDE y acceso al grupo de modelos estándar.

Acción recomendada:

Exporte la lista de usuarios con licencia.
Revise actividad real por usuario.
Recupere licencias de usuarios inactivos.
Repita la auditoría cada trimestre.

La licencia es el componente más fácil de estimar, pero también el más comúnmente sobredimensionado.

Medidor 2: solicitudes premium

Las solicitudes premium son la unidad de consumo para funciones más costosas de Copilot.

Cuentan como solicitudes premium las operaciones en:

Modo agente.
Workspace.
Copilot Spaces.
Selección de modelos fuera del predeterminado.

Tarifas actuales, sujetas a cambios:

Característica	Costo en solicitudes premium
Chat del modelo predeterminado	Gratis para niveles de pago
Completions en línea	Gratis para niveles de pago
Modo agente con modelo predeterminado	1 por solicitud
Workspace con modelo predeterminado	1 por solicitud
Claude Sonnet 4.5	Multiplicador de 1.5x
GPT-5.5	Multiplicador de 2x
GPT-5.5 Pro	Multiplicador de 6x
Consulta de Copilot Spaces	1 por consulta

Cuotas incluidas:

Plan	Solicitudes premium incluidas
Copilot Business	300 por usuario/mes
Copilot Enterprise	1.000 por usuario/mes

El exceso se factura a 0,04 USD por solicitud, hasta el límite de gasto configurado en la organización.

En equipos de API, los prompts que más consumen suelen ser tareas como:

Regenera el cliente OpenAPI para este cambio.

Escribe una prueba de contrato para este nuevo endpoint.

Actualiza el handler, la validación y los tests para esta ruta.

Aunque el desarrollador envíe una sola instrucción, el flujo interno puede ejecutar varios pasos y consumir varias solicitudes premium.

Medidor 3: minutos de Actions para revisión de código

Este es el cambio más importante para pipelines.

Cuando Copilot revisa una pull request, esa revisión se ejecuta como una GitHub Action. Por lo tanto, consume minutos del mismo pool de Actions que usa su CI.

Dos reglas prácticas:

Los minutos se descuentan de la cuota normal de GitHub Actions del plan.
En repositorios privados, esos minutos cuentan contra el presupuesto de Actions. En repositorios públicos, las Actions son gratuitas.

Una revisión típica de Copilot en una PR de API consume entre 2 y 6 minutos de Actions. Una revisión pesada, con diff grande y mucho contexto, puede llegar a 15 minutos.

Fórmula rápida:

minutos_revision = pull_requests_mes × minutos_promedio_por_revision

Ejemplo:

50 PR/mes × 4 min = 200 min/mes

En un único repositorio, eso puede parecer poco. En varios repositorios activos, empieza a competir con el presupuesto de CI.

Por qué los repositorios de API consumen más

Los repositorios de API suelen golpear estos medidores con más fuerza por tres motivos.

1. Las PR son más grandes

Un cambio típico de API puede tocar:

openapi.yaml
Clientes generados
Handler o controlador del servidor
Validaciones
Tests unitarios
Tests de contrato
Documentación

Copilot necesita leer más contexto, por lo que la revisión tarda más y consume más minutos de Actions.

2. El código generado infla el diff

Muchos equipos versionan clientes generados en varios lenguajes. Por ejemplo:

clients/typescript/**
clients/python/**
clients/java/**

Si Copilot revisa esos archivos, paga el costo de procesar código que normalmente no requiere revisión humana ni IA.

Acción recomendada: excluya clientes generados de la revisión.

3. Varias herramientas se ejecutan en la misma PR

Una PR de API puede activar:

Copilot review.
CodeQL.
Snyk.
Escáneres internos.
Tests de contrato.
Generación de clientes.
Validación OpenAPI.

Cada herramienta consume su propio tiempo de ejecución. Copilot no reemplaza esos costos; se suma a ellos.

Ejemplo:

50 PR/mes × 4 min/revisión = 200 min/mes

Con tres repositorios similares:

3 × 200 = 600 min/mes

Y eso antes de contar builds, tests y despliegues.

Cómo estimar la factura mensual

Use una estimación en tres pasos.

Paso 1: calcule licencias

costo_licencias_business = usuarios_activos × 10
costo_licencias_enterprise = usuarios_activos × 19

Ejemplo:

10 usuarios × 19 USD = 190 USD/mes

Paso 2: calcule solicitudes premium

Estime el consumo por perfil de usuario:

Perfil	Uso mensual aproximado
Usuario principalmente de chat	~150 solicitudes
Usuario intensivo de Workspace/agente	~600 a 800 solicitudes

Fórmula para Copilot Business:

exceso_premium = max(0, solicitudes_usadas - 300_por_usuario) × 0.04

Ejemplo:

solicitudes_usadas = 800
cuota_incluida = 300
exceso = 500

500 × 0.04 = 20 USD

Acción recomendada: configure un límite de gasto a nivel de organización. El valor predeterminado ilimitado no es seguro para equipos que aún no monitorean consumo.

Paso 3: calcule minutos de Actions para revisión

Use el promedio real si ya tiene datos. Si no, empiece con 4 minutos por PR de API.

minutos_revision = prs_mes × 4

Para repositorios privados en Linux:

exceso_actions = max(0, minutos_revision - cuota_actions_disponible) × 0.008

Ejemplo para un equipo de 10 desarrolladores en Enterprise que fusiona 200 PR al mes:

Licencias:          10 × 19 = 190 USD
Exceso premium:    ~40 USD
Revisión Copilot:  200 × 4 = 800 min/mes
Exceso Actions:    0 USD si entra en cuota

Total aproximado:

230 USD/mes

En equipos Business pequeños, el exceso puede aparecer antes porque las cuotas incluidas son más ajustadas.

Cambios recomendados en el pipeline de CI

Estos ajustes reducen consumo sin eliminar la revisión cuando aporta valor.

1. Omita bots y PR automáticas

No ejecute revisión de Copilot en PR de Dependabot, Renovate u otros automatizadores.

on:
  pull_request:
    types: [opened, synchronize]

jobs:
  copilot-review:
    if: github.actor != 'dependabot[bot]' && github.actor != 'renovate[bot]'
    runs-on: ubuntu-latest
    steps:
      - uses: github/copilot-review@v1

Esto evita gastar minutos en actualizaciones de dependencias que ya tienen un patrón de revisión conocido.

2. Filtre archivos generados

En repositorios de API, excluya clientes generados y artefactos derivados.

Ejemplo de rutas que sí conviene revisar:

on:
  pull_request:
    paths:
      - 'apis/**/*.yaml'
      - 'cmd/**'
      - 'internal/**'
      - 'tests/**'

Evite rutas como:

clients/generated/**
sdk/**
dist/**

La revisión se concentra en lógica, contratos y tests, no en archivos generados.

3. Use validación barata antes de revisión cara

Ordene el pipeline así:

Validar especificación OpenAPI.
Ejecutar pruebas de contrato.
Ejecutar tests rápidos.
Solo si todo pasa, activar revisión de Copilot.

Ejemplo conceptual:

jobs:
  contract-tests:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Run contract validation
        run: apidog-cli test

  copilot-review:
    needs: contract-tests
    if: needs.contract-tests.result == 'success'
    runs-on: ubuntu-latest
    steps:
      - uses: github/copilot-review@v1

La idea es simple: falle rápido con checks baratos y reserve Copilot para PR que ya pasaron validación básica.

4. Use activación por etiqueta

En lugar de revisar cada PR, active Copilot solo cuando la PR tenga una etiqueta explícita.

Ejemplo de política:

review-please

Modelo recomendado:

PR pequeñas: revisión humana normal.
PR de cambios de contrato: Copilot review.
PR críticas o de seguridad: Copilot review + revisión humana obligatoria.

Este patrón reduce costos sin perder cobertura en cambios importantes.

Gobernanza: controles mínimos

Configure estos cuatro controles antes del próximo ciclo de facturación.

1. Límite de gasto

Defínalo a nivel de organización.

Recomendación práctica:

límite = presupuesto_mensual_esperado × 0.8

Si el presupuesto esperado es 500 USD:

500 × 0.8 = 400 USD

Así fuerza una revisión antes de que el consumo se descontrole.

2. Alertas de solicitudes premium

GitHub envía alertas al 50 %, 75 % y 90 % de la cuota incluida.

No las deje solo en correo. Envíelas también a:

Slack.
Microsoft Teams.
PagerDuty.
La herramienta interna de incidentes.

3. Política de disparadores por repositorio

Defina una regla clara:

Copilot review en todas las PR.
Copilot review solo con etiqueta.
Copilot review solo en rutas específicas.
Copilot review solo en repositorios críticos.

Para equipos de API, el modelo por etiqueta suele ser el más equilibrado.

4. Habilitación por equipo

No active todas las funciones de Copilot Enterprise para toda la organización de una vez.

Empiece con:

Equipo de plataforma.
Equipo de API principal.
Repositorios con mayor volumen de cambios.
Expansión gradual tras 30 días de métricas.

Dónde encaja Apidog

Apidog no reemplaza Copilot. Sirve como capa para centralizar especificaciones, mocks y pruebas de contrato, de modo que la revisión de IA no tenga que resolver problemas que el pipeline puede detectar antes.

Un flujo práctico:

Mantenga la especificación y ejemplos de requests en la colección de Apidog junto al repositorio.
Ejecute pruebas de contrato contra el mock server de Apidog.
Valide contratos antes de activar revisión de Copilot.
Use Copilot para revisar lógica de controladores, cobertura y cambios no triviales.
Excluya clientes generados y artefactos derivados.

Secuencia recomendada:

OpenAPI spec
   ↓
Apidog mock server
   ↓
Contract tests
   ↓
CI checks
   ↓
Copilot review
   ↓
Human review

Esto importa porque la revisión de Copilot es uno de los pasos más caros del pipeline. Si una PR falla por contrato, conviene detectarlo antes de gastar minutos de revisión.

La guía de pruebas de API sin Postman cubre el flujo de simulación de Apidog. La guía de la API de DeepSeek V4 muestra el patrón aplicado a una API de modelo.

Qué revisar en el próximo ciclo de facturación

Ponga estos hitos en el calendario.

Días 1 a 7

Revise:

Usuarios activos.
Solicitudes premium por usuario.
Repositorios con Copilot review activado.
Minutos de Actions usados por CI.

En esta etapa, la mayoría de equipos aún está dentro de la cuota incluida.

Días 14 a 21

Aquí suelen aparecer los usuarios intensivos.

Revise:

solicitudes premium usadas / cuota incluida

Si configuró un límite de gasto, algunas solicitudes pueden empezar a fallar. Si no configuró límite, la factura seguirá creciendo.

Días 28 a 30

Compare contra el mes anterior:

Minutos de Actions totales.
Minutos atribuidos a revisión.
PR revisadas por Copilot.
PR de bots revisadas por error.
Rutas que dispararon revisiones innecesarias.

Ajuste:

Filtros de ruta.
Etiquetas.
Repositorios habilitados.
Licencias inactivas.
Usuarios que deberían pasar a Enterprise por volumen.

Errores comunes

Estos son los problemas que más suelen aparecer en auditorías de equipos de API.

1. No configurar límite de gasto

Un flujo de agente mal definido puede consumir durante horas. Siempre configure un límite.

2. Activar revisión en todos los repositorios

No todos los repositorios necesitan revisión de Copilot. Priorice:

APIs críticas.
Servicios con alto volumen de cambios.
Repositorios con lógica compleja.
Cambios de contrato frecuentes.

3. Revisar clientes generados

Filtre rutas generadas. Es uno de los ahorros más rápidos.

4. Revisar PR de bots

Excluya:

dependabot[bot]
renovate[bot]
Bots internos de actualización
Automatizaciones de versionado

5. No guardar una línea base

Sin una medición previa, no puede saber si un cambio ahorró dinero.

Cada mes, exporte CSV desde facturación de GitHub y guarde:

mes
repositorio
minutos_actions
solicitudes_premium
usuarios_activos
prs_revisadas
costo_total

FAQ

¿El precio por usuario sigue siendo de 10 USD?

Copilot Business cuesta 10 USD por usuario al mes. Copilot Enterprise cuesta 19 USD por usuario al mes. Copilot Pro para individuos cuesta 10 USD al mes. El plan también determina la cuota incluida de solicitudes premium.

¿Las completions en línea ahora se miden?

No. El chat con modelo predeterminado y las completions en línea no se miden para niveles de pago. Las solicitudes premium aplican a funciones más costosas y selección de modelos.

¿Qué pasa cuando se agota mi cuota premium?

Por defecto, las solicitudes pueden fallar con error de cuota. También puede configurar un límite de gasto para permitir exceso a 0,04 USD por solicitud hasta el límite definido.

¿Los minutos de Actions para revisión se facturan por separado?

No. Consumen el mismo grupo de minutos de GitHub Actions que usa el resto de su CI.

¿Puedo deshabilitar por completo la revisión de Copilot?

Sí. El administrador de la organización puede excluir repositorios mediante políticas. También puede controlar la activación por equipo.

¿Copilot review funciona con especificaciones de API privadas?

Sí. En repositorios privados, la revisión consume minutos de Actions. En repositorios públicos, las Actions son gratuitas.

¿La revisión de Copilot también usa solicitudes premium?

Actualmente consume minutos de Actions. El modelo usado por el revisor forma parte de la plataforma Copilot y no se factura por separado como solicitud premium. Esta parte podría cambiar, así que conviene seguir el changelog de GitHub.

Para equipos que ejecutan revisión de Copilot y llamadas directas a APIs de modelos en CI, la guía de GPT-5.5 free Codex cubre el lado por token. Apidog ayuda a mantener la capa de mock y contrato antes de ejecutar revisiones de IA más costosas.

Cómo Usar la API de Zuplo

Roobia — Mon, 27 Apr 2026 08:42:42 +0000

Si has leído sobre Zuplo y quieres implementar algo real con él, esta es la publicación para ti. La plataforma es rápida de aprender, pero la documentación está dispersa en flujos del portal, comandos de CLI y artículos del centro de aprendizaje. Esta guía une las piezas en un solo tutorial: crear un proyecto, exponer una ruta, agregar autenticación con clave API y limitación de velocidad, escribir una política personalizada de TypeScript, desplegar en el edge y probar todo con Apidog.

Prueba Apidog hoy

Al final, tendrás una puerta de enlace API funcional ejecutándose frente a tu origen, con autenticación, limitación de velocidad, un portal para desarrolladores autogenerado y un flujo de trabajo Git compatible con CI. Todo el recorrido te llevará unos treinta minutos.

Si aún estás decidiendo si Zuplo es la herramienta adecuada, comienza con nuestra publicación complementaria: Qué es la puerta de enlace API de Zuplo. Para todo lo demás, la documentación de Zuplo cubre casos especiales que esta guía omite.

En resumen

Regístrate en portal.zuplo.com o andamia un proyecto local con npm create zuplo.
Define rutas en config/routes.oas.json y reenvíalas a tu origen con el Manejador de Reenvío de URL (URL Forward Handler).
Agrega políticas de entrada (autenticación con clave API, límite de velocidad, validación de esquema) editando el archivo de ruta o haciendo clic en el Diseñador de Rutas.
Escribe lógica personalizada como módulos de TypeScript en modules/; el tiempo de ejecución te da acceso tipado a la solicitud, el contexto y el entorno.
Haz push a tu rama de Git vinculada para desplegar un entorno de vista previa; fusiona para enviar a producción en más de 300 ubicaciones edge.
Prueba cada ruta con Apidog antes de promover a producción.
El precio comienza gratis con 100K solicitudes al mes; el plan Builder cuesta $25 al mes.

Requisitos previos

Necesitas tres cosas antes de empezar:

Una cuenta de Zuplo
Una API de origen para colocar la puerta de enlace delante. Si no tienes una, usa https://echo.zuplo.io, que replica lo que le envíes.
Node.js 18 o superior si planeas usar la CLI.

Para el desarrollo local también necesitas un editor de código. VS Code con la extensión de TypeScript es el camino de menor resistencia, y puedes combinarlo con la extensión de Apidog para VS Code para enviar solicitudes sin salir de tu editor.

Paso 1: Crea tu proyecto Zuplo

Tienes dos formas de empezar: el portal web o la CLI. La mayoría de los equipos comienzan en el portal porque es más rápido para una demostración, y luego migran a la CLI una vez que desean CI/CD.

Opción A: Primero el portal

Inicia sesión en portal.zuplo.com.
Haz clic en "New Project" (Nuevo Proyecto) y elige un nombre como acme-gateway.
Elige "Empty Project" (Proyecto Vacío) para que no se cree nada automáticamente.
La pestaña Código se abre a un árbol de archivos inicial.

El portal vincula el proyecto a un repositorio Git gestionado por defecto. Puedes conectar tu propio repositorio de GitHub, GitLab, Bitbucket o Azure DevOps desde Configuración más tarde.

Opción B: Primero la CLI

La CLI andamia el mismo diseño de proyecto localmente para que puedas editar en tu IDE y usar Git desde el primer día.

npm create zuplo@latest -- --name acme-gateway
cd acme-gateway
npm install
npm run dev

El servidor de desarrollo se inicia en el puerto 9000 y muestra un enlace al Diseñador de Rutas local en http://localhost:9100. Cualquier cambio que realices en el editor o en el diseñador se recarga automáticamente de inmediato.

Para vincular el proyecto local a tu cuenta Zuplo una vez que estés listo para desplegar:

npx zuplo link

Elige la cuenta y el entorno cuando se te solicite. Desde aquí, npx zuplo deploy despliega la rama Git actual.

Paso 2: Define tu primera ruta

Abre config/routes.oas.json. Este es un documento OpenAPI 3 con extensiones Zuplo para manejadores y políticas. Agrega una ruta que reenvíe GET /v1/products a tu origen:

{
  "openapi": "3.1.0",
  "info": { "title": "Acme Gateway", "version": "1.0.0" },
  "paths": {
    "/v1/products": {
      "get": {
        "summary": "List products",
        "operationId": "list-products",
        "x-zuplo-route": {
          "corsPolicy": "anything-goes",
          "handler": {
            "export": "urlForwardHandler",
            "module": "$import(@zuplo/runtime)",
            "options": {
              "baseUrl": "${env.ORIGIN_URL}"
            }
          },
          "policies": { "inbound": [] }
        },
        "responses": {
          "200": { "description": "Success" }
        }
      }
    }
  }
}

La extensión x-zuplo-route es donde Zuplo reside dentro de un archivo OpenAPI por lo demás estándar.
El handler describe lo que sucede cuando la ruta coincide; urlForwardHandler es el proxy incorporado.
La referencia ${env.ORIGIN_URL} extrae de las variables de entorno para que puedas apuntar a diferentes backends por entorno.

Establece ORIGIN_URL desde Configuración > Variables de Entorno en el portal, o editando config/.env localmente. Usa https://echo.zuplo.io si aún no tienes un origen real.

Guarda y el servidor de desarrollo local se recargará. Accede a http://localhost:9000/v1/products y deberías ver la solicitud replicada. Las puertas de enlace desplegadas responderán desde el centro de datos edge más cercano en su lugar.

Paso 3: Agrega autenticación con clave API

Las API públicas necesitan credenciales. Zuplo ofrece un servicio de claves API gestionado para que no tengas que construir un almacén de claves por tu cuenta.

Edita la ruta para agregar la política de entrada:

"policies": {
  "inbound": ["api-key-auth"]
}

Luego, agrega la definición de la política a config/policies.json (Zuplo crea este archivo la primera vez que agregas una política):

{
  "name": "api-key-auth",
  "policyType": "api-key-inbound",
  "handler": {
    "export": "ApiKeyInboundPolicy",
    "module": "$import(@zuplo/runtime)",
    "options": {
      "allowUnauthenticatedRequests": false
    }
  }
}

Ahora crea un consumidor (la entidad que posee una o más claves API):

Ve a Servicios > Servicio de Claves API en el portal.
Haz clic en "Create Consumer" (Crear Consumidor).
Establece el sujeto a un identificador estable como acme-customer-1.
Agrega el correo electrónico de quien deba gestionar la clave.
Copia la clave API generada.

Prueba con curl. Sin la cabecera, deberías ver un 401:

curl -i https://YOUR-PROJECT.zuplo.app/v1/products
# HTTP/2 401

Con la cabecera, deberías ver la respuesta original 200:

curl -i https://YOUR-PROJECT.zuplo.app/v1/products \
  -H "Authorization: Bearer YOUR_API_KEY"
# HTTP/2 200

Si prefieres manejar esto desde un cliente real, importa la especificación OpenAPI de la puerta de enlace en Apidog, establece una cabecera global para Authorization: Bearer {{api_key}}, y vincula api_key a una variable de entorno. Obtendrás una superficie de prueba limpia para cada ruta en segundos.

Paso 4: Limita la velocidad de la ruta

Nunca lances una API pública sin límites de velocidad. La política predeterminada de límite de velocidad de Zuplo te ofrece limitación por IP, por clave o por atributo personalizado.

Agrégala a la lista de entrada, después de la autenticación:

"policies": {
  "inbound": ["api-key-auth", "rate-limit-by-key"]
}

Defínela en config/policies.json:

{
  "name": "rate-limit-by-key",
  "policyType": "rate-limit-inbound",
  "handler": {
    "export": "RateLimitInboundPolicy",
    "module": "$import(@zuplo/runtime)",
    "options": {
      "rateLimitBy": "sub",
      "requestsAllowed": 60,
      "timeWindowMinutes": 1
    }
  }
}

rateLimitBy: "sub" asocia el cubo al sujeto autenticado de la política de claves API, de modo que cada cliente obtiene su propio presupuesto de 60 por minuto. Reemplaza con "ip" si quieres limitar el tráfico anónimo.

La solicitud número 61 dentro de cualquier ventana de sesenta segundos devuelve un 429 con cabeceras de reintento adjuntas. Pruébalo enviando 70 solicitudes en un bucle y observando cómo cambian los códigos de respuesta.

for i in {1..70}; do
  curl -s -o /dev/null -w "%{http_code}\n" \
    https://YOUR-PROJECT.zuplo.app/v1/products \
    -H "Authorization: Bearer YOUR_API_KEY"
done | sort | uniq -c

Deberías ver 60 líneas que indican 200 y 10 que indican 429.

Paso 5: Valida las cargas útiles de las solicitudes

Si tienes una ruta POST que acepta un cuerpo JSON, la política de validación de solicitudes detecta cargas útiles malformadas en la puerta de enlace en lugar de en tu origen. Utiliza el esquema JSON incrustado en tu operación OpenAPI, por lo que obtienes esto gratis si tu especificación es precisa.

Agrega una ruta con un cuerpo de solicitud:

"/v1/products": {
  "post": {
    "summary": "Create product",
    "operationId": "create-product",
    "requestBody": {
      "required": true,
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": ["name", "priceCents"],
            "properties": {
              "name": { "type": "string", "minLength": 1 },
              "priceCents": { "type": "integer", "minimum": 1 },
              "category": { "type": "string", "enum": ["food", "drink"] }
            }
          }
        }
      }
    },
    "x-zuplo-route": {
      "handler": { /* mismo que arriba */ },
      "policies": {
        "inbound": [
          "api-key-auth",
          "rate-limit-by-key",
          "validate-request"
        ]
      }
    }
  }
}

Agrega la política:

{
  "name": "validate-request",
  "policyType": "open-api-request-validation-inbound",
  "handler": {
    "export": "OpenApiRequestValidationInboundPolicy",
    "module": "$import(@zuplo/runtime)",
    "options": {
      "validateBody": "reject"
    }
  }
}

Ahora, una solicitud POST con un campo faltante será rechazada con un 400 antes de que llegue a tu origen. Pruébalo con Apidog guardando una solicitud de “ruta feliz”, una solicitud de “campo requerido faltante” y una solicitud de “valor de enumeración incorrecto” como ejemplos separados en el mismo grupo de solicitudes. Puedes ejecutar las tres con un solo clic.

Paso 6: Escribe una política personalizada de TypeScript

Las políticas predefinidas cubren la mayoría de las necesidades de los equipos. El objetivo de Zuplo, sin embargo, es el momento en que necesitas algo personalizado. Aquí tienes una política de salida que agrega una cabecera Cache-Control para clientes de pago y no-store para los gratuitos.

Crea modules/tiered-cache.ts:

import { ZuploRequest, ZuploContext, HttpProblems } from "@zuplo/runtime";

interface PolicyOptions {
  paidPlanHeader: string;
  paidMaxAge: number;
}

export default async function (
  response: Response,
  request: ZuploRequest,
  context: ZuploContext,
  options: PolicyOptions,
): Promise<Response> {
  const plan = request.user?.data?.plan ?? "free";

  if (plan === "free") {
    response.headers.set("Cache-Control", "no-store");
  } else {
    response.headers.set(
      "Cache-Control",
      `public, max-age=${options.paidMaxAge}`,
    );
  }

  context.log.info(`Cache header set for plan=${plan}`);
  return response;
}

Conéctala en config/policies.json:

{
  "name": "tiered-cache",
  "policyType": "custom-code-outbound",
  "handler": {
    "export": "default",
    "module": "$import(./modules/tiered-cache)",
    "options": {
      "paidPlanHeader": "x-plan",
      "paidMaxAge": 300
    }
  }
}

Y referénciala desde la ruta:

"policies": {
  "inbound": ["api-key-auth", "rate-limit-by-key"],
  "outbound": ["tiered-cache"]
}

La política personalizada es solo una función. Puedes probarla unitariamente con Vitest o Jest pasando un Response y ZuploRequest sintéticos y haciendo aserciones sobre las cabeceras, sin necesidad de un arnés de integración.

Paso 7: Despliega en el edge

El despliegue es un git push.

git add .
git commit -m "Add products gateway with auth, rate limit, and tiered cache"
git push origin feature/products-gateway

Zuplo construye un entorno de vista previa para cada rama e imprime la URL en el registro de compilación. La vista previa obtiene su propio subdominio como https://acme-gateway-feature-products-gateway-abc123.zuplo.app, con todas tus políticas activas y apuntando a cualquier ORIGIN_URL que esté configurado para ese entorno.

Prueba la URL de vista previa con Apidog configurándola como un nuevo entorno en tu proyecto. Ejecuta tu suite de pruebas completa contra ella. Si todo pasa, fusiona la rama.

git checkout main
git merge feature/products-gateway
git push origin main

La fusión dispara el despliegue a producción. En sesenta segundos, la nueva versión está activa en más de 300 ubicaciones edge. La promoción y la reversión son ambas operaciones git push; no hay una interfaz de usuario separada.

Paso 8: Genera el portal para desarrolladores

El portal se aloja en https://YOUR-PROJECT.developers.zuplo.com y se reconstruye en cada despliegue. Incluye:

Una página por ruta, con el esquema, la descripción y una consola de prueba.
Ejemplos de código en cURL, JavaScript, Python, Go y algunos otros.
Emisión de claves API de autoservicio para cualquier visitante que se registre.
Controles de marca en el portal bajo Portal para desarrolladores > Configuración.

Si tu especificación OpenAPI tiene buenas descripciones y ejemplos, el portal parecerá terminado sin más trabajo. Si tu especificación es escasa, este es el momento en que lo descubrirás.

Para personalizar, el código fuente del portal se envía como una aplicación Next.js separada que puedes bifurcar desde el repositorio del portal para desarrolladores de Zuplo en GitHub. La mayoría de los equipos se mantienen en la versión alojada.

Paso 9: Prueba todo con Apidog

Una vez que tu puerta de enlace esté activa, la disciplina que previene incidentes en producción es probar cada ruta, cada política y cada ruta de error. Apidog lo hace rápido.

El flujo de trabajo que funciona bien:

Importa la especificación OpenAPI de la puerta de enlace desde https://YOUR-PROJECT.zuplo.app/openapi. Apidog convierte cada operación en una solicitud que puedes enviar.
Crea entornos para local, preview y production, cada uno con su propia base_url y api_key.
Guarda como mínimo tres solicitudes por ruta: ruta feliz, fallo de autenticación y activación del límite de velocidad. Ejecútalas como un grupo antes de cada despliegue.
Usa los escenarios de prueba automatizados de Apidog para encadenar llamadas (crear un producto, listarlo, eliminarlo) y hacer aserciones sobre las formas de las respuestas.
Genera ejemplos de código en el lenguaje principal de tu equipo y pégalos en tus manuales de operaciones.

Si estás migrando desde Postman, la guía de prueba de API sin Postman te explica la importación. Descarga Apidog si aún no lo has hecho.

Preguntas frecuentes sobre el uso de Zuplo

¿Cómo cambio una ruta entre entornos sin modificar la especificación?

Usa variables de entorno. Define ORIGIN_URL por entorno en la Configuración del portal o en config/.env localmente, y referénciala como ${env.ORIGIN_URL} dentro de las opciones del manejador. La ruta permanece idéntica; solo la variable cambia.

¿Puedo ejecutar Zuplo sin conexión?

Sí. npm run dev inicia una puerta de enlace local en el puerto 9000 con el Diseñador de Rutas local en el 9100. Las políticas personalizadas, la validación y la limitación de velocidad funcionan todas localmente; lo único que requiere una conexión a Internet es el servicio gestionado de claves API, y puedes ejecutar npx zuplo link para usar el servicio en la nube desde tu instancia local.

¿Cómo revierto un despliegue defectuoso?

Haz git revert al commit de fusión y haz push. Zuplo redeploya el estado anterior. No hay un botón de “reversión” separado porque el historial de Git es la fuente de la verdad.

¿Qué sucede con las solicitudes en curso durante un despliegue?

Los despliegues son atómicos en el edge; las solicitudes en curso terminan en la versión antigua y las nuevas solicitudes llegan a la nueva versión. No hay ventana de inactividad.

¿Puedo usar Zuplo con gRPC o WebSockets?

Sí. El urlForwardHandler proxy las actualizaciones de WebSocket de forma transparente, y gRPC es compatible a través del manejador gRPC. REST y GraphQL son de primera clase y los casos más comunes.

¿Cómo expongo mi API de Zuplo a agentes de IA?

Agrega el Manejador del Servidor MCP a una ruta, apúntalo a tu especificación OpenAPI y elige las operaciones a exponer. Las mismas políticas de autenticación y límite de velocidad se aplican a las solicitudes MCP. La documentación del Servidor MCP de Zuplo cubre la configuración.

¿Cuánto cuesta la puerta de enlace en producción?

El nivel gratuito cubre 100K solicitudes por mes. El plan Builder agrega 1M de solicitudes por $25 al mes, y las solicitudes adicionales cuestan $100 por cada 100K. Los precios empresariales comienzan en $1,000 al mes con un contrato anual. Desglose completo en la página de precios de Zuplo.

Conclusión

Ahora tienes una puerta de enlace Zuplo funcional con autenticación de clave API, limitación de velocidad por clave, validación de solicitudes, una política de salida personalizada de TypeScript y un portal para desarrolladores, todo desplegado a través de Git al edge global. El mismo proyecto maneja entornos de vista previa, lanzamientos de producción y acceso de agentes de IA a través de MCP.

La pieza que lo mantiene estable es el ciclo de pruebas. Usa Apidog en cada vista previa antes de fusionarla, y detectarás las cabeceras de autenticación rotas, los campos de esquema faltantes y los límites de velocidad que fueron accidentalmente demasiado generosos antes de que se implementen. Descarga Apidog y conéctalo a tu puerta de enlace hoy.

¿Qué es el API Gateway de Zuplo?

Roobia — Mon, 27 Apr 2026 06:28:18 +0000

La mayoría de los gateways API todavía parecen haber sido diseñados para un equipo de operaciones de 2014. Escribes YAML, luchas con un plano de control y esperas a que alguien con acceso al clúster impulse tus cambios. Zuplo cambia ese modelo. Es un gateway API programable y nativo de la periferia (edge-native) donde tus rutas residen en un repositorio Git, tus políticas son TypeScript y cada commit se despliega en más de 300 ubicaciones globales en segundos.

Prueba Apidog hoy

Esta guía explica qué hace el gateway API de Zuplo, cómo se diferencia de Kong y AWS API Gateway, cuánto cuesta y cómo implementar tu primer gateway en menos de treinta minutos. Verás ejemplos de código para enrutamiento, autenticación y limitación de tasas, además de una sección sobre cómo probar cada endpoint con Apidog antes de que llegue a producción.

Zuplo se encuentra en una categoría que solía estar dominada por Kong, Apigee y AWS API Gateway. La propuesta es simple: los desarrolladores obtienen un lenguaje de programación real, las operaciones obtienen un servicio gestionado y el producto obtiene una capa de monetización incorporada. A continuación se detalla el flujo de trabajo real y los compromisos.

En resumen

Zuplo es un gateway API totalmente gestionado y edge-native que ejecuta tus rutas en más de 300 centros de datos de Cloudflare con latencia <50ms y sin arranques en frío.
Configuración GitOps-nativa: el gateway reside en un repositorio Git y se despliega vía CI/CD, no desde una UI.
Políticas escritas en TypeScript con soporte de IDE completo, no YAML o Lua.
El plan gratuito cubre 100K solicitudes/mes con entornos, claves API y portales ilimitados.
Funciones integradas: autenticación por clave API, JWT, OAuth2, limitación de tasas, validación de solicitudes, portal autogenerado y monetización con Stripe.
Incluye manejador de servidor MCP para exponer rutas a Claude, Codex, Cursor o cualquier cliente MCP.
Prueba cualquier ruta Zuplo de extremo a extremo con Apidog antes de pasar a producción.

¿Qué es Zuplo?

Zuplo es una plataforma de gestión de API construida sobre tres principios: código sobre configuración, edge sobre región, y Git sobre GUI. Funciona como un servicio gestionado en el edge de Cloudflare: un solo despliegue llega a más de 300 ubicaciones globales sin aprovisionamiento manual.

En lugar de usar YAML almacenado en una base de datos de control, Zuplo trata tu gateway como un proyecto TypeScript. Tienes un archivo routes.oas.json para endpoints, una carpeta de módulos TypeScript para lógica personalizada y un archivo de configuración para políticas. Haz push a GitHub: la plataforma compila, valida y despliega automáticamente.

Soporta REST, GraphQL, gRPC, WebSockets y SOAP. Cumple SOC 2 Tipo II, funciona con AWS, Azure y GCP, y ofrece opción autoalojada en Kubernetes para requisitos estrictos. El modelo de precios es por volumen de solicitudes, no por usuario. Consulta el desglose en la página de precios de Zuplo.

Por qué elegir Zuplo frente a Kong, Apigee y AWS API Gateway

Cada gateway tiene un enfoque distinto. Kong prioriza el control y requiere experiencia en Lua. Apigee es empresarial, con analíticas profundas y curva de aprendizaje alta. AWS API Gateway es natural si ya usas AWS, pero carece de portal para desarrolladores y Lambda introduce latencias de arranque en frío.

Zuplo apunta a equipos pequeños que quieren capacidades empresariales sin staff dedicado de platform engineering.

Diferencias clave:

Código, no YAML: Una política de limitación de tasas en Zuplo es TypeScript directo (3 líneas). En Kong, son ~15 líneas de YAML y plugins.
Portal para desarrolladores incluido: Zuplo genera el portal desde tu OpenAPI, incluso en el plan gratuito. En Kong y Apigee, es complejo o solo empresarial.
GitOps por defecto: Todo cambio es un pull request; tienes auditoría y git revert gratis.
Edge-native, sin arranques en frío: Zuplo se ejecuta en Cloudflare Workers; cada solicitud llega al edge más cercano y arranca en milisegundos. AWS API Gateway + Lambda añade 100-800ms de arranque en frío.

Si ya tienes Kong o Apigee y la operación está bajo control, cambiar rara vez compensa. Si partes de cero o tu gateway actual es un cuello de botella, el flujo de Zuplo es una mejora clara.

Características principales del gateway API de Zuplo

Programabilidad con TypeScript

Define el comportamiento del gateway en archivos TypeScript junto a tus rutas. Las políticas son funciones que reciben la solicitud, procesan y devuelven la solicitud o respuesta modificada. Ejemplo para eliminar una cabecera interna:

import { ZuploRequest, ZuploContext } from "@zuplo/runtime";

export default async function (
  response: Response,
  request: ZuploRequest,
  context: ZuploContext,
) {
  response.headers.delete("x-internal-trace-id");
  return response;
}

Guárdalo en modules/strip-internal-header.ts, referencia en la ruta y haz push a Git para desplegar.

Más de 60 políticas predefinidas

No necesitas programar lo básico; Zuplo ofrece políticas listas para autenticación por clave API, JWT, OAuth2, limitación de tasas, validación OpenAPI, CORS, listas blancas de IP, transformación de solicitudes, etc. Solo edita la definición de la ruta; no hay que tocar código para los casos estándar.

Portal para desarrolladores autogenerado

El portal se genera automáticamente desde tu OpenAPI: documentación, consola interactiva, ejemplos en cURL/JS/Python/Go y emisión de claves API de autoservicio. Los desarrolladores pueden probar y consumir tu API sin intervención manual.

Monetización de API integrada

Define planes (gratuito, pro, enterprise), conecta Stripe y el portal gestiona pagos, suscripciones y facturación. Kong y AWS API Gateway no incluyen monetización directa.

Manejador de servidor MCP para agentes de IA

El nuevo manejador MCP permite exponer operaciones de tu OpenAPI para ser invocadas por Claude, Codex, Cursor y clientes MCP. Aplica las mismas políticas de autenticación y rate limiting. Consulta el tutorial MCP para detalles.

Despliegue en la periferia (edge): latencia <50ms

Por defecto, cada gateway se despliega en más de 300 ubicaciones edge de Cloudflare. Esto significa baja latencia global sin configuración adicional.

Cómo funciona Zuplo por dentro

El flujo de una solicitud típica:

Coincidencia de ruta: URL y método se emparejan con tu routes.oas.json.
Políticas de entrada: Se ejecuta autenticación, validación, rate limiting, etc. Si alguna falla, se detiene el flujo y responde al cliente.
Manejador: Proxy al origen, respuesta estática, TypeScript personalizado o MCP.
Políticas de salida: Transformaciones de respuesta, eliminación de cabeceras, etc.
Respuesta: Se envía la respuesta y se registran métricas/logs.

Todo corre en un Cloudflare Worker, lo que permite latencia baja y no pagar por capacidad inactiva.

Configurando tu primer gateway Zuplo

Puedes tener un gateway funcional en media hora. Pasos prácticos:

Regístrate en zuplo.com y crea un proyecto nuevo. Usa integración con GitHub para sincronización automática.
Importa tu especificación OpenAPI. Si tienes una, impórtala y Zuplo la convierte en rutas. Si no, puedes crear rutas en la UI y exportar la spec después.
Agrega autenticación por clave API: Añade la política api-key-inbound en el editor de rutas. Zuplo maneja la base de consumidores y emisión de claves.
Agrega limitación de tasas: Incluye la política rate-limit-inbound con tu configuración (ej: 100 req/min por API key) como bloque JSON en la ruta.
Despliega: Haz push a tu rama; Zuplo construye un entorno de vista previa. Promociona a producción haciendo merge.
Prueba de extremo a extremo: Usa Apidog para enviar solicitudes a la URL del gateway con claves válidas/erróneas, cargas inválidas, etc., y verifica visualmente el orden de ejecución de políticas.

El proceso es rápido; lo más laborioso es decidir la estructura de rutas y la lógica personalizada, igual que en cualquier plataforma.

Escribiendo políticas personalizadas en TypeScript

Si necesitas lógica específica, escribe tu propia política. Ejemplo para enriquecer una solicitud con datos internos antes de llegar al backend:

import { ZuploRequest, ZuploContext } from "@zuplo/runtime";

interface UserContext {
  userId: string;
  plan: "free" | "pro" | "enterprise";
}

export default async function (
  request: ZuploRequest,
  context: ZuploContext,
): Promise<ZuploRequest | Response> {
  const apiKey = request.user?.sub;
  if (!apiKey) {
    return new Response("Unauthorized", { status: 401 });
  }

  const lookupUrl = `https://internal.example.com/users/${apiKey}`;
  const userResponse = await fetch(lookupUrl, {
    headers: { authorization: `Bearer ${context.environment.INTERNAL_TOKEN}` },
  });

  if (!userResponse.ok) {
    return new Response("User lookup failed", { status: 502 });
  }

  const user = (await userResponse.json()) as UserContext;
  request.headers.set("x-user-id", user.userId);
  request.headers.set("x-user-plan", user.plan);
  return request;
}

Puntos clave:

Es una función async estándar, fácil de testear con unit tests.
Variables de entorno via context.environment.
Devolver un Response interrumpe la pipeline (útil para errores o autenticación).

Precios de Zuplo en 2026

Tres planes claros:

Gratuito ($0/mes): 100K solicitudes/mes, entornos, claves y portales ilimitados, 1GB salida, edge global, 2 desarrolladores. Tráfico de producción real.
Builder ($25/mes): 1M solicitudes/mes, 2 dominios personalizados, 1GB por cada 100K solicitudes, $100 por 100K adicionales, soporte comunitario.
Enterprise (desde $1,000/mes anual): Solicitudes y dominios ilimitados, SLA 99.5%-99.999%, integración con GitHub Enterprise/GitLab/Azure DevOps, SSO, RBAC, soporte 24/7 opcional.

AI Gateway y Developer Portal tienen planes separados (portal open source autoalojado gratis). Ve los detalles actualizados en la página de precios.

Comparativa: AWS API Gateway cobra $3.50/millón de solicitudes REST + transferencia + Lambda; Kong Enterprise suele superar los $1,000/mes. El plan gratuito de Zuplo es difícil de superar para proyectos iniciales.

Cuándo Zuplo es la opción correcta (y cuándo no)

Usa Zuplo si:

Quieres un gateway gestionado sin operar Kong en Kubernetes.
Tu equipo domina TypeScript/JavaScript.
Necesitas portal para desarrolladores sin sistemas extra.
Vas a monetizar la API y quieres Stripe integrado.
Expondrás tu API a agentes IA y buscas soporte MCP rápido.
El tráfico es global y la latencia edge importa.

No uses Zuplo si:

Necesitas control open source total (Kong es mejor).
Usas solo infraestructura on-premise sin salida a internet.
Requieres extensiones profundas sobre NGINX.
Estás totalmente invertido en Apigee/MuleSoft y migrar no compensa.

Probando tu gateway Zuplo con Apidog

Tras desplegar tu gateway, es fundamental testear cada ruta y política antes de pasar a producción. Un cliente API dedicado facilita este proceso.

Apidog importa tu OpenAPI, la misma que usa Zuplo, y te permite:

Llamar a cada ruta con claves válidas/erróneas para validar autenticación.
Enviar payloads incorrectos para probar validación de esquema.
Bombardear endpoints para comprobar que rate limiting actúa en el umbral correcto.
Guardar variables de entorno (preview/prod URL, claves API) para alternar entornos con un clic.
Generar ejemplos de código en cURL, JS, Python, Go para tu documentación.

Puedes automatizar tests con los escenarios de Apidog, más rápido que scripts manuales. Si nunca lo usaste, la extensión de Apidog para VS Code y la guía de pruebas API sin Postman te ayudarán a empezar. Descarga Apidog y comienza a probar.

Preguntas frecuentes sobre el gateway API de Zuplo

¿Es Zuplo de código abierto?

El runtime es cerrado, pero el portal y varias libs están en GitHub. Si necesitas autoalojado, puedes combinar el portal open source y despliegue Kubernetes propio.

¿Puede Zuplo ejecutarse en mi infraestructura?

Sí, el plan Enterprise ofrece despliegue autoalojado en Kubernetes (sin edge global ni operación gestionada). Es útil para requisitos estrictos de residencia de datos.

¿Cómo se compara Zuplo con Cloudflare API Shield?

API Shield es solo seguridad (validación, detección de abuso, mTLS). Zuplo es gestión completa: enrutamiento, políticas, portal, monetización, MCP. Pueden coexistir.

¿Funciona Zuplo con mi OpenAPI existente?

Sí, OpenAPI es la fuente de verdad. Importa tu spec, las rutas y el portal se generan automáticamente; políticas de validación usan los mismos esquemas.

¿Puedo exponer Zuplo a agentes IA como Claude o Codex?

Sí, vía el manejador MCP. Apunta a tu OpenAPI, elige operaciones y tu gateway queda listo para clientes MCP; se aplican las mismas políticas.

¿Cuánto tarda un despliegue de Zuplo?

Menos de 60 segundos para entornos de vista previa. Promociones a producción son aún más rápidas (artefacto ya construido). No hay ventanas de mantenimiento; despliegues atómicos.

¿Qué sucede si Cloudflare se cae?

Zuplo depende de la red Cloudflare, así que caídas regionales pueden afectar esas zonas. El plan Enterprise ofrece failover multi-nube para 99.999% de disponibilidad.

Conclusión

Zuplo es el gateway API para equipos que buscan características empresariales sin la carga operativa. Políticas en TypeScript, despliegues GitOps, portal autogenerado, monetización integrada y soporte MCP lo convierten en una plataforma completa. El plan gratuito cubre tráfico real; el plan Enterprise escala según tus necesidades.

Evalúa Zuplo con una de tus APIs reales, pruébalo con Apidog para validar cada política y decide basado en evidencia, no en marketing. La combinación de gateway edge gestionado y cliente de pruebas potente es el camino rápido de "tenemos una API" a "tenemos un producto". Descarga Apidog y comienza a probar.

Cómo Usar DeepSeek V4 Gratis

Roobia — Fri, 24 Apr 2026 04:38:11 +0000

DeepSeek V4 se lanzó el 23 de abril de 2026 y, a diferencia de la mayoría de los modelos de vanguardia, las rutas gratuitas están disponibles desde el primer día. El chat web oficial ejecuta V4-Pro sin necesidad de tarjeta de crédito. Los pesos tienen licencia MIT y puedes descargarlos hoy mismo. Agregadores como OpenRouter y Chutes suelen ofrecer niveles gratuitos a los pocos días de cada lanzamiento de DeepSeek. En conjunto, puedes ejecutar cargas de trabajo serias en V4 sin costo antes de decidir si recargar una cuenta.

Prueba Apidog hoy mismo

Esta guía detalla cada ruta sin costo verificada, cómo elegir la adecuada para tu caso de uso y cómo configurar una colección lista para producción en Apidog para que la transición al pago sea fluida cuando escales.

Para una descripción general a nivel de producto, revisa qué es DeepSeek V4. Para un recorrido completo por la API, consulta cómo usar la API de DeepSeek V4.

En resumen

chat.deepseek.com — chat web gratuito en V4-Pro con modos Think High y Think Max. Sin tarjeta. Funciona hoy.
Pesos de Hugging Face + tu propia GPU — licencia MIT, V4-Flash funciona en 2 a 4 H100, V4-Pro necesita un clúster.
Niveles gratuitos de OpenRouter y Chutes — pasarelas de terceros que suelen abrir cuotas gratuitas en modelos DeepSeek dentro de una semana de su lanzamiento.
Proveedores de inferencia de Hugging Face — endpoint compartido y con límite de tasa para experimentación temprana con V4.
Créditos de prueba de Kaggle, Colab y RunPod — cómputo gratuito para pruebas puntuales si quieres experimentar con autoalojamiento.
Todas las rutas gratuitas limitan el uso. Para producción, pasa a la facturación de pago antes de alcanzar los topes.

Ruta 1: chat.deepseek.com (la ruta gratuita predeterminada)

La forma más rápida y estable de probar DeepSeek V4 es el chat web oficial. V4-Pro es el modelo principal; puedes alternar entre los modos Sin Pensar, Pensar Alto y Pensar Máximo desde el cuadro de redacción.

Configuración

Abre chat.deepseek.com.
Inicia sesión con correo electrónico, Google o WeChat.
Verifica que el modelo activo sea V4-Pro.
Empieza a escribir y prueba prompts.

Lo que obtienes

Contexto completo de 1M de tokens.
Carga de archivos: PDF, imágenes y paquetes de código.
Búsqueda web bajo demanda.
Tres modos de razonamiento, incluido Think Max.
Historial de conversaciones y carpetas.

Límites

DeepSeek no publica un límite estricto por día; el nivel gratuito tiene un límite suave bajo carga. Un uso intensivo puede ralentizar respuestas o poner solicitudes en cola, pero rara vez bloquea el acceso. Si ves límites de tasa persistentes, reduce el ritmo o considera la API.

Casos adecuados: comparar prompts difíciles, revisión arquitectónica de repositorios, uso de Think Max para analizar contratos complejos.

No adecuado para: automatización o flujos reproducibles.

Ruta 2: Autoalojar V4-Flash en tu propia GPU

V4-Flash es la variante con licencia MIT para autoalojamiento realista. Con 284B y 13B activos, una máquina multi-H100 lo ejecuta en FP8 con buen rendimiento; en INT4 cabe en una sola tarjeta de 80GB.

El costo es solo el hardware. Si ya tienes GPUs, es la ruta gratuita más duradera y no está sujeta a límites de tasa ni retiros.

Descargar los pesos

pip install -U "huggingface_hub[cli]"
huggingface-cli login
huggingface-cli download deepseek-ai/DeepSeek-V4-Flash \
  --local-dir ./models/deepseek-v4-flash

Aproximadamente 500GB en FP8. Asegúrate de tener espacio.

Servir con vLLM

pip install "vllm>=0.9.0"

vllm serve deepseek-ai/DeepSeek-V4-Flash \
  --tensor-parallel-size 4 \
  --max-model-len 1048576 \
  --dtype auto \
  --port 8000

Cuando esté listo, apunta cualquier cliente OpenAI a http://localhost:8000/v1. El endpoint acepta el mismo formato de solicitud que la API de DeepSeek; Apidog lo detecta como otra base URL y tus colecciones funcionan igual.

Requisitos de hardware

Variante	Tarjetas mínimas (FP8)	Tarjetas mínimas (INT4)	Rendimiento realista
V4-Flash	2 × H100 80GB	1 × H100 80GB	50 a 150 tok/s
V4-Pro	16 × H100 80GB	8 × H100 80GB	dependiente del clúster

Si no tienes GPUs disponibles, suele ser más barato la API que alquilar hardware. Esta ruta es ideal para equipos con GPUs o necesidades de cumplimiento.

Ruta 3: Nivel gratuito de OpenRouter

OpenRouter agrega modelos de pesos abiertos y privados a través de una única API. Ofrece niveles gratuitos en nuevos lanzamientos de DeepSeek, patrón visto en V3, V3.1 y V3.2.

Configuración

Regístrate en openrouter.ai.
Crea una clave API.
Busca en el catálogo deepseek/deepseek-v4-pro o deepseek/deepseek-v4-flash. Las variantes gratuitas suelen tener el sufijo :free.
Llama con el SDK OpenAI compatible.

from openai import OpenAI

client = OpenAI(
    api_key=OPENROUTER_KEY,
    base_url="https://openrouter.ai/api/v1",
)

response = client.chat.completions.create(
    model="deepseek/deepseek-v4-flash:free",
    messages=[{"role": "user", "content": "Write a Python CLI for semver bumping."}],
)

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

Límites

Niveles gratuitos limitados a cientos de solicitudes diarias por clave y menor prioridad bajo carga. Perfecto para prototipos, no fiable para producción.

Ruta 4: Proveedores de inferencia de Hugging Face

Hugging Face ofrece inferencia alojada con puntos de control V4 poco después del lanzamiento. Límites de tasa estrictos y latencia variable, pero gratuito.

from huggingface_hub import InferenceClient

client = InferenceClient(model="deepseek-ai/DeepSeek-V4-Flash")

response = client.chat_completion(
    messages=[{"role": "user", "content": "Summarize the V4 technical report in 5 bullets."}],
    max_tokens=512,
)

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

El token de HF es gratuito. Para uso intensivo, actualiza a cuenta Pro para mejores límites; aún así, el costo es mucho menor que la API oficial en cargas equivalentes.

Ruta 5: Créditos de prueba en Colab, Kaggle, RunPod y Lambda

Los principales proveedores de GPUs ofrecen créditos de prueba. Bien gestionados, permiten experimentar con V4-Flash sin costo real.

Google Colab: El nivel gratuito T4 no sirve para V4, pero Colab Pro+ ofrece 500 unidades/mes, suficiente para algunos experimentos en A100.
Kaggle: Horas de GPU semanales gratis en T4/P100. Limitado para V4-Pro, suficiente para V4-Flash cuantificado.
RunPod: $10 de crédito de prueba cubren horas en H100. Ideal para pruebas rápidas con vLLM.
Lambda: Promociones ocasionales de horas gratuitas en H100 y H200; revisa su página de registro.

No son rutas gratuitas a largo plazo, solo útiles para pruebas puntuales.

Construye una colección Apidog agnóstica al proveedor

El beneficio de tantas rutas gratuitas es poder probar el mismo prompt en todas sin duplicar trabajo. Flujo recomendado:

Descarga Apidog.
Crea una colección con cuatro entornos: chat (placeholder), deepseek (https://api.deepseek.com/v1), openrouter (https://openrouter.ai/api/v1), self-hosted (http://localhost:8000/v1).
Guarda una única solicitud POST en {{BASE_URL}}/chat/completions.
Almacena la clave de cada proveedor como variable secreta para que el cuerpo de la solicitud sea idéntico en todos los entornos.
Cambia de entorno para pruebas A/B en cada backend.

Este es el mismo patrón que la colección del nivel gratuito de GPT-5.5: una herramienta, todos los proveedores, sin duplicar trabajo.

¿Qué ruta gratuita deberías elegir?

Cuatro heurísticas para decidir:

Quiero probar rápido: Usa chat.deepseek.com.
Quiero prototipar un producto: Usa el nivel gratuito de OpenRouter y luego recarga en DeepSeek si es necesario.
Tengo GPUs y necesito cumplimiento: Autoalojar V4-Flash con vLLM.
Busco uso gratuito a largo plazo: No existe. Todos los niveles gratuitos tienen límites. Combina chat.deepseek.com para trabajo interactivo y recarga de pago para automatización.

Cuándo dejar el uso gratuito

Tres señales claras:

Te aplican límites de tasa más de una vez al día. Es momento de presupuestar.
Necesitas SLAs. Solo la API oficial los ofrece.
Necesitas logs, auditoría o cumplimiento. La API de pago entrega registros claros, los niveles gratuitos no.

Cuando ocurra cualquiera de estos casos, pasa a la API oficial. La recarga mínima es de $2 y el precio por token es el menor en el segmento.

Preguntas Frecuentes

¿Es chat.deepseek.com realmente gratuito?

Sí. Sin tarjeta, sin límite de tiempo. Límite suave bajo carga, pero no hay muro de pago.

¿Necesito cuenta de Hugging Face para descargar los pesos?

Técnicamente no; el repo es público. Prácticamente sí: una cuenta inicia mejores límites de tasa.

¿Qué ruta gratuita ejecuta el verdadero V4-Pro?

chat.deepseek.com usa V4-Pro. Los niveles gratuitos de OpenRouter suelen ser V4-Flash. Si quieres V4-Pro sin pagar, el chat web es la opción.

¿Puedo usar un nivel gratuito para un producto?

No de manera responsable. Los gratuitos tienen límites de tasa, cambian términos y pueden desaparecer. Para productos, usa la API o autoalójalo.

¿El autoalojamiento es realmente gratuito?

La licencia sí. El hardware no. Si tienes GPUs, el costo es electricidad. Si alquilas, suele ser más caro que la API.

¿Habrá un nivel gratuito de Apidog para probar?

Apidog es gratuito para diseño y pruebas de API; solo cobra créditos al usar APIs de pago. Puedes combinar un workspace gratuito de Apidog con chat.deepseek.com u OpenRouter para un flujo 100% gratuito.

Cómo Ejecutar DeepSeek V4 Localmente

Roobia — Fri, 24 Apr 2026 04:35:02 +0000

DeepSeek V4 se lanzó el 23 de abril de 2026 con pesos bajo licencia MIT en Hugging Face. Esa única elección de licencia cambia las reglas del juego para cualquier equipo que desee IA de vanguardia en su propio hardware. V4-Flash (284B total, 13B activo) cabe en un par de H100 a FP8. V4-Pro (1.6T total, 49B activo) necesita un clúster pero funciona competitivamente con GPT-5.5 y Claude Opus 4.6 en código y razonamiento.

Prueba Apidog hoy

Esta guía es un tutorial de implementación local. Cubre los requisitos de hardware, las opciones de cuantificación, las configuraciones de vLLM y SGLang, la configuración de uso de herramientas y un flujo de trabajo de prueba en Apidog que valida el servidor local antes de dirigir el tráfico de producción hacia él.

Para una descripción general del producto, consulte qué es DeepSeek V4. Para la ruta de la API alojada, consulte cómo usar la API de DeepSeek V4. Para la comparación de costos, consulte precios de la API de DeepSeek V4.

En resumen

V4-Flash se ejecuta en 2 × H100 de 80GB a FP8, o 1 × H100 a INT4. Los pesos son de ~500GB a FP8.
V4-Pro necesita más de 16 H100 a FP8 para el rendimiento de producción; no es un modelo para portátiles.
vLLM es el camino más rápido a un servidor compatible con OpenAI. vllm>=0.9.0 añade soporte para V4.
SGLang es la alternativa para equipos que desean mejores características de uso de herramientas y salida estructurada.
La cuantificación a AWQ INT4 o GPTQ INT4 permite que V4-Flash quepa en una única tarjeta de 80GB con una pérdida de calidad de ~5%.
Use Apidog para apuntar a http://localhost:8000/v1 y reutilizar la colección exacta que usa con la API alojada.

Quién debería autoalojarse

El autoalojamiento de V4 es la decisión correcta para tres tipos de equipos:

Con requisitos de cumplimiento. Sectores como salud, finanzas, legal o defensa donde los datos no pueden salir de la red. La licencia MIT de pesos abiertos elimina acuerdos de uso y flujos de datos transfronterizos.
Cargas de trabajo grandes y estables. A tasas de caché fallida, la API V4-Pro cuesta $1.74/M de entrada y $3.48/M de salida. Para cargas de trabajo de más de 200 mil millones de tokens/mes, el hardware dedicado comienza a ser más rentable.
Ajuste fino e investigación. Los checkpoints Base existen para preentrenamiento continuo y adaptación de dominio. La licencia MIT permite redistribución comercial del modelo resultante.

Quién NO debería autoalojarse: prototipadores, equipos sin experiencia en operaciones de GPU y quienes consumen menos de $200/mes en la API alojada. Los gastos operativos superan el ahorro a pequeña escala.

Requisitos de hardware

DeepSeek V4 usa precisión mixta FP4 + FP8 de forma nativa, lo que mejora el uso de memoria respecto al conteo de parámetros.

Variante	Parámetros totales	Parámetros activos	VRAM FP8	VRAM INT4	Tarjetas mínimas
V4-Flash	284B	13B	~500GB	~140GB	2 × H100 80GB (FP8) o 1 × H100 (INT4)
V4-Pro	1.6T	49B	~2.4TB	~700GB	16 × H100 80GB (FP8) o 8 × H100 (INT4)

Aclaraciones importantes:

La memoria de MoE es total, no activa. Necesita suficiente VRAM para todos los expertos.
H200 y MI300X son alternativas válidas. 141GB o 192GB por tarjeta permiten menos GPUs para el mismo modelo.
GPU de consumo no sirven. Ni V4-Flash en INT4 corre en una RTX 5090 de 24GB.
Apple Silicon: M3/M4 Max con 128GB pueden ejecutar V4-Flash (cuantificado, lento). Solo como entorno de desarrollo.

Paso 1: Descargar los pesos

Repositorios oficiales:

deepseek-ai/DeepSeek-V4-Flash
deepseek-ai/DeepSeek-V4-Pro
deepseek-ai/DeepSeek-V4-Flash-Base y DeepSeek-V4-Pro-Base para ajuste fino.

Descargue usando la CLI de Hugging Face:

pip install -U "huggingface_hub[cli]"
huggingface-cli login

huggingface-cli download deepseek-ai/DeepSeek-V4-Flash \
  --local-dir ./models/deepseek-v4-flash \
  --local-dir-use-symlinks False

Reserve ~500GB de disco para V4-Flash y varios TB para V4-Pro. ModelScope es más rápido para usuarios en China.

Paso 2: Elegir un motor de servicio

Opciones principales:

vLLM: Mejor rendimiento, interfaz OpenAI limpia, comunidad grande. Opción por defecto.
SGLang: Mejor uso de herramientas, salida estructurada, mejoras en contexto largo. Útil si depende de llamada a funciones.

Ambos soportan V4 desde versiones recientes.

Paso 3: Servir V4-Flash con vLLM

pip install "vllm>=0.9.0"

vllm serve deepseek-ai/DeepSeek-V4-Flash \
  --tensor-parallel-size 2 \
  --max-model-len 1048576 \
  --dtype auto \
  --enable-prefix-caching \
  --port 8000

Parámetros clave:

--tensor-parallel-size 2: Divide entre 2 H100. Aumente según tarjetas disponibles.
--max-model-len 1048576: Ventana de contexto completa (1M tokens). Reduzca para liberar VRAM.
--enable-prefix-caching: Acelera prompts repetidos.
--dtype auto: Usa precisión mixta FP8 de V4.

Con el servidor funcionando, cualquier cliente OpenAI apunta a http://localhost:8000/v1.

Paso 4: Servir V4-Pro con vLLM

V4-Pro requiere clúster. Solo cambia el paralelismo:

vllm serve deepseek-ai/DeepSeek-V4-Pro \
  --tensor-parallel-size 8 \
  --pipeline-parallel-size 2 \
  --max-model-len 524288 \
  --enable-prefix-caching \
  --port 8000

Contexto de 512K para ajustarse a 16 H100; aumente si tiene más VRAM. Combine pipeline y tensor parallel para multinodo.

Paso 5: Servir con SGLang (alternativa para uso de herramientas)

pip install "sglang[all]>=0.4.0"

python -m sglang.launch_server \
  --model-path deepseek-ai/DeepSeek-V4-Flash \
  --tp 2 \
  --context-length 1048576 \
  --port 30000

SGLang expone la API OpenAI en http://localhost:30000/v1. Su DSL lang facilita la llamada a funciones y salida JSON.

Paso 6: Cuantificar para una sola GPU

Cuantificación INT4 permite correr V4-Flash en una sola H100 de 80GB con pérdida de calidad mínima.

AWQ (recomendado)

pip install autoawq

python -c "
from awq import AutoAWQForCausalLM
from transformers import AutoTokenizer

model_path = './models/deepseek-v4-flash'
out_path = './models/deepseek-v4-flash-awq'
model = AutoAWQForCausalLM.from_pretrained(model_path)
tokenizer = AutoTokenizer.from_pretrained(model_path)
model.quantize(tokenizer, quant_config={'w_bit': 4, 'q_group_size': 128})
model.save_quantized(out_path)
tokenizer.save_pretrained(out_path)
"

GPTQ

pip install auto-gptq
# Siga la receta de cuantificación GPTQ; similar a AWQ.

Para servir, pase --quantization awq o --quantization gptq a vLLM.

Paso 7: Probar con Apidog

No envíe tráfico de producción sin validar el servidor local.

Descargue Apidog.
Cree una colección apuntando a http://localhost:8000/v1/chat/completions.
Pegue el mismo prompt de prueba que usa en la API alojada. Compare respuestas.
Pruebe con un contexto de 500K tokens para validar la caché KV.
Ejecute un flujo de llamada a herramientas de extremo a extremo antes de conectar un agente.

La colección de la API alojada de DeepSeek V4 funciona igual con servidor local cambiando solo la base URL.

Observabilidad y monitorización

Cuatro métricas críticas:

Tokens por segundo: Prompt y generación. vLLM expone /metrics (Prometheus).
Utilización de GPU: nvidia-smi o DCGM. Uso <70% suele indicar batch size incorrecto.
Tasa de acierto de caché KV: vLLM informa con --enable-prefix-caching.
Latencia de solicitud p50/p95/p99: Use tracing estándar; p99 alto con p50 estable implica bloqueo en la cola.

Envíe todo a Grafana o su stack de observabilidad.

Ajuste fino de los puntos de control Base de V4

Los checkpoints Base sirven para preentrenamiento continuo y SFT.

pip install "torch>=2.6" transformers accelerate peft trl

# SFT estándar con LoRA en V4-Flash-Base
python -m trl sft \
  --model_name_or_path deepseek-ai/DeepSeek-V4-Flash-Base \
  --dataset_name your-org/your-sft-set \
  --output_dir ./models/v4-flash-custom \
  --per_device_train_batch_size 1 \
  --gradient_accumulation_steps 16 \
  --learning_rate 2e-5 \
  --bf16 true \
  --use_peft true \
  --lora_r 64 \
  --lora_alpha 128

Ajuste fino completo en V4-Pro es un reto de investigación. Para la mayoría, LoRA sobre V4-Flash-Base ofrece gran mejora con bajo coste computacional.

Errores comunes

OOM al iniciar: --max-model-len demasiado alto o --tensor-parallel-size bajo. Reduzca contexto o aumente paralelismo.
Primera solicitud lenta: vLLM compila kernels de forma perezosa. Haga un warmup con una solicitud dummy.
Errores de análisis en uso de herramientas: El esquema de DeepSeek difiere de OpenAI. Use SDKs compatibles con V4.
Errores FP8 en tarjetas antiguas: A100 no soporta FP8. Use BF16 y espere el doble de VRAM.

Cuándo vale la pena el autoalojamiento

Cálculo de punto de equilibrio (basado en precios de la API alojada):

V4-Flash con 200B tokens de entrada/mes + 20B salida: ~$33.6K en API alojada vs ~$20K/mes alquilando 8 × H100. Autoalojamiento ahorra ~40%.
V4-Pro con 500B entrada + 50B salida/mes: ~$1.04M en API alojada vs ~$35K/mes en 16 × H100. Autoalojamiento ahorra más del 95%.

El punto de equilibrio de V4-Flash es ~100B tokens/mes. Por debajo, la API alojada es más barata.

Preguntas frecuentes

¿Puedo ejecutar V4-Flash en una sola A100?

Con cuantificación fuerte y contexto más corto, sí, pero lento. INT4 en A100 80GB: 5–15 tok/s. H100 es la arquitectura ideal.
¿Soporta V4 el ajuste fino con LoRA?

Sí. Use los checkpoints Base y pipelines estándar de TRL o Axolotl. MoE no modifica la matemática de LoRA.
¿El servidor local es compatible con OpenAI?

Sí. vLLM y SGLang exponen /v1/chat/completions y /v1/completions con formato OpenAI. La guía de la API alojada funciona sin cambios en localhost.
¿Cómo habilito el modo de pensamiento localmente?

Pase thinking_mode: "thinking" o "thinking_max" en la solicitud. vLLM y SGLang reenvían el flag.
¿Puedo hacer streaming desde un servidor V4 local?

Sí. Configure stream: true igual que en OpenAI o la API alojada.
¿Forma más barata de experimentar antes de comprar hardware?

Alquile una H100 en RunPod o Lambda, ejecute V4-Flash a INT4 y mida el rendimiento real. Una prueba de $10–$30 responde más rápido que una semana de planeación.

Cómo Usar la API de DeepSeek V4 Gratis

Roobia — Fri, 24 Apr 2026 04:23:07 +0000

DeepSeek V4 se lanzó el 23 de abril de 2026 con una API de bajo costo, pero existen rutas realmente gratuitas para desarrolladores que desean automatizar pruebas o prototipos sin registrar una tarjeta. Varias pasarelas agregadas ofrecen variantes :free, Hugging Face publica un endpoint de inferencia compartido, y la API oficial otorga crédito de prueba a cuentas nuevas. Si combinas estas rutas y configuras una cadena de respaldo en Apidog, puedes construir y probar productos con V4 sin gastar dinero.

Prueba Apidog hoy

Esta guía explica el uso gratuito de la API. Para opciones que incluyen chat web y autoalojamiento, revisa cómo usar DeepSeek V4 gratis. Para el tutorial de pago, consulta cómo usar la API de DeepSeek V4. Para la descripción general del producto, ve a qué es DeepSeek V4.

En resumen

Nivel gratuito de OpenRouter — deepseek/deepseek-v4-flash:free y a veces deepseek-v4-pro:free. Compatible con OpenAI, permite cientos de solicitudes al día por clave.
Proveedores de inferencia de Hugging Face — endpoint gratuito en https://router.huggingface.co/hf-inference. Útil para prototipos, con límite de velocidad.
Nivel gratuito de Chutes — red comunitaria de GPU que expone endpoints gratuitos de DeepSeek poco después del lanzamiento.
Crédito de prueba de DeepSeek — cuentas nuevas en platform.deepseek.com reciben saldo inicial.
V4-Flash autoalojado — ejecuta en tu propia GPU sin costo de licencia; consulta cómo ejecutar DeepSeek V4 localmente.
Crea una cadena de respaldo en Apidog para mantener la misma forma de solicitud en todos los proveedores.

Por qué existe la ruta gratuita de la API

Aunque DeepSeek ya tiene precios bajos, las rutas gratuitas existen por tres motivos clave:

Prototipado previo a la tarjeta: Llama a V4 desde código sin registrar un método de pago.
Trabajo estudiantil, investigación y open source: Accede a calidad de vanguardia para proyectos sin presupuesto.
Comparación de proveedores: Ejecuta el mismo prompt en varios endpoints para comparar latencia, calidad y confiabilidad.

Si alguno de estos casos aplica, sigue esta guía. Si vas a lanzar un producto, pasa a la guía de la API de pago.

Ruta 1: Nivel gratuito de OpenRouter

OpenRouter es una pasarela compatible con la API de OpenAI que agrega modelos de vanguardia, incluyendo variantes gratuitas de DeepSeek V4.

Configuración

Regístrate en openrouter.ai.
Crea una clave API en Ajustes → Claves.
Busca modelos con sufijo :free, por ejemplo deepseek/deepseek-v4-flash:free.
Llama al endpoint con cualquier SDK compatible con OpenAI.

Ejemplo en Python

from openai import OpenAI

client = OpenAI(
    api_key=OPENROUTER_API_KEY,
    base_url="https://openrouter.ai/api/v1",
)

response = client.chat.completions.create(
    model="deepseek/deepseek-v4-flash:free",
    messages=[{"role": "user", "content": "Refactoriza esta función Go para usar canales."}],
)

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

Límites

Las solicitudes gratuitas se ponen en cola tras el tráfico de pago. Los límites suelen estar entre 50 y 200 solicitudes por día por clave, con concurrencia baja. Puede ralentizarse o desactivarse sin aviso.

Ejemplo en Node.js

import OpenAI from "openai";

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

const response = await client.chat.completions.create({
  model: "deepseek/deepseek-v4-flash:free",
  messages: [{ role: "user", content: "Explica el enrutamiento de MoE como si tuviera 12 años." }],
});

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

Ruta 2: Proveedores de inferencia de Hugging Face

Hugging Face ofrece un endpoint compartido para DeepSeek V4. Es gratuito con un token de HF, pero tiene límites estrictos de velocidad.

import os
from huggingface_hub import InferenceClient

client = InferenceClient(
    model="deepseek-ai/DeepSeek-V4-Flash",
    token=os.environ["HF_TOKEN"],
)

response = client.chat_completion(
    messages=[
        {"role": "user", "content": "Escribe un decorador de Python que reintente con jitter."}
    ],
    max_tokens=512,
)

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

Obtén el token gratuito en huggingface.co/settings/tokens. La latencia y el uso dependen de la carga. Para menos límites, actualiza a HF Pro o migra a la API de DeepSeek.

Ruta 3: Chutes y pasarelas comunitarias

Chutes es una red descentralizada de GPU que frecuentemente aloja variantes de DeepSeek V4 con endpoints compatibles con OpenAI, por ejemplo https://llm.chutes.ai/v1.

client = OpenAI(
    api_key=CHUTES_API_KEY,
    base_url="https://llm.chutes.ai/v1",
)

response = client.chat.completions.create(
    model="deepseek-ai/DeepSeek-V4-Flash",
    messages=[{"role": "user", "content": "Compara la atención CSA y HCA en dos frases."}],
)

La disponibilidad y los modelos cambian rápido. Siempre valida el ID del modelo y el costo antes de depender de esta ruta.

Ruta 4: Crédito de prueba de DeepSeek

DeepSeek otorga crédito de prueba a cuentas nuevas (por ejemplo, $1 tras verificar email). Revisa tu saldo tras registrarte en platform.deepseek.com.

Incluso $1 rinde mucho: ~7 millones de tokens de entrada en V4-Flash o 570,000 en V4-Pro.

Crea una cadena gratuita agnóstica al proveedor en Apidog

Para resiliencia, configura una cadena de respaldo en Apidog y alterna entre rutas gratuitas según disponibilidad:

Descarga Apidog y crea un nuevo proyecto.
Define cuatro entornos: openrouter, huggingface, chutes, deepseek-trial.
Guarda las claves API y BASE_URL como variables en cada entorno.
Crea una solicitud POST a {{BASE_URL}}/chat/completions parametrizando model.
Cambia de entorno para reusar el mismo prompt en todos los proveedores.

Este método también sirve para rutas gratuitas de la API de GPT-5.5.

Implementa una cadena de respaldo en código

Automatiza la reserva de proveedor en Python con el SDK de OpenAI:

import os
from openai import OpenAI, RateLimitError, APIError

PROVIDERS = [
    {
        "base_url": "https://openrouter.ai/api/v1",
        "api_key": os.environ["OPENROUTER_API_KEY"],
        "model": "deepseek/deepseek-v4-flash:free",
    },
    {
        "base_url": "https://llm.chutes.ai/v1",
        "api_key": os.environ["CHUTES_API_KEY"],
        "model": "deepseek-ai/DeepSeek-V4-Flash",
    },
    {
        "base_url": "https://api.deepseek.com/v1",
        "api_key": os.environ["DEEPSEEK_API_KEY"],
        "model": "deepseek-v4-flash",
    },
]

def call_v4(messages):
    for provider in PROVIDERS:
        try:
            client = OpenAI(
                api_key=provider["api_key"],
                base_url=provider["base_url"],
            )
            return client.chat.completions.create(
                model=provider["model"],
                messages=messages,
            )
        except (RateLimitError, APIError) as e:
            print(f"{provider['base_url']} falló: {e}")
            continue
    raise RuntimeError("todos los proveedores agotados")

Para qué sirve realmente cada ruta gratuita

Ruta	Mejor para	Peor para
OpenRouter gratuito	Prototipado, desarrollo diario	Cualquier cosa con SLAs estrictos
Inferencia HF	Llamadas exploratorias, notebooks	Cargas de trabajo de baja latencia
Chutes	Trabajo comunitario experimental	Dependencias a largo plazo
Prueba de DeepSeek	Pruebas de fidelidad total	Producción sostenida
V4-Flash autoalojado	Trabajo con requisitos de cumplimiento	Equipos sin capacidad de GPU

Cálculo de cuotas que importa

Ten en cuenta los límites diarios reales de cada ruta gratuita:

OpenRouter gratuito: ~100 solicitudes/día/clave, ~50K tokens cada una. Útil para 30-50 llamadas de desarrollo por día.
Inferencia HF gratuita: límite compartido, ~1000 solicitudes/día por cuenta; puede ser lento bajo carga.
Chutes: variable; úsalo como mejor esfuerzo.
Prueba de DeepSeek ($1): ~700 llamadas de 10K tokens cada una en V4-Flash.
V4-Flash autoalojado: el límite es tu hardware (p.ej., 4 × H100 = 50-150 tok/s).

Si tu prototipo supera estos límites, la API de pago es más eficiente. A $0.14/M en V4-Flash, 10,000 llamadas con 2K de contexto y 500 de salida cuestan ~$2.80.

Cuándo pasar a la API de pago

Considera escalar cuando:

Alcanzas límites de velocidad varias veces al día.
Encadenas varios proveedores gratuitos para cubrir la carga.
Necesitas latencia predecible o SLAs.

La recarga mínima en platform.deepseek.com es de $2. Consulta la guía de precios de DeepSeek V4.

Preguntas frecuentes

¿Alguna ruta es permanentemente gratuita?

No. Los niveles gratuitos pueden cambiar o desaparecer. Úsalos solo para prototipos.

¿OpenRouter :free ejecuta el V4 real?

Sí, con límites de velocidad estrictos. La calidad es igual, el rendimiento puede variar.

¿Puedo usar la salida gratuita en un producto comercial?

Revisa los términos de cada proveedor. OpenRouter permite uso comercial dentro del límite; HF también, pero más restringido. DeepSeek sigue sus propios términos.

¿Qué ruta gratuita tiene la mejor latencia?

El crédito de prueba de DeepSeek, seguido de OpenRouter. HF y Chutes varían.

¿Puedo autoalojar V4 gratis?

Sí, la licencia es MIT. El costo es solo el hardware. Consulta cómo ejecutar DeepSeek V4 localmente.

¿Cómo rastreo qué ruta gratuita usé hoy?

Usa Apidog y activa usage en el visor de respuestas. La mayoría de agregadores también tienen panel de uso.

Precios de la API DeepSeek V4

Roobia — Fri, 24 Apr 2026 04:21:53 +0000

DeepSeek publicó los precios de V4 el mismo día que lanzó los modelos, el 23 de abril de 2026, reajustando el punto de partida para la IA de frontera. V4-Flash opera a $0.14 por millón de tokens de entrada y $0.28 por millón de tokens de salida. V4-Pro a $1.74 de entrada y $3.48 de salida. Ambos admiten ventana de contexto de 1 millón de tokens y hasta 384 mil de salida. Además, ofrecen un agresivo descuento por acierto de caché, reduciendo los costos de entrada entre 80% y 90% en solicitudes repetidas.

Prueba Apidog hoy

Esta guía explica la lista de precios completa, cómo el almacenamiento en caché de contexto modifica el costo real por llamada, una comparación técnica con GPT-5.5 y Claude Opus, y cuatro estrategias para controlar el gasto en Apidog.

Para información general del producto, revisa qué es DeepSeek V4. Para un tutorial de integración, consulta cómo usar la API de DeepSeek V4. Si buscas rutas sin costo, revisa cómo usar DeepSeek V4 gratis.

En resumen

V4-Flash: $0.14 / M entrada (sin caché), $0.028 / M entrada (con caché), $0.28 / M salida.
V4-Pro: $1.74 / M entrada (sin caché), $0.145 / M entrada (con caché), $3.48 / M salida.
Ventana de contexto: 1 millón de tokens de entrada, 384 mil tokens de salida, ambas variantes.
Descuento por acierto de caché: aprox. 80% en Flash, 92% en Pro en prefijos repetidos.
deepseek-chat y deepseek-reasoner se deprecian el 24 de julio de 2026; la facturación se asigna a V4-Flash.
Con tasas de caché fallido, V4-Pro es ~2.9 veces más barato que GPT-5.5 en entrada y ~8.6 veces más barato en salida.

La lista de precios completa

Modelo	Entrada (sin caché)	Entrada (con caché)	Salida	Contexto
`deepseek-v4-flash`	$0.14 / M	$0.028 / M	$0.28 / M	1M / 384K
`deepseek-v4-pro`	$1.74 / M	$0.145 / M	$3.48 / M	1M / 384K
`deepseek-chat` (obsoleto 24-07-2026)	se asigna a V4-Flash sin razonamiento	—	—	—
`deepseek-reasoner` (obsoleto 24-07-2026)	se asigna a V4-Flash con razonamiento	—	—	—

Puntos clave:

El precio depende solamente del ID del modelo; el modo de razonamiento solo afecta la cantidad de tokens consumidos.
El descuento por caché es automático: cualquier prefijo repetido de al menos 1,024 tokens (byte a byte) en la misma cuenta se factura al precio reducido.
Los IDs antiguos (deepseek-chat, deepseek-reasoner) ya son alias de V4-Flash; la fecha límite es el 24 de julio de 2026.

Almacenamiento en caché de contexto explicado

El almacenamiento en caché es la mayor herramienta de reducción de costos en DeepSeek V4. Todo lo que se repite entre llamadas, como prompts de sistema largos, esquemas de herramientas o contexto RAG, se factura a una fracción en las siguientes llamadas.

Ejemplo práctico:

Supón un agente con un prompt de sistema de 20,000 tokens (inalterable) y 100 preguntas de usuario de 200 tokens cada una.

Sin caché:

Entrada: 100 × 20,200 tokens × $1.74 / M = $3.52
Salida: 100 × 500 tokens × $3.48 / M = $0.17
Total: $3.69

Con caché (1 fallo inicial, 99 aciertos):

Entrada primera llamada: 20,200 × $1.74 / M = $0.035
Siguientes 99 prefijos con caché: 99 × 20,000 × $0.145 / M = $0.287
Siguientes 99 turnos de usuario sin caché: 99 × 200 × $1.74 / M = $0.034
Salida: 100 × 500 × $3.48 / M = $0.174
Total: $0.53

Resultado: ~7 veces más barato. El efecto es aún mayor en V4-Flash.

Comparativa con GPT-5.5 y Claude

La comparación relevante para equipos técnicos:

Modelo	Entrada (estándar)	Entrada (en caché)	Salida	Contexto
DeepSeek V4-Flash	$0.14 / M	$0.028 / M	$0.28 / M	1M
DeepSeek V4-Pro	$1.74 / M	$0.145 / M	$3.48 / M	1M
GPT-5.5	$5 / M	$1.25 / M	$30 / M	1M
GPT-5.5 Pro	$30 / M	—	$180 / M	1M
Claude Opus 4.6	$15 / M	$1.50 / M	$75 / M	200K

Conclusiones técnicas:

En salida, V4-Pro es ~8.6 veces más barato que GPT-5.5 y 21 veces más barato que Claude Opus 4.6.
En entrada con caché, V4-Pro es ~10 veces más barato que GPT-5.5 y Claude Opus en escenarios repetitivos.
En rendimiento, V4-Pro iguala o supera a GPT-5.5 en benchmarks de codificación (LiveCodeBench, Codeforces), costando solo una fracción. Más detalles en qué es DeepSeek V4.

Advertencia: Claude supera a V4-Pro en recuperación de contexto largo, y Gemini 3.1 Pro lidera MMLU-Pro. Si tu caso depende de recuperar información precisa en grandes contextos, evalúa la calidad antes del costo.

Modelado de costos para cargas de trabajo comunes

Cuatro patrones cubren la mayoría de los casos en producción. Así se calculan en V4-Pro (sin caché; los ahorros por caché se suman):

1. Bucle de codificación agéntico (50K de contexto, 2K de salida, 20 llamadas por tarea)

Entrada: 50,000 × 20 × $1.74 / M = $1.74
Salida: 2,000 × 20 × $3.48 / M = $0.14
Costo por tarea: ~$1.88

GPT-5.5: ~$6.20 por tarea.

2. Q&A de documentos largos (500K de contexto, 1K de salida)

Entrada: 500,000 × $1.74 / M = $0.87
Salida: 1,000 × $3.48 / M = $0.003
Costo por llamada: ~$0.87

GPT-5.5: ~$2.53 por llamada.

3. Clasificación de alto volumen (2K contexto, 200 salida, 10,000 llamadas)

Usa V4-Flash para esto.

Entrada: 2,000 × 10,000 × $0.14 / M = $2.80
Salida: 200 × 10,000 × $0.28 / M = $0.56
Costo total: ~$3.36

GPT-5.5: ~$110 ejecutando lo mismo.

4. Chatbot con indicaciones repetidas (10K prompt sistema, 500 tokens usuario, 1K salida, 1,000 sesiones)

Entrada primera llamada: 10,500 × $1.74 / M = $0.018
Entrada con caché: 999 × 10,000 × $0.145 / M = $1.45
Turnos usuario sin caché: 999 × 500 × $1.74 / M = $0.87
Salida: 1,000 × 1,000 × $3.48 / M = $3.48
Costo total: ~$5.82

GPT-5.5 con caché: ~$26.35 para la misma carga.

Costos ocultos a vigilar

El precio listado no lo es todo. Ten en cuenta:

Inflación de tokens en modo razonamiento: thinking_max puede consumir 3-10x más tokens de salida. Limita este modo con indicadores.
Crecimiento del contexto: Los agentes suelen realimentar la conversación entera en cada turno. Trunca o resume agresivamente para evitar explosión de costos.
Tormentas de reintentos: Un bug que reintenta en cada error 500 puede duplicar la factura. Implementa retroceso exponencial y límite de reintentos.
Iteraciones de desarrollo: Probar prompts con curl vuelve a ejecutar todo el contexto. Usar Apidog y variables parametrizadas reduce costos de iteración casi a cero.

Seguimiento de costos en Apidog

Flujo recomendado para controlar costos:

Descarga Apidog y almacena DEEPSEEK_API_KEY como variable secreta.
Crea una solicitud POST a https://api.deepseek.com/v1/chat/completions.
En el panel de respuesta, ancla usage.prompt_tokens, usage.completion_tokens y usage.reasoning_tokens para ver los costos en cada llamada.
Parametriza model y thinking_mode para testear entre V4-Flash y V4-Pro, y entre Non-Think y Think Max.
Replica la colección para GPT-5.5 (la guía de API de GPT-5.5 explica la configuración).

Este workflow detecta ~80% de sorpresas de costo antes de que lleguen a la factura.

Cuatro reglas para mantener el gasto predecible

Por defecto, usa V4-Flash. Solo escala a V4-Pro si la mejora de calidad lo justifica.
Por defecto, usa Non-Think. Escala a Think High para tareas difíciles y Think Max solo para tareas críticas.
Limita max_tokens. El máximo de 384K es una protección, no un objetivo. La mayoría de respuestas caben en 2K.
Envía telemetría de uso. Registra prompt_tokens, completion_tokens y reasoning_tokens. Haz alertas sobre picos de tokens de razonamiento.

Preguntas frecuentes

¿Existe un nivel gratuito?

No hay API gratuita, pero a veces se otorga crédito de prueba. Para rutas sin costo, revisa cómo usar DeepSeek V4 gratis.

¿Cómo funciona la tarificación por acierto de caché?

Prefijos de 1,024+ tokens repetidos en la misma cuenta se facturan al precio reducido. La primera llamada paga tarifa completa; posteriores con el mismo prefijo, tarifa con descuento. Es automático.

¿Los modos de razonamiento cuestan más?

El precio por token es igual, pero los modos de razonamiento consumen más tokens. Monitorea reasoning_tokens en el objeto usage.

¿Los precios son estables?

DeepSeek puede cambiar precios. V3.2 fue estable en 2025; V4 no tiene fecha de fin publicada. Consulta la página de precios en vivo antes de presupuestar.

¿V4-Pro y V4-Flash tienen la misma tarifa de salida?

No. V4-Pro salida: $3.48 / M; V4-Flash salida: $0.28 / M. Es la razón más fuerte para usar Flash por defecto.

¿El endpoint Anthropic cambia la tarifa?

No. https://api.deepseek.com/anthropic usa las mismas tarifas que el endpoint OpenAI. El formato no afecta la facturación.

Cómo usar la API DeepSeek V4

Roobia — Fri, 24 Apr 2026 04:15:03 +0000

DeepSeek V4 se lanzó con API en vivo desde el primer día. Los ID de modelo son deepseek-v4-pro y deepseek-v4-flash, el endpoint es compatible con OpenAI y la URL base es https://api.deepseek.com. Esto significa que cualquier cliente compatible con GPT-5.5 u otras APIs OpenAI puede usar V4 solo cambiando la URL base.

Prueba Apidog hoy

Esta guía cubre autenticación, parámetros clave, ejemplos en Python y Node, matemáticas en modo de pensamiento, llamadas a herramientas, streaming y un flujo de trabajo con Apidog para visualizar costos mientras iteras.

Para una descripción general de producto, revisa qué es DeepSeek V4. Para usar sin costo, consulta cómo usar DeepSeek V4 gratis.

En resumen

DeepSeek V4 expone dos endpoints: OpenAI-compatible en https://api.deepseek.com/v1/chat/completions y Anthropic-compatible en https://api.deepseek.com/anthropic.
IDs de modelo: deepseek-v4-pro (1.6T total, 49B activos) y deepseek-v4-flash (284B total, 13B activos).
Ambos soportan contexto de 1M tokens y tres modos de razonamiento: non-thinking, thinking, thinking_max.
Usa temperature=1.0, top_p=1.0 como recomienda DeepSeek; no uses defaults de GPT-5.5 o Claude.
Los IDs antiguos deepseek-chat y deepseek-reasoner se deprecian el 24 de julio de 2026; migra antes.
Descarga Apidog para reproducir solicitudes, comparar modos y mantener tu clave fuera del historial de shell.

Requisitos previos

Antes de tu primera solicitud, ten listos:

Cuenta de desarrollador DeepSeek en platform.deepseek.com y recarga de $2 mínimo (sin saldo, todas las llamadas devuelven 402 Insufficient Balance).
Clave API con alcance a proyecto (más seguro que clave general).
SDK con soporte de URL base OpenAI (Python openai>=1.30.0, Node openai@4.x funcionan sin cambios).
Cliente API que pueda repetir solicitudes fácilmente. Usa curl solo para pruebas rápidas; para iteraciones y comparación, usa Apidog.

Exporta la clave:

export DEEPSEEK_API_KEY="sk-..."

Endpoint y autenticación

Tienes dos URL base:

POST https://api.deepseek.com/v1/chat/completions # Formato OpenAI
POST https://api.deepseek.com/anthropic/v1/messages # Formato Anthropic

Elige OpenAI a menos que ya utilices Anthropic. El resto de ejemplos usa formato OpenAI.

Autenticación: token tipo Bearer en el header Authorization. Ejemplo mínimo viable:

curl https://api.deepseek.com/v1/chat/completions \
  -H "Authorization: Bearer $DEEPSEEK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-v4-pro",
    "messages": [
      {"role": "user", "content": "Explain MoE routing in two sentences."}
    ]
  }'

Respuestas exitosas devuelven un JSON con choices, usage (tokens de entrada, salida y reasoning_tokens si aplica), y id. Errores usan el formato estándar OpenAI (error.code y error.message).

Parámetros de solicitud

Cada campo impacta costo o comportamiento. Mapeo para deepseek-v4-pro y deepseek-v4-flash:

Parámetro	Tipo	Valores	Notas
`model`	string	`deepseek-v4-pro`, `deepseek-v4-flash`	Obligatorio.
`messages`	array	pares rol/contenido	Obligatorio. Mismo esquema que OpenAI.
`thinking_mode`	string	`non-thinking`, `thinking`, `thinking_max`	Default: `non-thinking`.
`temperature`	float	0 a 2	DeepSeek recomienda 1.0.
`top_p`	float	0 a 1	DeepSeek recomienda 1.0.
`max_tokens`	int	1 a 131072	Límite de salida.
`stream`	boolean	true o false	Activa streaming SSE.
`tools`	array	especificación OpenAI	Para llamada a funciones.
`tool_choice`	string/object	`auto`, `required`, `none`, o específica	Controla uso de herramientas.
`response_format`	object	`{"type": "json_object"}`	Salida JSON.
`seed`	int	cualquier int	Para reproducibilidad.
`presence_penalty`	float	-2 a 2	Penaliza temas repetidos.
`frequency_penalty`	float	-2 a 2	Penaliza tokens repetidos.

thinking_mode es la palanca de costo más relevante. non-thinking omite razonamiento y es más rápido/económico; thinking agrega razonamiento útil en código/matemáticas a cambio de más tokens; thinking_max maximiza precisión y costo (requiere contexto ≥384K).

Cliente Python

El SDK openai funciona usando base_url. Otros wrappers OpenAI (LangChain, LlamaIndex, DSPy) también funcionan.

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["DEEPSEEK_API_KEY"],
    base_url="https://api.deepseek.com/v1",
)

response = client.chat.completions.create(
    model="deepseek-v4-pro",
    messages=[
        {"role": "system", "content": "Reply in code only."},
        {"role": "user", "content": "Write a Rust function that debounces events."},
    ],
    extra_body={"thinking_mode": "thinking"},
    temperature=1.0,
    top_p=1.0,
    max_tokens=2048,
)

choice = response.choices[0]
print("Content:", choice.message.content)
print("Reasoning tokens:", response.usage.reasoning_tokens)
print("Total tokens:", response.usage.total_tokens)

Pasa parámetros específicos de DeepSeek usando extra_body sin modificar la librería.

Cliente Node

Estructura similar en Node:

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.DEEPSEEK_API_KEY,
  baseURL: "https://api.deepseek.com/v1",
});

const response = await client.chat.completions.create({
  model: "deepseek-v4-flash",
  messages: [
    { role: "user", content: "Explain the Muon optimizer in plain English." },
  ],
  thinking_mode: "thinking",
  temperature: 1.0,
  top_p: 1.0,
});

console.log(response.choices[0].message.content);
console.log("Usage:", response.usage);

El SDK Node acepta campos adicionales directamente (no requiere extra_body).

Respuestas en streaming

Activa stream: true y recorre los chunks SSE. Compatible con la forma OpenAI.

stream = client.chat.completions.create(
    model="deepseek-v4-pro",
    messages=[{"role": "user", "content": "Stream a 300-word essay on MoE."}],
    stream=True,
    extra_body={"thinking_mode": "non-thinking"},
)

for chunk in stream:
    delta = chunk.choices[0].delta.content or ""
    print(delta, end="", flush=True)

Si usas modo de pensamiento, el razonamiento llega por delta.reasoning_content. Puedes mostrarlo o ignorarlo.

Llamadas a herramientas

V4 soporta el esquema estándar OpenAI para funciones. Define funciones en tools, el modelo decide cuándo invocarlas.

tools = [{
    "type": "function",
    "function": {
        "name": "get_weather",
        "description": "Return the current weather for a city.",
        "parameters": {
            "type": "object",
            "properties": {
                "city": {"type": "string"},
                "unit": {"type": "string", "enum": ["c", "f"]},
            },
            "required": ["city"],
        },
    },
}]

response = client.chat.completions.create(
    model="deepseek-v4-pro",
    messages=[{"role": "user", "content": "¿Clima en Lagos en Celsius?"}],
    tools=tools,
    tool_choice="auto",
    extra_body={"thinking_mode": "thinking"},
)

tool_call = response.choices[0].message.tool_calls[0]
print(tool_call.function.name, tool_call.function.arguments)

Después, llama la función, añade el output como role: "tool" y reenvía a la API. El flujo es idéntico a OpenAI/Anthropic.

Modo JSON

Para salida estructurada, fuerza formato JSON:

response = client.chat.completions.create(
    model="deepseek-v4-flash",
    messages=[
        {"role": "system", "content": "Reply with a single JSON object."},
        {"role": "user", "content": "Summarize this release note as {title, date, bullets}: ..."},
    ],
    response_format={"type": "json_object"},
    extra_body={"thinking_mode": "non-thinking"},
)

Esto garantiza JSON válido, pero no esquema. Para validación estricta, usa Pydantic o Zod en cliente.

Crea la colección en Apidog

No repitas pruebas manuales en terminal; consume créditos y dificulta comparar. Hazlo así:

Descarga Apidog y crea un proyecto.
Crea un entorno con {{DEEPSEEK_API_KEY}} como variable secreta.
Guarda una solicitud POST a {{BASE_URL}}/chat/completions con header Authorization: Bearer {{DEEPSEEK_API_KEY}}.
Parametriza model y thinking_mode para pruebas A/B de variantes.
Usa el visor de respuestas para monitorear usage.reasoning_tokens y ver si pagas razonamiento extra.

Si ya tienes la colección GPT-5.5 en Apidog, duplícala, cambia la URL base a https://api.deepseek.com/v1, actualiza el modelo y compara resultados en minutos.

Manejo de errores

El formato de error es igual a OpenAI. Principales códigos:

Código	Significado	Solución
400	Solicitud incorrecta	Verifica el esquema JSON, sobre todo `messages` y `tools`.
401	Clave inválida	Regenera desde platform.deepseek.com.
402	Saldo insuficiente	Recarga la cuenta.
403	Modelo no permitido	Revisa alcance de la clave y ortografía del modelo.
422	Parámetro fuera de rango	Verifica `max_tokens` y `thinking_mode`.
429	Límite de tasa	Implementa backoff exponencial y reintenta.
500	Error del servidor	Reintenta una vez; si persiste, revisa status.
503	Sobrecarga	Pasa a V4-Flash o espera 30 segundos.

Implementa un helper de reintentos para 429 y 5xx con backoff exponencial. No reintentes errores 4xx automáticamente: indican errores de lógica.

Patrones de control de costos

Para evitar sorpresas en facturación:

Predetermina V4-Flash. Cambia a V4-Pro solo si mides mejora tangible.
Protege thinking_max con flag. Es el modo más caro; úsalo solo si la corrección es crítica.
Limita max_tokens. La mayoría de respuestas caben en 2.000 tokens. El contexto de 1M es para entrada, no salida.
Registra usage en cada llamada. Monitorea tokens de entrada, salida y razonamiento para detectar picos.

Migración desde modelos DeepSeek antiguos

IDs deepseek-chat y deepseek-reasoner se deprecian el 24/07/2026. Migra cambiando solo el ID de modelo; la forma de requests/responses no cambia.

-  model="deepseek-chat"
+  model="deepseek-v4-pro"

Antes de producción, haz comparativas A/B en Apidog. La mejora de calidad suele justificar el esfuerzo.

Preguntas frecuentes

¿La API de DeepSeek V4 está lista para producción?

Sí. La API está disponible desde el 23 de abril de 2026. V3/V3.2 ya operaban a escala, la superficie es madura.

¿Soporta formato Anthropic?

Sí. Usa https://api.deepseek.com/anthropic/v1/messages y payload Anthropic. Acceso al mismo modelo.

¿Cuál es la ventana de contexto?

1 millón de tokens en V4-Pro y V4-Flash. thinking_max recomienda mínimo 384K.

¿Cómo cuento tokens de entrada antes de enviar?

Usa tokenizador OpenAI para estimar; el recuento exacto está en usage de la respuesta. Para presupuestos, confía en el output real.

¿Puedo ajustar (fine-tune) vía API?

No por ahora. Fine-tuning solo vía checkpoints base en Hugging Face.

¿Es gratis para probar?

No hay capa gratuita, pero nuevos registros a veces reciben crédito de prueba.