Main API Routes in the ACE-Step UI Backend: Complete Endpoint Reference

The ACE-Step UI backend exposes ten core REST endpoint groups under the /api prefix, including authentication, user profiles, song CRUD, playlists, AI music generation, and LoRA training pipelines, all implemented as Express routers in server/src/routes/.

The ACE-Step UI server is an Express application that organizes its HTTP API under the /api namespace. All route handlers live in the server/src/routes/ directory and are mounted in server/src/index.ts. This architecture provides a clean separation between the web frontend and the backend services that manage the AI music generation workflows.

Core API Endpoint Groups

The backend groups functionality into distinct routers, each handling a specific domain of the music creation platform.

Authentication (/api/auth)

The authentication router in server/src/routes/auth.ts handles user identity and session management. It provides endpoints for automatic login detection, initial user setup, and JWT token generation. The /api/auth/auto endpoint returns the first available user and a valid JWT for rapid development setups, while /api/auth/setup accepts a username to create or retrieve a user profile. According to the source code in server/src/index.ts, this router mounts at /api/auth using app.use('/api/auth', authRoutes).

User Management (/api/users)

User profiles and social features reside in server/src/routes/users.ts. This router supports public profile lookups via /api/users/:username, avatar and banner uploads through /api/users/me/avatar (using multipart/form-data), and creator following logic via /api/users/:username/follow. The /api/users/public/featured endpoint returns curated creators for the explore page, requiring no authentication via the optionalAuthMiddleware.

Song Library (/api/songs)

The song CRUD and streaming endpoints live in server/src/routes/songs.ts. Authenticated users can list their creations at /api/songs, while public tracks are available at /api/songs/public/:id. The router handles audio proxying, like toggling via /api/songs/:id/like, and metadata management including title, lyrics, style tags, BPM, key signature, and duration. Songs integrate with the storage abstraction layer defined in server/src/services/storage/factory.js for S3 or local file handling.

Playlists (/api/playlists)

Playlist management is centralized in server/src/routes/playlists.ts. Users create collections via POST to /api/playlists with JSON payloads containing name, description, and visibility flags. The router supports adding songs through /api/playlists/:id/songs and editing playlist metadata. Public discovery endpoints allow browsing of community-curated collections.

Music Generation (/api/generate)

The heart of the ACE-Step system resides in server/src/routes/generate.ts. This router interfaces with the external ACE-Step service through server/src/services/acestep.js. Key endpoints include:

• POST /api/generate – Submit music generation jobs with parameters like songDescription, instrumental flag, and duration
• GET /api/generate/status/:localJobId – Poll for completion status
• POST /api/generate/upload-audio – Upload reference audio files for conditioning
• GET /api/generate/models – List available DiT model checkpoints
• GET /api/generate/limits – Query GPU memory constraints and generation limits

The service wrapper handles Python path resolution and status synchronization with the local SQLite database.

Training and LoRA (/api/training and /api/lora)

AI model fine-tuning capabilities split across two routers. server/src/routes/training.ts manages audio dataset uploads, preprocessing via Python scripts, and LoRA training orchestration. The /api/training/checkpoints endpoint enumerates ACE-Step model checkpoints on disk, while /api/training/lora-checkpoints lists fine-tuned adaptations.

The server/src/routes/lora.ts router provides utilities for model checkpoint listing, export operations, and LoRA-specific management tasks, supporting the custom model training workflow.

Reference Tracks (/api/reference-tracks)

Reference audio management for generation conditioning lives in server/src/routes/referenceTrack.ts. These endpoints handle reference track uploads, metadata tagging, and association with generation jobs, enabling users to influence AI output style through existing audio examples.

Contact and Support (/api/contact)

The public contact form submission system exists in server/src/routes/contact.ts. The POST /api/contact endpoint accepts name, email, subject, message, and category fields, storing submissions for admin review without requiring authentication.

Route Registration in the Express Application

In server/src/index.ts, the Express application imports and mounts all routers under the /api prefix using the following pattern:

import authRoutes from './routes/auth.js';
import songsRoutes from './routes/songs.js';
import generateRoutes from './routes/generate.js';
import usersRoutes from './routes/users.js';
import playlistsRoutes from './routes/playlists.js';
import contactRoutes from './routes/contact.js';
import referenceTrackRoutes from './routes/referenceTrack.js';
import loraRoutes from './routes/lora.js';
import trainingRoutes from './routes/training.js';

app.use('/api/auth', authRoutes);
app.use('/api/songs', songsRoutes);
app.use('/api/generate', generateRoutes);
app.use('/api/users', usersRoutes);
app.use('/api/playlists', playlistsRoutes);
app.use('/api/contact', contactRoutes);
app.use('/api/reference-tracks', referenceTrackRoutes);
app.use('/api/lora', loraRoutes);
app.use('/api/training', trainingRoutes);

Additional inline routes defined directly in server/src/index.ts include /api/oembed for OpenGraph embed data, /song/:id for social media preview pages with HTML meta tags, and static asset servers mounted at /audio/*, /editor/*, and /demucs-web/* for audio files and web-based editing tools.

Authentication Middleware

All protected routes utilize JWT-based authentication middleware located in server/src/middleware/auth.ts. The system provides three middleware variants:

• authMiddleware – Requires valid JWT, returns 401 if missing
• optionalAuthMiddleware – Attaches user context if token present, allows anonymous access
• adminMiddleware – Restricts endpoints to users with administrative privileges

Routes handling public resources like /api/songs/public/:id and /api/users/public/featured typically use optionalAuthMiddleware to support both authenticated and guest browsing.

Practical API Usage Examples

Below are runnable cURL commands demonstrating key interactions with the ACE-Step UI backend. Replace localhost:3000 with your deployment host and include JWT tokens where indicated.

Authenticate and Retrieve Tokens

# Auto-login for development (returns first user + JWT)

curl http://localhost:3000/api/auth/auto

# Create or retrieve user by username

curl -X POST http://localhost:3000/api/auth/setup \
     -H "Content-Type: application/json" \
     -d '{"username":"creator1"}'

Manage User Profiles

# Fetch public profile (no authentication required)

curl http://localhost:3000/api/users/creator1

# Upload avatar (requires JWT)

curl -X POST http://localhost:3000/api/users/me/avatar \
     -H "Authorization: Bearer $JWT" \
     -F "avatar=@/path/to/image.png"

# Follow another creator

curl -X POST http://localhost:3000/api/users/creator2/follow \
     -H "Authorization: Bearer $JWT"

Song Operations

# List authenticated user's songs

curl http://localhost:3000/api/songs \
     -H "Authorization: Bearer $JWT"

# Create a new song entry manually

curl -X POST http://localhost:3000/api/songs \
     -H "Authorization: Bearer $JWT" \
     -H "Content-Type: application/json" \
     -d '{
       "title":"My AI Composition",
       "lyrics":"AI generated lyrics here",
       "style":"electronic",
       "duration":180,
       "bpm":128,
       "keyScale":"Am",
       "isPublic":true
     }'

# Like a song

curl -X POST http://localhost:3000/api/songs/12345/like \
     -H "Authorization: Bearer $JWT"

Generate Music

# Submit a generation job

curl -X POST http://localhost:3000/api/generate \
     -H "Authorization: Bearer $JWT" \
     -H "Content-Type: application/json" \
     -d '{
       "customMode":false,
       "songDescription":"upbeat jazz fusion with saxophone",
       "instrumental":true,
       "duration":120
     }'

# Check generation status

curl http://localhost:3000/api/generate/status/abc123 \
     -H "Authorization: Bearer $JWT"

# List available models

curl http://localhost:3000/api/generate/models

Playlist Management

# Create a playlist

curl -X POST http://localhost:3000/api/playlists \
     -H "Authorization: Bearer $JWT" \
     -H "Content-Type: application/json" \
     -d '{"name":"Chill Vibes","isPublic":true}'

# Add song to playlist

curl -X POST http://localhost:3000/api/playlists/9876/songs \
     -H "Authorization: Bearer $JWT" \
     -H "Content-Type: application/json" \
     -d '{"songId":"12345"}'

Submit Contact Form

curl -X POST http://localhost:3000/api/contact \
     -H "Content-Type: application/json" \
     -d '{
       "name":"Support User",
       "email":"user@example.com",
       "subject":"Feature Request",
       "message":"Please add dark mode",
       "category":"feedback"
     }'

Summary

• Ten core endpoint groups under /api handle authentication, users, songs, playlists, generation, training, LoRA, reference tracks, and contact forms, implemented as separate Express routers in server/src/routes/.
• JWT-based security uses authMiddleware, optionalAuthMiddleware, and adminMiddleware from server/src/middleware/auth.ts to protect routes while allowing public browsing of shared content.
• Route mounting occurs centrally in server/src/index.ts, which also defines inline routes for oEmbed data, social previews, and static asset serving.
• Music generation (/api/generate) serves as the primary integration point with the ACE-Step inference engine, handling job submission, status polling, and model configuration.
• Training pipeline (/api/training and /api/lora) provides complete workflows for dataset preparation and custom model fine-tuning through REST endpoints.

Frequently Asked Questions

What is the base URL prefix for all API endpoints in ACE-Step UI?

All REST endpoints use the /api prefix. For example, authentication routes are accessed at /api/auth/*, song operations at /api/songs/*, and generation endpoints at /api/generate/*. This prefix is applied in server/src/index.ts where each router mounts under /api followed by its specific path segment.

Which endpoints require authentication versus allowing anonymous access?

Endpoints under /api/auth, /api/users/me/, /api/songs (private listing), /api/playlists (creation), and /api/generate require valid JWT tokens via authMiddleware. However, public resources like /api/songs/public/:id, /api/users/public/featured, /api/users/:username (profiles), and /api/contact use optionalAuthMiddleware, allowing anonymous access while still recognizing logged-in users when tokens are present.

How does the music generation endpoint interact with the AI backend?

The /api/generate routes in server/src/routes/generate.ts act as a proxy to the external ACE-Step service defined in server/src/services/acestep.js. When a client POSTs to /api/generate, the server creates a database entry, forwards the request to the Python-based ACE-Step inference engine, and returns a localJobId. Clients poll /api/generate/status/:localJobId to track progress; upon completion, the system creates a permanent songs database record with the generated audio URL.

Where are static assets and embedded previews served from?

Static audio files, the AudioMass editor, and Demucs web UI are served from /audio/*, /editor/*, and /demucs-web/* respectively, configured in server/src/index.ts. Social media embeds use the /song/:id route (returning HTML with OpenGraph meta tags) and /api/oembed (returning JSON embed data), both defined inline in the main Express application file rather than in the separate route modules.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}