feat(gpu-server): add API key auth, VRAM management, and Piper TTS voices

- Add API key authentication to all GPU services (X-API-Key header)
  - /health and /docs remain public (no key needed)
  - Shared key configured via GPU_API_KEY env variable
- Add VRAM auto-unload for mana-image-gen (5min) and mana-stt (10min)
  - FLUX.2 pipeline freed after idle, recovering ~13GB VRAM
  - WhisperX models freed after idle, recovering ~3GB VRAM
- Install Piper TTS voices (Thorsten + Kerstin) for local German TTS
- Update @manacore/shared-gpu client to support apiKey parameter
- Add GPU_API_KEY to .env.development
- Document API auth and VRAM management in setup guide

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

packages/shared-gpu/src/gpu-client.ts

@@ -28,8 +28,10 @@ export class GpuClient {
 	public readonly stt: SttClient;
 	public readonly tts: TtsClient;
 	public readonly image: ImageClient;
+	public readonly apiKey?: string;
 
 	constructor(config: GpuServiceConfig) {
+		this.apiKey = config.apiKey;
 		this.stt = new SttClient(config);
 		this.tts = new TtsClient(config);
 		this.image = new ImageClient(config);

packages/shared-gpu/src/image-client.ts

@@ -9,10 +9,12 @@ import { resolveServiceUrl } from './resolve-url';
 export class ImageClient {
 	private baseUrl: string;
 	private timeout: number;
+	private apiKey?: string;
 
 	constructor(config: GpuServiceConfig) {
 		this.baseUrl = resolveServiceUrl(config, 'image');
 		this.timeout = config.timeout ?? 120_000;
+		this.apiKey = config.apiKey;
 	}
 
 	/** Generate an image from a text prompt. */
@@ -23,7 +25,10 @@ export class ImageClient {
 		try {
 			const response = await fetch(`${this.baseUrl}/generate`, {
 				method: 'POST',
-				headers: { 'Content-Type': 'application/json' },
+				headers: {
+					'Content-Type': 'application/json',
+					...(this.apiKey ? { 'X-API-Key': this.apiKey } : {}),
+				},
 				body: JSON.stringify({
 					prompt: options.prompt,
 					width: options.width ?? 1024,

packages/shared-gpu/src/stt-client.ts

@@ -4,10 +4,12 @@ import { resolveServiceUrl } from './resolve-url';
 export class SttClient {
 	private baseUrl: string;
 	private timeout: number;
+	private apiKey?: string;
 
 	constructor(config: GpuServiceConfig) {
 		this.baseUrl = resolveServiceUrl(config, 'stt');
 		this.timeout = config.timeout ?? 60_000;
+		this.apiKey = config.apiKey;
 	}
 
 	/** Transcribe audio with optional word timestamps and speaker diarization. */
@@ -34,6 +36,7 @@ export class SttClient {
 		try {
 			const response = await fetch(`${this.baseUrl}/transcribe`, {
 				method: 'POST',
+				headers: this.apiKey ? { 'X-API-Key': this.apiKey } : {},
 				body: formData,
 				signal: controller.signal,
 			});

packages/shared-gpu/src/tts-client.ts

@@ -4,10 +4,12 @@ import { resolveServiceUrl } from './resolve-url';
 export class TtsClient {
 	private baseUrl: string;
 	private timeout: number;
+	private apiKey?: string;
 
 	constructor(config: GpuServiceConfig) {
 		this.baseUrl = resolveServiceUrl(config, 'tts');
 		this.timeout = config.timeout ?? 30_000;
+		this.apiKey = config.apiKey;
 	}
 
 	/** Synthesize speech. Returns audio as ArrayBuffer. */
@@ -23,7 +25,10 @@ export class TtsClient {
 		try {
 			const response = await fetch(`${this.baseUrl}/synthesize/auto`, {
 				method: 'POST',
-				headers: { 'Content-Type': 'application/json' },
+				headers: {
+					'Content-Type': 'application/json',
+					...(this.apiKey ? { 'X-API-Key': this.apiKey } : {}),
+				},
 				body: JSON.stringify({
 					text: options.text,
 					voice: options.voice,

packages/shared-gpu/src/types.ts

@@ -119,6 +119,8 @@ export interface GpuServiceConfig {
 		image?: string;
 		ollama?: string;
 	};
+	/** API key for authenticated access (X-API-Key header) */
+	apiKey?: string;
 	/** Request timeout in ms (default: 30000) */
 	timeout?: number;
 }