Calling AmiVoice's Synchronous HTTP API Through a Next.js BFF — Auth, multipart Order, and the WebM Trap

📝 Originally published in Japanese on Zenn. This is the English version. Canonical: https://zenn.dev/uya0526_design/articles/satellite1_amivoice-bff 📚 This is satellite article #1 in my "Read-Aloud Speed Meter dev log" series. For the whole picture, see the main article . Where This Sits In the read-aloud speed meter app, this article covers the part that sends browser-recorded audio to the AmiVoice API to get back recognized text plus timestamps. The theme is calling an external API without exposing your API key to the browser — in other words, implementing a BFF (Backend for Frontend). The main article only touched the highlights, so here I go down to a level you can reproduce yourself. Specifically, four things: Why you must not call AmiVoice directly from the browser (why a BFF is needed) AmiVoice's synchronous HTTP auth, parameters, and multipart order Why the browser's MediaRecorder output (WebM/Opus) passes through as-is Reshaping the raw JSON with a pure-function mapper and testing it with fixtures 💡 I'm an ex-Java engineer learning TypeScript in public, so I drop in comparisons to Java here and there. Why a BFF Is Needed Using the AmiVoice API requires an API key. And that key must never appear in browser-side code. Frontend JavaScript is fully inspectable by the user, so writing the key there leaks it instantly. So I insert a relay that holds the key. [Browser] ──audio Blob──▶ [Next.js API Route (BFF / holds key)] ──▶ [AmiVoice API] record / display audio field reshape into u / d / a speech → text The browser only calls my own API Route ( /api/recognize ), and that Route attaches the key server-side and forwards to AmiVoice. The key is just read from process.env and never ends up in the bundle shipped to the browser. ☕ Java comparison: This is the same as a Spring @RestController reading an external API key from application.yml (env vars) and relaying without showing it to the client. Think "a thin Servlet that hides the secret and relays an external API."