Saltar al contenido principal
Ejecuta una pequeña aplicación de chat con Next.js cuyo código del navegador solo habla con tus propias rutas de servidor, de modo que tu clave de API de Phaseo nunca llega al navegador. Al terminar tendrás una página de chat local con un selector de modelos que se rellena desde GET /v1/models y respuestas de POST /v1/responses. El ejemplo es ilustrativo: sus rutas no tienen inicio de sesión ni límite de solicitudes, así que cualquiera que pueda acceder a ellas gasta tu clave. Añade primero las comprobaciones de Antes de desplegarla. Para que un agente de programación cree la misma aplicación desde cero, pega este prompt:

Crea una aplicación de chat web con Next.js sobre Phaseo Gateway.

Abrir en Cursor

Cómo está construido el ejemplo

El ejemplo está en examples/web-chat-nextjs:

Ejecútalo

Necesitas Node.js y una clave de API de Phaseo.
1

Instala

El ejemplo incluye un package-lock.json, así que npm instala las versiones probadas.
2

Crea .env.local

El ejemplo no tiene .env.example. Crea .env.local tú mismo:
.env.local
Aquí NEXT_PUBLIC_GATEWAY_URL solo se lee en el servidor, pero el prefijo NEXT_PUBLIC_ la expondría al código del navegador, así que nunca pongas una clave en ella. Atribución de aplicaciones explica las dos cabeceras opcionales.
3

Corrige el segundo turno del chat

ChatClient.tsx envía el id de la respuesta anterior como previous_response_id. El Gateway no guarda respuestas, así que rechaza ese campo con 400 validation_error (palabra clave unsupported_param) y el segundo mensaje falla. En app/api/responses/route.ts, elimina el bloque que copia previous_response_id en el payload:
app/api/responses/route.ts
Así cada turno se responde por separado. Para conservar el contexto, envía los turnos anteriores como un array de mensajes en input.
4

Inicia el servidor de desarrollo

Abre http://localhost:3000.

Comprueba que funciona

  • El selector de modelos se rellena con ID de modelo.
  • Dos mensajes seguidos reciben cada uno una respuesta.
  • En el panel de red del navegador, las solicitudes van solo a /api/models y /api/responses, y ninguna lleva PHASEO_API_KEY.
  • Un ID de modelo incorrecto muestra el mensaje de error del Gateway en lugar de una respuesta en blanco.
  • Las solicitudes aparecen en Ajustes → Uso → Registros con el título de aplicación que configuraste.

Antes de desplegarla

  • Autentica las rutas. Exige un usuario con sesión iniciada en /api/responses y /api/models, o usa el banco de trabajo OAuth para que cada usuario gaste sus propios créditos.
  • Limita los modelos a una lista permitida. La ruta reenvía cualquier cadena model que llegue del navegador. Compruébala en el servidor contra una lista fija.
  • Limita la entrada y la frecuencia. Limita la longitud de la entrada y las solicitudes por usuario, y fija un límite de gasto en la clave.
  • Usa streaming si lo necesitas. Pon stream: true y reenvía los eventos; Streaming muestra qué evento termina un stream de Responses.
Para un script de backend en lugar de una interfaz, empieza por la aplicación de prueba REST con Node o la CLI del gateway en Python.
Última modificación el 5 de noviembre de 2026