Cómo crear una aplicación con DeepSeek API paso a paso

Última verificación documental y de código: 29 de julio de 2026. La arquitectura y los ejemplos se revisaron, pero no se desplegó la aplicación ni se ejecutó una llamada facturable. La prueba completa requiere una API key de DeepSeek con saldo y un entorno de staging.

Pasar de una demostración a una aplicación real exige bastante más que enviar un prompt. Hay que autenticar usuarios, proteger secretos, separar clientes, controlar el gasto, almacenar solo lo necesario, resistir fallos y evaluar la calidad. Esta guía propone una arquitectura de producción con Node.js y TypeScript. La misma estructura sirve para un asistente interno, un generador de contenido, una función de análisis o un producto SaaS.

DeepSeek aporta el modelo y la API de texto. Tu aplicación sigue siendo responsable de la interfaz, los permisos, los datos, las herramientas externas, la revisión humana y el cumplimiento legal. V4 es solo texto: si recibes imágenes, audio o documentos, debes extraer o transformar su contenido mediante servicios propios antes de enviar texto, respetando derechos, consentimiento y minimización.

Estado actual de la API que afecta al diseño

Elemento	Dato verificado	Decisión recomendada
Modelos	`deepseek-v4-flash` y `deepseek-v4-pro`	Usa el identificador explícito, no un alias temporal
Aliases heredados	Retirada anunciada para el 24 de julio de 2026; ya no aparecen en la lista operativa actual	Usa IDs V4 explícitos; la respuesta actual de los aliases no se probó con una clave válida
Contexto	1 millón de tokens; salida máxima de 384.000 tokens	Impón límites propios mucho menores
Concurrencia por cuenta	Flash: 2.500; Pro: 500	Cola trabajos y limita cada cliente
Modalidad V4	Solo texto	Procesa otros formatos fuera del modelo
URL base compatible con OpenAI	`https://api.deepseek.com`	Configúrala solo en el servidor

El precio por millón de tokens de entrada con acierto de caché, entrada sin acierto y salida es, respectivamente, 0,0028, 0,14 y 0,28 USD para V4 Flash; y 0,003625, 0,435 y 0,87 USD para V4 Pro. Son precios oficiales en la fecha indicada, no una promesa permanente. Consulta también nuestra página de precios de DeepSeek y la ficha de DeepSeek V4.

Arquitectura de referencia

Cliente web o móvil: recoge la petición y muestra el resultado, pero nunca contiene la clave de DeepSeek.
Backend for Frontend: autentica, valida tamaños, aplica cuotas y crea una solicitud interna.
Servicio de IA: compone instrucciones, selecciona modelo, llama a DeepSeek y valida la respuesta.
Cola y trabajadores: procesan tareas largas, reintentos y picos sin bloquear peticiones interactivas.
Datos: PostgreSQL para estado e idempotencia; almacenamiento de objetos para archivos originales si realmente son necesarios.
Puerta de herramientas: ejecuta funciones permitidas con credenciales y autorización propias.
Observabilidad: registra latencia, tokens, errores y versión del prompt sin copiar datos sensibles.

Separa el plano síncrono del asíncrono. Una respuesta corta puede viajar por HTTP o streaming. Un análisis masivo debe crear un trabajo, devolver un identificador y procesarse en segundo plano. Esta separación facilita cancelación, límites de tiempo y recuperación tras un reinicio.

1. Define el contrato antes del prompt

Escribe qué entradas acepta la función, qué salida promete, quién puede usarla y qué acciones están prohibidas. Un contrato como “recibe texto de hasta 20.000 caracteres y devuelve un resumen con riesgos y fuentes aportadas” es comprobable. “Responde cualquier cosa” no lo es. Decide también si el resultado es informativo, si requiere aprobación y cuánto tiempo se conserva.

Diseña estados visibles: pendiente, procesando, completado, rechazado por política, fallido y cancelado. No confundas un error de red con una respuesta vacía. El usuario debe saber cuándo el contenido está generado por IA y que puede contener errores, especialmente en decisiones relevantes.

2. Crea un backend mínimo y seguro

Instala Node.js 20 o posterior y crea un proyecto TypeScript. El siguiente núcleo usa el SDK de OpenAI porque la API ofrece compatibilidad. La clave se lee desde el entorno del servidor; no se incluye en el repositorio, HTML, aplicación móvil ni respuesta de una ruta.

npm install fastify openai zod
npm install -D typescript tsx @types/node

# .env local; no lo subas a Git
DEEPSEEK_API_KEY=tu_clave
DEEPSEEK_MODEL=deepseek-v4-flash

// src/ai.ts
import OpenAI from "openai";
import { z } from "zod";

const allowedModels = z.enum([
  "deepseek-v4-flash",
  "deepseek-v4-pro"
]);

const model = allowedModels.parse(
  process.env.DEEPSEEK_MODEL ?? "deepseek-v4-flash"
);

const client = new OpenAI({
  apiKey: process.env.DEEPSEEK_API_KEY,
  baseURL: "https://api.deepseek.com"
});

export async function generateSummary(text: string) {
  // Propiedad específica de DeepSeek; el spread mantiene compatible el SDK.
  const deepSeekOptions = { thinking: { type: "disabled" as const } };
  const response = await client.chat.completions.create({
    model,
    messages: [
      {
        role: "system",
        content: "Resume solo el texto recibido. Señala incertidumbres y no inventes fuentes."
      },
      { role: "user", content: text }
    ],
    max_tokens: 1200,
    ...deepSeekOptions
  });

  return {
    text: response.choices[0]?.message?.content ?? "",
    usage: response.usage
  };
}

Desactivar Thinking puede convenir para una tarea sencilla y predecible. Para un razonamiento más complejo puedes habilitarlo y evaluar reasoning_effort. En Non-Thinking puedes ajustar temperature o top_p según el comportamiento que necesites, aunque normalmente conviene modificar uno de los dos y no ambos. Cuando Thinking está habilitado, temperature y top_p se ignoran. Por separado, presence_penalty y frequency_penalty están obsoletos y no producen efecto en ningún modo. No construyas controles de interfaz que prometan modificar el comportamiento mediante parámetros que la API ignora.

3. Protege la ruta de aplicación

// src/server.ts
import Fastify from "fastify";
import { z } from "zod";
import { generateSummary } from "./ai.js";

const app = Fastify({ logger: true, bodyLimit: 30_000 });
const Input = z.object({ text: z.string().min(1).max(20_000) });

app.post("/api/summaries", async (request, reply) => {
  // Sustituye esto por autenticación real y una cuota por usuario/tenant.
  const userId = request.headers["x-demo-user"];
  if (typeof userId !== "string") {
    return reply.code(401).send({ error: "authentication_required" });
  }

  const parsed = Input.safeParse(request.body);
  if (!parsed.success) {
    return reply.code(400).send({ error: "invalid_input" });
  }

  try {
    const result = await generateSummary(parsed.data.text);
    return reply.send({ result: result.text });
  } catch (error) {
    request.log.error({ error, userId }, "deepseek_request_failed");
    return reply.code(502).send({ error: "ai_service_unavailable" });
  }
});

app.listen({ host: "0.0.0.0", port: 3000 });

La cabecera de demostración no es autenticación segura. En producción valida una sesión o JWT emitido por tu propio proveedor, comprueba organización y rol, y calcula la cuota de ese cliente. La ruta tampoco debe devolver el objeto de error del proveedor, porque puede revelar detalles internos.

4. Aísla clientes y minimiza datos

En un producto multiempresa, cada fila debe estar asociada a un tenant_id obtenido de la sesión, nunca del cuerpo enviado por el navegador. Aplica políticas de acceso en base de datos, claves de caché con espacio de nombres y almacenamiento separado cuando el riesgo lo justifique. Una fuga entre clientes es más grave que una mala respuesta del modelo.

No envíes nombres, correos, identificadores, secretos, expedientes o conversaciones completas si la tarea funciona con un fragmento anonimizado. Define una retención por campo y un proceso de borrado. Los términos de la plataforma exigen que el desarrollador informe a sus usuarios, disponga de una base legal o consentimiento cuando corresponda, permita ejercer derechos y proteja los datos. La política de privacidad de tu producto debe explicar tu flujo real, no copiar una plantilla.

5. Herramientas: el modelo propone, tu código decide

Tool calling no concede al modelo acceso automático a internet, archivos, pagos ni bases de datos. La respuesta puede incluir una solicitud estructurada; tu servidor valida nombre y argumentos, comprueba permisos, ejecuta una función permitida y devuelve el resultado al modelo. Mantén una lista cerrada de herramientas, límites de tiempo, esquemas estrictos e idempotencia.

Una consulta de lectura puede ejecutarse con credenciales de solo lectura y filtros de tenant.
Un cambio reversible puede requerir confirmación explícita.
Un pago, borrado, envío masivo o decisión de alto impacto debe pasar por revisión humana y controles independientes.
Nunca uses directamente una URL o sentencia SQL generada por el modelo.

Trata documentos, páginas y mensajes recuperados como datos no confiables. Pueden contener instrucciones maliciosas dirigidas al modelo. Delimita el contenido, recuerda en el mensaje de sistema que no es una orden y autoriza acciones según identidad y política, no según lo que diga el texto.

6. Fiabilidad: tiempos, reintentos e idempotencia

Define un tiempo máximo por petición y permite cancelar cuando el usuario abandona. Reintenta únicamente errores transitorios, con espera exponencial y aleatoria, y limita los intentos. No reintentes indefinidamente un 400 ni dupliques una operación externa. Para trabajos, guarda una clave de idempotencia única por tenant y petición.

Las cifras de concurrencia de la cuenta no sustituyen tus cuotas. Reserva capacidad para tráfico interactivo, limita el número de trabajos simultáneos y aplica contrapresión en la cola. Si el proveedor falla, devuelve un estado honesto, conserva el trabajo cuando sea seguro y permite repetirlo. Una respuesta de reserva prefabricada es mejor que presentar contenido inventado como si procediera del modelo.

7. Control de costes sin degradar a ciegas

Mide tokens de entrada y salida por función, modelo, usuario y tenant. Establece presupuestos diarios y alertas antes del límite. V4 Flash suele ser el punto inicial para gran volumen; reserva Pro para casos en los que una evaluación demuestre una mejora suficiente. No selecciones el modelo solo por precio ni envíes siempre el contexto máximo.

La caché de contexto en disco está habilitada por defecto en la plataforma, pero un acierto depende de prefijos reutilizables. Coloca instrucciones estables al principio y datos variables después, sin perjudicar claridad o privacidad. Calcula el coste con el uso realmente devuelto, porque una salida larga puede dominar la factura.

8. Observabilidad y evaluaciones

Métricas técnicas: latencia por percentil, tasa de error, cancelaciones, reintentos y profundidad de cola.
Métricas económicas: tokens, coste estimado, caché y consumo por tenant.
Métricas de calidad: exactitud con un conjunto etiquetado, tasa de abstención, formato válido y revisión humana.
Trazabilidad: modelo explícito, versión del prompt, herramienta invocada y versión del esquema.

No registres prompts completos por defecto. Usa identificadores, conteos y categorías; si necesitas muestras para depurar, aplica acceso restringido, redacción y caducidad. Crea un conjunto de evaluación con casos normales, ambiguos, adversariales, multilingües y demasiado largos. Ejecuta esas pruebas antes de cambiar modelo o prompt y durante un despliegue canario.

9. Despliegue y lista de salida

Guarda secretos en un gestor y rota cualquier clave expuesta.
Usa TLS, cabeceras seguras y reglas de salida que permitan solo destinos necesarios.
Ejecuta migraciones de base de datos de forma compatible hacia atrás.
Prueba deepseek-v4-flash o deepseek-v4-pro explícitamente y elimina los alias antes de su retirada.
Publica primero a un porcentaje pequeño, compara errores, calidad y coste, y prepara reversión.
Documenta incidentes, responsables, retención, borrado y procedimiento para solicitudes de usuarios.
Informa claramente de que la función usa IA y de sus limitaciones.

Para detalles de autenticación y parámetros consulta nuestra guía de la API. Si solo necesitas una conversación, la guía de chatbots con DeepSeek es más directa. Para sistemas de clientes y acciones empresariales, continúa con integración de DeepSeek con un CRM.

10. Modelo de datos y ciclo de vida de un trabajo

Guarda la petición como un trabajo pequeño, no como un volcado de toda la conversación. Como mínimo necesita un identificador, tenant_id, usuario, función, estado, modelo explícito, versión del prompt, fechas y clave de idempotencia. Los textos de entrada y salida deben estar en columnas separadas con retención propia, o no persistirse si la función no lo requiere.

Un trabajador reclama el trabajo con un bloqueo que caduca, incrementa el número de intento y registra el siguiente momento permitido. Si cae, otro trabajador puede recuperarlo sin duplicar una acción. Separa “fallo temporal”, “entrada rechazada”, “salida no válida” y “cancelado por el usuario”; esos estados necesitan respuestas y alertas distintas.

Usa una restricción única sobre tenant y clave de idempotencia.
No guardes la clave de API ni tokens de sesión junto al trabajo.
Conserva el uso de tokens y el código de error, no el cuerpo completo de una excepción.
Haz que el borrado de una cuenta alcance trabajos, adjuntos, índices, cachés y copias derivadas según tu política.
Prueba restauraciones; una copia de seguridad que nunca se restaura es solo una esperanza.

11. Revisión de seguridad antes de abrir al público

Revisa límites de cuerpo, tipos MIME, descompresión, URLs de importación y archivos temporales. La extracción de documentos debe ejecutarse aislada, con antivirus cuando corresponda, límites de páginas y sin acceso innecesario a la red. No permitas que una URL suministrada por el usuario alcance direcciones internas o metadatos de nube.

Comprueba autorización en cada objeto y herramienta, no solo al entrar en la aplicación. Añade protección CSRF cuando uses cookies, configura CORS para orígenes concretos y evita insertar HTML generado sin sanitización. Ejecuta análisis de dependencias, rota claves en un entorno de ensayo y simula la pérdida del proveedor. La seguridad de la aplicación no se hereda automáticamente de la seguridad del modelo.

Preguntas frecuentes

¿Puedo llamar a DeepSeek directamente desde React o una app móvil?

No con una clave secreta permanente. El paquete del navegador o móvil puede inspeccionarse. Envía la petición a tu backend, autentica allí, aplica cuotas y realiza desde allí la llamada al proveedor.

¿V4 procesa imágenes o PDF de forma nativa?

No. V4 se documenta como texto. Extrae texto con una canalización independiente, conserva referencias a páginas y valida el resultado antes de enviarlo al modelo.

¿Debo usar Flash o Pro?

Empieza con Flash y un conjunto de evaluación representativo. Usa Pro donde su calidad adicional compense el mayor coste y la menor concurrencia disponible. La decisión debe basarse en tus datos.

¿La API convierte mi aplicación en un producto oficial?

No. Debes describirla como integración independiente y no sugerir afiliación, aprobación o autorización que no exista. Revisa también los términos aplicables al nombre, dominio, logotipo y comercialización.

Cómo crear tu propia aplicación con DeepSeek