feat: add ElevenLabs Music API integration

app/api/music/compose/detailed/route.ts

@@ -0,0 +1,25 @@
+import { NextResponse } from "next/server";
+import { getCorsHeaders } from "@/lib/networking/getCorsHeaders";
+import { composeDetailedHandler } from "@/lib/elevenlabs/composeDetailedHandler";
+
+/**
+ * OPTIONS handler for CORS preflight requests.
+ *
+ * @returns A 204 response with CORS headers.
+ */
+export async function OPTIONS() {
+  return new NextResponse(null, { status: 204, headers: getCorsHeaders() });
+}
+
+/**
+ * POST /api/music/compose/detailed
+ *
+ * Generate a song with metadata and optional word timestamps.
+ * Returns multipart/mixed (JSON metadata + binary audio).
+ */
+export { composeDetailedHandler as POST };
+
+export const dynamic = "force-dynamic";
+export const fetchCache = "force-no-store";
+export const revalidate = 0;
+export const maxDuration = 120;

app/api/music/compose/route.ts

@@ -0,0 +1,25 @@
+import { NextResponse } from "next/server";
+import { getCorsHeaders } from "@/lib/networking/getCorsHeaders";
+import { composeHandler } from "@/lib/elevenlabs/composeHandler";
+
+/**
+ * OPTIONS handler for CORS preflight requests.
+ *
+ * @returns A 204 response with CORS headers.
+ */
+export async function OPTIONS() {
+  return new NextResponse(null, { status: 204, headers: getCorsHeaders() });
+}
+
+/**
+ * POST /api/music/compose
+ *
+ * Generate a song from a text prompt or composition plan using ElevenLabs Music AI.
+ * Returns binary audio. The song-id is returned in the response headers.
+ */
+export { composeHandler as POST };
+
+export const dynamic = "force-dynamic";
+export const fetchCache = "force-no-store";
+export const revalidate = 0;
+export const maxDuration = 120;

app/api/music/plan/route.ts

@@ -0,0 +1,25 @@
+import { NextResponse } from "next/server";
+import { getCorsHeaders } from "@/lib/networking/getCorsHeaders";
+import { createPlanHandler } from "@/lib/elevenlabs/createPlanHandler";
+
+/**
+ * OPTIONS handler for CORS preflight requests.
+ *
+ * @returns A 204 response with CORS headers.
+ */
+export async function OPTIONS() {
+  return new NextResponse(null, { status: 204, headers: getCorsHeaders() });
+}
+
+/**
+ * POST /api/music/plan
+ *
+ * Create a composition plan from a text prompt.
+ * Free — does not consume ElevenLabs credits.
+ * Use this before compose to preview and tweak the plan.
+ */
+export { createPlanHandler as POST };
+
+export const dynamic = "force-dynamic";
+export const fetchCache = "force-no-store";
+export const revalidate = 0;

app/api/music/stem-separation/route.ts

@@ -0,0 +1,26 @@
+import { NextResponse } from "next/server";
+import { getCorsHeaders } from "@/lib/networking/getCorsHeaders";
+import { stemSeparationHandler } from "@/lib/elevenlabs/stemSeparationHandler";
+
+/**
+ * OPTIONS handler for CORS preflight requests.
+ *
+ * @returns A 204 response with CORS headers.
+ */
+export async function OPTIONS() {
+  return new NextResponse(null, { status: 204, headers: getCorsHeaders() });
+}
+
+/**
+ * POST /api/music/stem-separation
+ *
+ * Separate an audio file into individual stems (vocals, drums, bass, etc.).
+ * Accepts multipart/form-data with one audio file.
+ * Returns a ZIP archive containing the stem files.
+ */
+export { stemSeparationHandler as POST };
+
+export const dynamic = "force-dynamic";
+export const fetchCache = "force-no-store";
+export const revalidate = 0;
+export const maxDuration = 120;

app/api/music/stream/route.ts

@@ -0,0 +1,24 @@
+import { NextResponse } from "next/server";
+import { getCorsHeaders } from "@/lib/networking/getCorsHeaders";
+import { streamHandler } from "@/lib/elevenlabs/streamHandler";
+
+/**
+ * OPTIONS handler for CORS preflight requests.
+ *
+ * @returns A 204 response with CORS headers.
+ */
+export async function OPTIONS() {
+  return new NextResponse(null, { status: 204, headers: getCorsHeaders() });
+}
+
+/**
+ * POST /api/music/stream
+ *
+ * Generate a song and stream audio chunks to the client in real time.
+ */
+export { streamHandler as POST };
+
+export const dynamic = "force-dynamic";
+export const fetchCache = "force-no-store";
+export const revalidate = 0;
+export const maxDuration = 120;

app/api/music/video-to-music/route.ts

@@ -0,0 +1,25 @@
+import { NextResponse } from "next/server";
+import { getCorsHeaders } from "@/lib/networking/getCorsHeaders";
+import { videoToMusicHandler } from "@/lib/elevenlabs/videoToMusicHandler";
+
+/**
+ * OPTIONS handler for CORS preflight requests.
+ *
+ * @returns A 204 response with CORS headers.
+ */
+export async function OPTIONS() {
+  return new NextResponse(null, { status: 204, headers: getCorsHeaders() });
+}
+
+/**
+ * POST /api/music/video-to-music
+ *
+ * Generate background music from video files.
+ * Accepts multipart/form-data with 1-10 video files (total ≤200MB).
+ */
+export { videoToMusicHandler as POST };
+
+export const dynamic = "force-dynamic";
+export const fetchCache = "force-no-store";
+export const revalidate = 0;
+export const maxDuration = 120;

lib/const.ts

@@ -32,6 +32,9 @@ export const RECOUP_ORG_ID = "04e3aba9-c130-4fb8-8b92-34e95d43e66b";
 
 export const RECOUP_API_KEY = process.env.RECOUP_API_KEY || "";
 
+/** ElevenLabs Music API base URL */
+export const ELEVENLABS_BASE_URL = "https://api.elevenlabs.io";
+
 /** Music Flamingo model inference endpoint (Modal) */
 export const FLAMINGO_GENERATE_URL =
   "https://sidney-78147--music-flamingo-musicflamingo-generate.modal.run";

lib/elevenlabs/__tests__/callElevenLabsMusic.test.ts

@@ -0,0 +1,61 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+
+vi.mock("@/lib/const", () => ({
+  ELEVENLABS_BASE_URL: "https://api.elevenlabs.io",
+}));
+
+const mockFetch = vi.fn();
+vi.stubGlobal("fetch", mockFetch);
+
+import { callElevenLabsMusic } from "../callElevenLabsMusic";
+
+describe("callElevenLabsMusic", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    vi.stubEnv("ELEVENLABS_API_KEY", "test-xi-key");
+  });
+
+  it("sends JSON body with xi-api-key header", async () => {
+    mockFetch.mockResolvedValue(new Response("audio-data", { status: 200 }));
+
+    await callElevenLabsMusic("/v1/music", { prompt: "upbeat pop" });
+
+    expect(mockFetch).toHaveBeenCalledWith(
+      "https://api.elevenlabs.io/v1/music",
+      expect.objectContaining({
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          "xi-api-key": "test-xi-key",
+        },
+        body: JSON.stringify({ prompt: "upbeat pop" }),
+      }),
+    );
+  });
+
+  it("appends output_format query param when provided", async () => {
+    mockFetch.mockResolvedValue(new Response("audio-data", { status: 200 }));
+
+    await callElevenLabsMusic("/v1/music", { prompt: "test" }, "mp3_44100_128");
+
+    const calledUrl = mockFetch.mock.calls[0][0];
+    expect(calledUrl).toContain("output_format=mp3_44100_128");
+  });
+
+  it("does not append output_format when not provided", async () => {
+    mockFetch.mockResolvedValue(new Response("audio-data", { status: 200 }));
+
+    await callElevenLabsMusic("/v1/music", { prompt: "test" });
+
+    const calledUrl = mockFetch.mock.calls[0][0];
+    expect(calledUrl).not.toContain("output_format");
+  });
+
+  it("throws when ELEVENLABS_API_KEY is missing", async () => {
+    vi.stubEnv("ELEVENLABS_API_KEY", "");
+
+    await expect(callElevenLabsMusic("/v1/music", { prompt: "test" })).rejects.toThrow(
+      "ELEVENLABS_API_KEY is not configured",
+    );
+  });
+});

lib/elevenlabs/__tests__/callElevenLabsMusicMultipart.test.ts

@@ -0,0 +1,64 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+
+vi.mock("@/lib/const", () => ({
+  ELEVENLABS_BASE_URL: "https://api.elevenlabs.io",
+}));
+
+const mockFetch = vi.fn();
+vi.stubGlobal("fetch", mockFetch);
+
+import { callElevenLabsMusicMultipart } from "../callElevenLabsMusicMultipart";
+
+describe("callElevenLabsMusicMultipart", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    vi.stubEnv("ELEVENLABS_API_KEY", "test-xi-key");
+  });
+
+  it("sends FormData with xi-api-key header", async () => {
+    mockFetch.mockResolvedValue(new Response("zip-data", { status: 200 }));
+
+    const formData = new FormData();
+    formData.append("file", new Blob(["audio"]), "test.mp3");
+
+    await callElevenLabsMusicMultipart("/v1/music/stem-separation", formData);
+
+    expect(mockFetch).toHaveBeenCalledWith(
+      "https://api.elevenlabs.io/v1/music/stem-separation",
+      expect.objectContaining({
+        method: "POST",
+        headers: { "xi-api-key": "test-xi-key" },
+        body: formData,
+      }),
+    );
+  });
+
+  it("does not set Content-Type header (lets fetch auto-set multipart boundary)", async () => {
+    mockFetch.mockResolvedValue(new Response("data", { status: 200 }));
+
+    const formData = new FormData();
+    await callElevenLabsMusicMultipart("/v1/music/stem-separation", formData);
+
+    const headers = mockFetch.mock.calls[0][1].headers;
+    expect(headers).not.toHaveProperty("Content-Type");
+  });
+
+  it("appends output_format query param when provided", async () => {
+    mockFetch.mockResolvedValue(new Response("data", { status: 200 }));
+
+    const formData = new FormData();
+    await callElevenLabsMusicMultipart("/v1/music/stem-separation", formData, "mp3_44100_128");
+
+    const calledUrl = mockFetch.mock.calls[0][0];
+    expect(calledUrl).toContain("output_format=mp3_44100_128");
+  });
+
+  it("throws when ELEVENLABS_API_KEY is missing", async () => {
+    vi.stubEnv("ELEVENLABS_API_KEY", "");
+
+    const formData = new FormData();
+    await expect(
+      callElevenLabsMusicMultipart("/v1/music/stem-separation", formData),
+    ).rejects.toThrow("ELEVENLABS_API_KEY is not configured");
+  });
+});