fairstack-music-generation

The saved excerpt is a snapshot from review. The external source remains the complete and most current version.

---
name: fairstack-music-generation
description: |
  Generate music via the FairStack API. AI music composition with lyrics,
  tempo/BPM, key signature, and time signature controls. Song covers, remixes,
  and editing (repaint, retake, extend). Models include Mureka and ACE-Step.
  Async by default. Trigger on: generate music, create music, AI music, compose
  song, soundtrack, background music, jingle, song cover, music generation.
---

# Music Generation

Compose original music with AI — full songs with lyrics, instrumentals, covers, and remixes. Control tempo, key, and style through a single endpoint.

**Base URL:** `https://fairstack.ai`
**Endpoint:** `POST /v1/music/generate`

---

## Authentication

```bash
export FAIRSTACK_API_KEY="fs_live_..."
```

Get your API key at [fairstack.ai/app/api-keys](https://fairstack.ai/app/api-keys).

---

## Quick Start

Music generation is **async by default** — submit and poll.

### curl

```bash
# 1. Submit music generation
curl -X POST https://fairstack.ai/v1/music/generate \
  -H "Authorization: Bearer $FAIRSTACK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Upbeat indie pop with acoustic guitar and handclaps",
    "duration_sec": 60,
    "bpm": 120,
    "key": "G major",
    "project": "podcast",
    "tags": [
      {"key": "tag", "value": "intro"},
      {"key": "tag", "value": "upbeat"},
      {"key": "tag", "value": "indie-pop"}
    ]
  }'

# Response: {"data": {"generation_id": "gen_music_123", "status": "running", ...}}

# 2. Poll for completion
curl https://fairstack.ai/v1/generations/gen_music_123 \
  -H "Authorization: Bearer $FAIRSTACK_API_KEY"
```

### CLI

```bash
fairstack generate music \
  --prompt "Upbeat indie pop with acoustic guitar and handclaps" \
  --duration 60 --bpm 120 --key "G major" \
  --project podcast \
  --tags "intro, upbeat, indie-pop"
```

### JavaScript / TypeScript

```typescript
// Submit
const submit = await fetch("https://fairstack.ai/v1/music/generate", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.FAIRSTACK_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    prompt: "Upbeat indie pop with acoustic guitar and handclaps",
    lyrics: "[Verse 1]\nWalking down the street on a sunny day\nNothing gonna stand in my way\n\n[Chorus]\nOh oh oh, feeling alive\nOh oh oh, ready to thrive",
    duration_sec: 90,
    bpm: 120,
    key: "G major",
  }),
});

const { data: job } = await submit.json();

// Poll until complete
async function pollUntilDone(id: string) {
  while (true) {
    const res = await fetch(`https://fairstack.ai/v1/generations/${id}`, {
      headers: { Authorization: `Bearer ${process.env.FAIRSTACK_API_KEY}` },
    });
    const { data } = await res.json();
    if (data.status === "succeeded") return data;
    if (data.status === "failed") throw new Error(data.error || "Failed");
    await new Promise((r) => setTimeout(r, 5000));
  }
}

const result = await pollUntilDone(job.generation_id);
console.log(result.url);      // CDN URL to audio
console.log(result.cost_usd); // e.g. 0.60
```

### Python

```python
import requests, os, time

headers = {"Authorization": f"Bearer {os.environ['FAIRSTACK_API_KEY']}"}

# Submit
resp = requests.post(
    "https://fairstack.ai/v1/music/generate",
    headers=headers,
    json={
        "prompt": "Upbeat indie pop with acoustic guitar and handclaps",
        "duration_sec": 60,
        "bpm": 120,
        "key": "G major",
    },
)
job = resp.json()["data"]

# Poll
while True:
    status = requests.get(
        f"https://fairstack.ai/v1/generations/{job['generation_id']}",
        headers=headers,
    ).json()["data"]
    if status["status"] == "succeeded":
        print(status["url"])
        break
    if status["status"] == "failed":
        raise Exception("Failed")
    time.sleep(5)
```

---

## Response

### Submit Response (202)

```json
{
  "request_id": "req_abc123",
  "data": {
    "generation_id": "gen_m