Ngamia Music API
Create, manage, and share music with Ngamia
Ngamia Music is a web application backed by a session-aware NestJS API. This guide documents the API implemented in the Music API service: Camel Accounts OAuth exchange, secure session cookies, model discovery, long-running track generation, and an authenticated proxy to the Ngamia platform API.
What this service does
The Music API is a NestJS application running on the Express adapter. It exchanges a short-lived OAuth authorization code for Camel Accounts credentials, uses the Camel access token to establish a Ngamia account session, and keeps Ngamia access and refresh tokens in HttpOnly cookies. Authenticated calls go from the service to the Ngamia API with a per-account bearer token. The browser never receives that Ngamia token.
The service implements seven route shapes: health, Camel sign-in exchange, session inspection, logout, model catalog, music generation, and /api/ngamia/v1/* forwarding. The upstream proxy is a bridge to another API; it does not define that API’s resource schemas.
Choose a guide
| Goal | Guide |
|---|---|
| Run the services locally | Getting started |
| Understand code exchange and token refresh | Authentication & sessions |
| Send the correct browser origin and cookies | Origins, cookies & CORS |
| Call a Music API route | API reference |
| Generate and retrieve audio | Generate a track |
| Configure production | Configuration |
Service endpoints at a glance
| Method | Path | Session | Result |
|---|---|---|---|
GET | /api/health | No | Service status JSON |
POST | /api/auth/camel | No | Exchanges OAuth code; writes cookies |
GET | /api/auth/session | Yes (if present) | Current profile, or {authenticated:false} |
POST | /api/auth/logout | Optional | Revokes upstream session when possible; clears cookies |
GET | /api/music/models | Yes | Account’s upstream model catalog |
POST | /api/music/generate | Yes | Audio bytes for a generated track |
| Any method (proxied) | /api/ngamia/v1/* | Usually | Ngamia API passthrough |
The route implementation is the source of truth. See scope and limitations for behaviors owned by the upstream Ngamia API and therefore not specified by this service.