> ## Documentation Index
> Fetch the complete documentation index at: https://docs.audiopod.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# AudioMusic V2

> Generate original music, instrumentals, covers, and audio transformations using AudioPod AI's AudioMusic V2 engine.

## Overview

AudioPod AI's **AudioMusic V2** is a state-of-the-art music generation engine that transforms text descriptions into original musical compositions. Powered by a Transformer Model with Chain-of-Thought reasoning, AudioMusic V2 delivers studio-quality results.

### Key Capabilities

* **Text-to-Music**: Generate complete songs with vocals from prompts and lyrics
* **Simple Mode**: Describe what you want in natural language — AudioMusic V2 handles everything
* **Cover / Style Transfer**: Transform existing audio into different styles and genres
* **Reference Audio**: Guide generation using a reference track's timbre and mixing style
* **Audio Analysis**: Extract metadata (BPM, key, lyrics, caption) from any audio
* **Stem Extraction**: Isolate specific instruments (vocals, drums, bass, guitar, and more)
* **Repaint / Edit / Extend**: Modify specific sections, edit with new prompts, or extend tracks
* **Batch Generation**: Generate 1-8 variations in a single request
* **LRC Timestamps**: Synchronized lyric timestamps for karaoke-style playback
* **Quality Scoring**: Automatic quality assessment for every generation
* **50+ Languages**: Generate music with vocals in over 50 languages
* **Multiple Formats**: Output in WAV, MP3, FLAC, or OGG
* **Royalty-Free**: All generated music is 100% royalty-free for commercial use

## Authentication

All music endpoints require authentication. Use one of these methods:

* **API Key (Recommended)**: `X-API-Key: your_api_key` header
* **JWT Token**: `Authorization: Bearer your_jwt_token` (for session-based auth)

```bash theme={null}
# Example with API Key
curl -X POST "https://api.audiopod.ai/api/v1/music/simple" \
  -H "X-API-Key: $AUDIOPOD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "upbeat pop song with catchy melody"}'
```

## Quick Start — Simple Mode

The fastest way to generate music. Just describe what you want:

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    from audiopod import AudioPod

    client = AudioPod(api_key="ap_your_api_key")

    # Simple mode — AudioMusic V2 auto-generates everything
    job = client.music.simple(
        query="a soft Bengali love song for a quiet evening",
        wait_for_completion=True
    )
    print(f"Music URL: {job['output_url']}")
    ```
  </Tab>

  <Tab title="Node.js">
    ```typescript theme={null}
    import AudioPod from 'audiopod';

    const client = new AudioPod({ apiKey: 'ap_your_api_key' });

    // Simple mode — AudioMusic V2 auto-generates everything
    const job = await client.music.simple({
      query: 'a soft Bengali love song for a quiet evening',
    });
    const completed = await client.music.waitForCompletion(job.id);
    console.log(`Music URL: ${completed.output_url}`);
    ```
  </Tab>

  <Tab title="cURL">
    ```bash theme={null}
    # Create job
    JOB=$(curl -s -X POST "https://api.audiopod.ai/api/v1/music/simple" \
      -H "X-API-Key: $AUDIOPOD_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{"query": "a soft Bengali love song for a quiet evening"}')

    JOB_ID=$(echo $JOB | jq -r '.job.id')
    echo "Job created: $JOB_ID"

    # Poll for completion
    while true; do
      STATUS=$(curl -s "https://api.audiopod.ai/api/v1/music/jobs/$JOB_ID/status" \
        -H "X-API-Key: $AUDIOPOD_API_KEY")
      STATE=$(echo $STATUS | jq -r '.status')
      echo "Status: $STATE"
      [ "$STATE" = "COMPLETED" ] && echo "URL: $(echo $STATUS | jq -r '.output_url')" && break
      [ "$STATE" = "FAILED" ] && echo "Failed" && break
      sleep 5
    done
    ```
  </Tab>
</Tabs>

## Complete Parameters Reference

All music generation endpoints inherit from a common base. Here are all available parameters:

### Core Parameters

| Parameter | Type | Default | Description |
| - | - | - | - |
| `duration` | float | -1.0 | Audio duration in seconds. Use -1 for automatic duration based on lyrics length. Max: 600 |
| `format` | string | `"flac"` | Output audio format: `wav`, `mp3`, `flac`, `ogg` |
| `model_version` | string | `"audiomusic-v2"` | Model version: `audiomusic-v2` (recommended) or `audiomusic-v1.5` |
| `batch_size` | int | 1 | Number of variations to generate (1-8) |
| `seed` | int | -1 | Random seed for reproducibility. Use -1 for random |

### Diffusion Parameters

| Parameter | Type | Default | Description |
| - | - | - | - |
| `inference_steps` | int | 64 | Number of diffusion steps. Higher = better quality, slower. Range: 32-100 |
| `guidance_scale` | float | 7.0 | Classifier-free guidance scale. Higher = more prompt adherence. Range: 1.0-15.0 |
| `shift` | float | 3.0 | Timestep shift factor. Range: 1.0-5.0 |
| `infer_method` | string | `"ode"` | Inference method: `ode` (Euler, faster) or `sde` (stochastic, more diverse) |
| `use_adg` | bool | false | Enable Adaptive Dual Guidance for enhanced control |
| `cfg_interval_start` | float | 0.0 | CFG interval start ratio (0.0-1.0) |
| `cfg_interval_end` | float | 1.0 | CFG interval end ratio (0.0-1.0) |

### Language Model Parameters

AudioMusic V2 includes a language model that can auto-generate and refine metadata, captions, lyrics, and more.

| Parameter | Type | Default | Description |
| - | - | - | - |
| `thinking` | bool | true | Enable Chain-of-Thought reasoning for higher quality |
| `lm_temperature` | float | 0.85 | Sampling temperature (0.0-2.0). Lower = more deterministic |
| `lm_cfg_scale` | float | 2.0 | LM classifier-free guidance (0.0-10.0) |
| `lm_top_k` | int | 0 | Top-k sampling (0-100, 0 disables) |
| `lm_top_p` | float | 0.9 | Nucleus sampling threshold (0.0-1.0) |
| `lm_negative_prompt` | string | `"NO USER INPUT"` | Negative prompt for LM guidance |
| `use_cot_metas` | bool | true | Auto-generate BPM, key, time signature via Chain-of-Thought |
| `use_cot_caption` | bool | true | Refine caption/tags via Chain-of-Thought |
| `use_cot_lyrics` | bool | false | Generate or refine lyrics via Chain-of-Thought |
| `use_cot_language` | bool | true | Auto-detect vocal language via Chain-of-Thought |
| `use_constrained_decoding` | bool | false | Enable structured LM output |

### Music Metadata Parameters

These are auto-detected when `thinking: true`, but can be specified manually.

| Parameter | Type | Default | Description |
| - | - | - | - |
| `bpm` | int | null | Beats per minute (30-300). Auto-detected if null |
| `keyscale` | string | null | Musical key, e.g. `"C Major"`, `"Am"`. Auto-detected if null |
| `timesignature` | string | null | Time signature: `"2/4"`, `"3/4"`, `"4/4"`, `"6/8"`. Auto-detected if null |
| `vocal_language` | string | `"unknown"` | ISO 639-1 language code (e.g. `"en"`, `"zh"`, `"ja"`). Use `"unknown"` for auto-detection |

### Output & Quality Parameters

| Parameter | Type | Default | Description |
| - | - | - | - |
| `generate_lrc` | bool | false | Generate synchronized LRC lyric timestamps |
| `calculate_quality` | bool | true | Calculate quality score (0.0-1.0) for the output |
| `thumbnail_url` | string | null | URL for custom track thumbnail image |

### LoRA Parameters

| Parameter | Type | Default | Description |
| - | - | - | - |
| `lora_name_or_path` | string | null | Path to LoRA adapter for fine-tuned styles |
| `lora_weight` | float | 1.0 | LoRA adapter weight (-3.0 to 3.0) |

## Genre Presets

Pre-configured genre settings for quick generation:

| Preset | Description |
| - | - |
| `Modern Pop` | Contemporary pop with electronic elements |
| `Rock` | Guitar-driven rock music |
| `Hip Hop` | Modern hip hop beats and production |
| `Jazz` | Jazz compositions with improvisation |
| `Classical` | Orchestral and classical arrangements |
| `Electronic` | EDM, synth-driven electronic music |
| `Country` | Country music with acoustic instruments |
| `Folk` | Folk music with traditional elements |
| `Blues` | Blues with soulful expression |
| `Reggae` | Reggae with Caribbean rhythms |
| `Latin` | Latin music styles |
| `R&B` | Rhythm and blues |
| `Metal` | Heavy metal and rock subgenres |
| `Custom` | Custom genre (specify in caption/prompt) |

## Output Formats

| Format | Extension | Quality | Use Case |
| - | - | - | - |
| FLAC | `.flac` | Lossless | Default. Best quality, larger files |
| WAV | `.wav` | Lossless | Uncompressed, maximum compatibility |
| MP3 | `.mp3` | Lossy | Smaller files, streaming |
| OGG | `.ogg` | Lossy | Open format, good compression |

## Job Lifecycle

All music generation is asynchronous:

1. **Submit** a generation request → receive a job with `status: "PENDING"`
2. **Poll** the job status endpoint → `"PROCESSING"` while generating
3. **Complete** → `status: "COMPLETED"` with `output_url` and `output_urls` (multiple formats)
4. **Failed** → `status: "FAILED"` with `error_message` (use retry endpoint to re-queue)

## Pricing

Music generation is billed per minute of audio generated. Two billing paths
apply depending on how you authenticate:

| Path | Rate |
| - | - |
| Account credits (subscription / JWT) | **990 credits/minute** |
| API wallet (API key, USD-denominated) | **\$0.04/minute** |

| Duration | Credits | API wallet (USD) |
| - | - | - |
| 30 seconds | 495 | \$0.02 |
| 1 minute | 990 | \$0.04 |
| 2 minutes | 1,980 | \$0.08 |
| 5 minutes | 4,950 | \$0.20 |
| 10 minutes | 9,900 | \$0.40 |

<Note>
  **AudioMusic Premium** (`quality: "premium"`) is a higher-fidelity variant
  that bills at **2× the base rate** — 1,980 credits/minute or \$0.08/minute.
  Requires a Pro-tier or higher subscription; calls from Free/Basic tiers return
  `402 PREMIUM_TIER_REQUIRED`.
</Note>

Credits are reserved when the job is created and refunded if generation fails.

## Best Practices

1. **Use Simple Mode for quick results** — describe what you want in natural language and let AudioMusic V2 handle the details
2. **Enable `thinking: true`** (default) for best quality — Chain-of-Thought reasoning significantly improves output
3. **Use `caption` over `prompt`** — AudioMusic V2 uses `caption` internally; `prompt` is a legacy alias
4. **Set `inference_steps: 64`** for production quality. Use 32 for fast drafts, 8 for turbo previews
5. **Default `guidance_scale: 7.0`** works well for most cases. Increase to 10-15 for stronger prompt adherence
6. **Use structure tags in lyrics** — `[verse]`, `[chorus]`, `[bridge]`, `[intro]`, `[outro]`, `[Instrumental]`
7. **Use `batch_size > 1`** to generate multiple variations and pick the best one
8. **Enable `generate_lrc: true`** when you need synchronized lyric timestamps

## Error Handling

| Status Code | Description |
| - | - |
| 200 | Success |
| 400 | Invalid parameters (check error message for details) |
| 401 | Authentication required |
| 402 | Insufficient credits |
| 404 | Job or resource not found |
| 429 | Rate limit exceeded (wait and retry) |
| 500 | Internal server error |

<Accordion title="Common Errors">
  **"Insufficient credits"** — Your wallet balance is too low. Top up at [Dashboard](https://www.audiopod.ai/dashboard/account).

  **"Job must be completed"** — You tried to retake/extend/edit a job that hasn't finished yet. Wait for completion first.

  **"Original music job not found"** — The source job ID doesn't exist or doesn't belong to your account.

  **"Rate limit exceeded"** — You've exceeded the rate limit. Wait a moment and try again.
</Accordion>

## Next Steps

<Columns cols={2}>
  <Card title="Music Generation" icon="music" href="/api-reference/music/generation">
    Text-to-Music, Instrumental, Rap, Vocals, Samples, Simple Mode
  </Card>

  <Card title="Audio Tools" icon="wand-magic-sparkles" href="/api-reference/music/audio-tools">
    Cover, Reference Audio, Analysis, Stem Extraction, Edit, Extend
  </Card>

  <Card title="Job Management" icon="list-check" href="/api-reference/music/jobs">
    Job status, listing, filtering, retry, presets
  </Card>
</Columns>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.