> ## 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.

# Noise Reduction

> Remove background noise, enhance audio quality, and clean up recordings using AudioPod AI's advanced noise reduction technology.

## Overview

AudioPod AI's Noise Reduction API uses advanced AI models to remove background noise, enhance speech clarity, and improve overall audio quality. Process recordings to eliminate unwanted sounds while preserving the natural characteristics of speech and music.

### Key Features

* **AI-Powered Denoising**: Advanced neural networks for intelligent noise removal
* **Three Quality Modes**: `balanced` (faster, lighter), `studio` (the default) and `ultra` (highest fidelity)
* **Spectral Processing**: Traditional spectral subtraction for specific noise types
* **Voice Preservation**: Maintain natural speech characteristics during cleanup
* **Video Support**: Process audio from video files while preserving video streams
* **Batch Processing**: Handle multiple files efficiently

## Authentication

All 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)

## AI Noise Reduction

### Standard Denoising

Remove background noise using AI-powered denoising models.

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

    client = Client()

    # Simple noise reduction
    denoised = client.denoiser.denoise_audio(
        audio_file="noisy_recording.wav",
        quality_mode="balanced",  # "balanced", "studio" (default) or "ultra"
        wait_for_completion=True
    )

    print(f"Denoising completed!")
    print(f"Input file: {denoised.input_file}")
    print(f"Denoised audio URL: {denoised.denoised_audio_url}")
    print(f"Noise reduction level: {denoised.noise_reduction_db}dB")

    # Download cleaned audio
    clean_audio = client.download_file(denoised.denoised_audio_url)
    with open("clean_recording.wav", "wb") as f:
        f.write(clean_audio)

    # Studio quality denoising
    studio_denoised = client.denoiser.denoise_audio(
        audio_file="interview_with_background_noise.wav",
        quality_mode="studio",  # Higher quality processing
        wait_for_completion=True
    )

    print(f"Studio denoising completed!")
    print(f"Noise reduction level: {studio_denoised.noise_reduction_db}dB")

    # Batch processing multiple files
    noisy_files = [
        "meeting_room_recording.wav",
        "interview_outdoors.mp3",
        "podcast_home_setup.wav",
        "lecture_hall_audio.m4a"
    ]

    batch_results = client.denoiser.denoise_batch(
        audio_files=noisy_files,
        quality_mode="balanced",
        wait_for_completion=True
    )

    for i, result in enumerate(batch_results):
        print(f"\nFile {i+1}: {noisy_files[i]}")
        print(f"Status: {result.status}")
        if result.status == "completed":
            print(f"Noise reduced: {result.noise_reduction_db}dB")
            print(f"Clean audio: {result.denoised_audio_url}")
            
            # Download and save
            clean_audio = client.download_file(result.denoised_audio_url)
            output_name = f"clean_{i+1}_{noisy_files[i].split('.')[0]}.wav"
            with open(output_name, "wb") as f:
                f.write(clean_audio)
            print(f"Saved: {output_name}")

    # Process video files (audio cleaning)
    video_denoised = client.denoiser.denoise_video(
        video_file="presentation_with_noise.mp4",
        quality_mode="studio",  # Higher quality processing
        preserve_video=True,        # Keep original video stream
        wait_for_completion=True
    )

    print(f"Video denoising completed!")
    print(f"Clean video URL: {video_denoised.video_output_url}")
    print(f"Audio-only URL: {video_denoised.denoised_audio_url}")
    ```
  </Tab>

  <Tab title="Node.js">
    ```javascript theme={null}
    // Note: SDK examples shown are conceptual and may not reflect the current SDK implementation
    // For production use, refer to the Raw HTTP examples or check the latest SDK documentation
    const { AudioPodClient } = require('audiopod-js');
    const fs = require('fs');

    const client = new AudioPodClient();

    async function denoiseAudio() {
      try {
        // Simple noise reduction
        const denoised = await client.denoiser.denoiseAudio({
          audioFile: fs.createReadStream('noisy_recording.wav'),
          qualityMode: 'balanced',  // "balanced", "studio" (default) or "ultra"
          waitForCompletion: true
        });

        console.log('Denoising completed!');
        console.log(`Input file: ${denoised.inputFile}`);
        console.log(`Denoised audio URL: ${denoised.denoisedAudioUrl}`);
        console.log(`Noise reduction level: ${denoised.noiseReductionDb}dB`);

        // Download cleaned audio
        const cleanAudio = await client.downloadFile(denoised.denoisedAudioUrl);
        fs.writeFileSync('clean_recording.wav', cleanAudio);

        // Studio quality denoising
        const studioDenoised = await client.denoiser.denoiseAudio({
          audioFile: fs.createReadStream('interview_with_background_noise.wav'),
          qualityMode: 'studio',  // Higher quality processing
          waitForCompletion: true
        });

        console.log('Studio denoising completed!');
        console.log(`Noise reduction level: ${studioDenoised.noiseReductionDb}dB`);

        // Batch processing multiple files
        const noisyFiles = [
          'meeting_room_recording.wav',
          'interview_outdoors.mp3',
          'podcast_home_setup.wav',
          'lecture_hall_audio.m4a'
        ];

        const fileStreams = noisyFiles.map(file => ({
          file: fs.createReadStream(file),
          name: file
        }));

        const batchResults = await client.denoiser.denoiseBatch({
          audioFiles: fileStreams,
          qualityMode: 'balanced',
          waitForCompletion: true
        });

        batchResults.forEach((result, index) => {
          console.log(`\nFile ${index + 1}: ${noisyFiles[index]}`);
          console.log(`Status: ${result.status}`);
          if (result.status === 'completed') {
            console.log(`Noise reduced: ${result.noiseReductionDb}dB`);
            console.log(`Clean audio: ${result.denoisedAudioUrl}`);
            
            // Download and save
            client.downloadFile(result.denoisedAudioUrl).then(cleanAudio => {
              const outputName = `clean_${index + 1}_${noisyFiles[index].split('.')[0]}.wav`;
              fs.writeFileSync(outputName, cleanAudio);
              console.log(`Saved: ${outputName}`);
            });
          }
        });

        // Process video files (audio cleaning)
        const videoDenoised = await client.denoiser.denoiseVideo({
          videoFile: fs.createReadStream('presentation_with_noise.mp4'),
          qualityMode: 'studio',  // Higher quality processing
          preserveVideo: true,        // Keep original video stream
          waitForCompletion: true
        });

        console.log('Video denoising completed!');
        console.log(`Clean video URL: ${videoDenoised.videoOutputUrl}`);
        console.log(`Audio-only URL: ${videoDenoised.denoisedAudioUrl}`);

      } catch (error) {
        console.error('Denoising error:', error.message);
      }
    }

    denoiseAudio();
    ```
  </Tab>

  <Tab title="Raw HTTP">
    ```python theme={null}
    import requests
    import time

    # Standard denoising
    with open("noisy_recording.wav", "rb") as audio_file:
        response = requests.post(
            "https://api.audiopod.ai/api/v1/denoiser/denoise",
            headers={"X-API-Key": api_key},
            data={
                "quality_mode": "balanced"  # "balanced", "studio" (default) or "ultra"
            },
            files={"file": audio_file}
        )

    if response.status_code == 200:
        job_data = response.json()
        job_id = job_data["id"]
        print(f"Denoising job created: {job_id}")
        
        # Poll for completion
        while True:
            status_response = requests.get(
                f"https://api.audiopod.ai/api/v1/denoiser/jobs/{job_id}",
                headers={"X-API-Key": api_key}
            )
            
            if status_response.status_code == 200:
                job_status = status_response.json()
                print(f"Status: {job_status['status']}")
                
                if job_status["status"] == "COMPLETED":
                    print(f"Denoising completed!")
                    print(f"Clean audio URL: {job_status.get('denoised_audio_url')}")
                    print(f"Noise reduction: {job_status.get('noise_reduction_db', 0)}dB")
                    
                    # Download the cleaned audio
                    if job_status.get('denoised_audio_url'):
                        audio_response = requests.get(job_status['denoised_audio_url'])
                        with open("clean_recording.wav", "wb") as f:
                            f.write(audio_response.content)
                        print("Downloaded clean audio: clean_recording.wav")
                    break
                elif job_status["status"] == "FAILED":
                    print(f"Denoising failed: {job_status.get('error', 'Unknown error')}")
                    break
                    
            time.sleep(5)  # Check every 5 seconds
    else:
        print(f"Error: {response.status_code} - {response.text}")
    ```
  </Tab>

  <Tab title="cURL">
    ```bash theme={null}
    # Upload file for denoising
    curl -X POST "https://api.audiopod.ai/api/v1/denoiser/denoise" \
      -H "X-API-Key: $AUDIOPOD_API_KEY" \
      -F "file=@noisy_recording.wav" \
      -F "quality_mode=balanced"

    # Check job status (replace JOB_ID with actual job ID)
    curl -X GET "https://api.audiopod.ai/api/v1/denoiser/jobs/JOB_ID" \
      -H "X-API-Key: $AUDIOPOD_API_KEY"

    # Studio quality denoising
    curl -X POST "https://api.audiopod.ai/api/v1/denoiser/denoise" \
      -H "X-API-Key: $AUDIOPOD_API_KEY" \
      -F "file=@very_noisy_audio.wav" \
      -F "quality_mode=studio"
    ```
  </Tab>
</Tabs>

### Denoise from URL

Process audio/video from URLs (YouTube, etc.) to remove noise.

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    # Note: SDK examples shown are conceptual and may not reflect the current SDK implementation
    # For production use, refer to the Raw HTTP examples or check the latest SDK documentation
    from audiopod import Client

    client = Client()

    # Denoise from YouTube URL
    url_denoised = client.denoiser.denoise_from_url(
        url="https://youtube.com/watch?v=example123",
        quality_mode="studio",  # Higher quality processing for online content
        wait_for_completion=True
    )

    print(f"URL denoising completed!")
    print(f"Source: {url_denoised.source_url}")
    print(f"Clean audio URL: {url_denoised.denoised_audio_url}")
    print(f"Noise reduction: {url_denoised.noise_reduction_db}dB")

    # Batch URL processing
    urls = [
        "https://youtube.com/watch?v=lecture1",
        "https://vimeo.com/meeting_recording",
        "https://example.com/noisy_podcast.mp3"
    ]

    batch_url_results = client.denoiser.denoise_batch_from_urls(
        urls=urls,
        quality_mode="balanced",
        wait_for_completion=True
    )

    for i, result in enumerate(batch_url_results):
        print(f"\nURL {i+1}: {urls[i]}")
        print(f"Status: {result.status}")
        if result.status == "completed":
            print(f"Clean audio: {result.denoised_audio_url}")
    ```
  </Tab>

  <Tab title="Node.js">
    ```javascript theme={null}
    // Note: SDK examples shown are conceptual and may not reflect the current SDK implementation
    // For production use, refer to the Raw HTTP examples or check the latest SDK documentation
    const { AudioPodClient } = require('audiopod-js');

    const client = new AudioPodClient();

    async function denoiseFromUrl() {
      try {
        // Denoise from YouTube URL
        const urlDenoised = await client.denoiser.denoiseFromUrl({
          url: "https://youtube.com/watch?v=example123",
          qualityMode: "studio",  // Higher quality processing for online content
          waitForCompletion: true
        });

        console.log('URL denoising completed!');
        console.log(`Source: ${urlDenoised.sourceUrl}`);
        console.log(`Clean audio URL: ${urlDenoised.denoisedAudioUrl}`);
        console.log(`Noise reduction: ${urlDenoised.noiseReductionDb}dB`);

        // Batch URL processing
        const urls = [
          "https://youtube.com/watch?v=lecture1",
          "https://vimeo.com/meeting_recording",
          "https://example.com/noisy_podcast.mp3"
        ];

        const batchUrlResults = await client.denoiser.denoiseBatchFromUrls({
          urls: urls,
          qualityMode: "balanced",
          waitForCompletion: true
        });

        batchUrlResults.forEach((result, index) => {
          console.log(`\nURL ${index + 1}: ${urls[index]}`);
          console.log(`Status: ${result.status}`);
          if (result.status === "completed") {
            console.log(`Clean audio: ${result.denoisedAudioUrl}`);
          }
        });

      } catch (error) {
        console.error('URL denoising error:', error.message);
      }
    }

    denoiseFromUrl();
    ```
  </Tab>

  <Tab title="Raw HTTP">
    ```python theme={null}
    import requests
    import time

    response = requests.post(
        "https://api.audiopod.ai/api/v1/denoiser/denoise",
        headers={"X-API-Key": api_key},
        data={
            "url": "https://youtube.com/watch?v=example123",
            "quality_mode": "studio"  # Higher quality processing
        }
    )

    if response.status_code == 200:
        job_data = response.json()
        job_id = job_data["id"]
        print(f"URL denoising started: {job_id}")
        
        # Poll for completion
        while True:
            status_response = requests.get(
                f"https://api.audiopod.ai/api/v1/denoiser/jobs/{job_id}",
                headers={"X-API-Key": api_key}
            )
            
            if status_response.status_code == 200:
                job_status = status_response.json()
                print(f"Status: {job_status['status']}")
                
                if job_status["status"] == "COMPLETED":
                    print(f"URL denoising completed!")
                    print(f"Source: {job_status.get('source_url')}")
                    print(f"Clean audio: {job_status.get('denoised_audio_url')}")
                    break
                elif job_status["status"] == "FAILED":
                    print(f"Denoising failed: {job_status.get('error')}")
                    break
                    
            time.sleep(10)  # URL processing may take longer
    ```
  </Tab>

  <Tab title="cURL">
    ```bash theme={null}
    # Denoise from URL (multipart form fields, not a JSON body)
    curl -X POST "https://api.audiopod.ai/api/v1/denoiser/denoise" \
      -H "X-API-Key: $AUDIOPOD_API_KEY" \
      -F "url=https://youtube.com/watch?v=example123" \
      -F "quality_mode=ultra"

    # Check job status
    curl -X GET "https://api.audiopod.ai/api/v1/denoiser/jobs/JOB_ID" \
      -H "X-API-Key: $AUDIOPOD_API_KEY"
    ```
  </Tab>
</Tabs>

**Quality Modes:**

Every mode removes background noise and improves speech clarity. Send the mode as the `quality_mode` form field.

* **`balanced`**: The fastest, lightest mode, with clean results.
* **`studio`** (default): Broadcast and podcast quality. Used when `quality_mode` is omitted or blank.
* **`ultra`**: The highest fidelity, restoring lost high frequencies.

The value is case-insensitive. Any other value is rejected with a `422` before a job is created or any credits are reserved.

**Response:**

```json theme={null}
{
  "id": 123,
  "status": "PROCESSING",
  "progress": 0,
  "input_path": "/uploads/noisy_recording.wav",
  "is_video": false,
  "task_id": "celery_task_uuid_here",
  "created_at": "2024-01-15T10:30:00Z",
  "original_filename": "noisy_recording.wav",
  "display_name": "noisy_recording.wav"
}
```

## Spectral Noise Reduction

### Advanced Spectral Processing

Use traditional spectral subtraction for specific noise types and fine control.

<Tabs>
  <Tab title="POST">
    ```http theme={null}
    POST /api/v1/denoiser/spectral/denoise
    X-API-Key: {api_key}
    Content-Type: multipart/form-data

    file: (audio file)
    noise_type: general
    prop_decrease: 0.8
    stationary: true
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    with open("recording_with_hum.wav", "rb") as audio_file:
    response = requests.post(
            "https://api.audiopod.ai/api/v1/denoiser/spectral/denoise",
            headers={"X-API-Key": api_key},
            data={
                "noise_type": "electrical_hum",  # Specific noise type
                "prop_decrease": 0.8,            # 80% noise reduction
                "stationary": True,              # Constant noise
                "time_constant_s": 2.0,          # Adaptation time
                "freq_mask_smooth_hz": 500,      # Frequency smoothing
                "time_mask_smooth_ms": 50        # Time smoothing
            },
            files={"file": audio_file}
        )

    if response.status_code == 200:
        job_data = response.json()
        print(f"Spectral denoising job: {job_data['id']}")
    ```
  </Tab>
</Tabs>

**Noise Types:**

* **`general`**: General background noise
* **`electrical_hum`**: 50/60Hz electrical interference
* **`air_conditioning`**: HVAC and fan noise
* **`traffic`**: Vehicle and road noise
* **`crowd`**: Background conversations and crowd noise

## Job Management

### Get Job Status

Monitor the progress of noise reduction jobs.

<Tabs>
  <Tab title="GET">
    ```http theme={null}
    GET /api/v1/denoiser/jobs/{job_id}
    X-API-Key: {api_key}
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    response = requests.get(
        f"https://api.audiopod.ai/api/v1/denoiser/jobs/{job_id}",
        headers={"X-API-Key": api_key}
    )

    if response.status_code == 200:
        job_status = response.json()
        print(f"Status: {job_status['status']}")
        print(f"Progress: {job_status['progress']}%")
        
        if job_status["status"] == "COMPLETED":
            print("Denoising complete!")
            print(f"Output URL: {job_status['output_url']}")
    ```
  </Tab>
</Tabs>

**Response (Completed):**

```json theme={null}
{
  "id": 123,
  "status": "COMPLETED",
  "progress": 100,
  "input_path": "/uploads/noisy_recording.wav",
  "output_path": "/processed/clean_recording_123.wav",
  "video_output_path": null,
  "is_video": false,
  "task_id": "celery_task_uuid_here",
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:32:15Z",
  "completed_at": "2024-01-15T10:32:15Z",
  "output_url": "https://api.audiopod.ai/download/clean_recording_123.wav",
  "video_output_url": null,
  "original_filename": "noisy_recording.wav",
  "display_name": "Clean Recording",
  "stats": {
    "noise_reduction_db": 15.2,
    "processing_time": 135.4,
    "audio_duration": 180.0
  }
}
```

### List Denoising Jobs

Get all noise reduction jobs for the authenticated user.

<Tabs>
  <Tab title="GET">
    ```http theme={null}
    GET /api/v1/denoiser/jobs?limit=50&skip=0
    X-API-Key: {api_key}
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    response = requests.get(
        "https://api.audiopod.ai/api/v1/denoiser/jobs",
        headers={"X-API-Key": api_key},
        params={
            "limit": 50,
            "skip": 0
        }
    )

    if response.status_code == 200:
        jobs = response.json()
    for job in jobs:
            print(f"Job {job['id']}: {job['status']} - {job['original_filename']}")
    ```
  </Tab>
</Tabs>

### Retry Failed Job

Retry a failed noise reduction job.

<Tabs>
  <Tab title="POST">
    ```http theme={null}
    POST /api/v1/denoiser/jobs/{job_id}/retry
    X-API-Key: {api_key}
    ```
  </Tab>
</Tabs>

### Cancel Job

Cancel a pending denoising job.

<Tabs>
  <Tab title="POST">
    ```http theme={null}
    POST /api/v1/denoiser/jobs/{job_id}/cancel
    X-API-Key: {api_key}
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    response = requests.post(
        f"https://api.audiopod.ai/api/v1/denoiser/jobs/{job_id}/cancel",
        headers={"X-API-Key": api_key}
    )

    if response.status_code == 200:
        job_status = response.json()
        print(f"Job {job_id} cancelled: {job_status['status']}")
    ```
  </Tab>
</Tabs>

### Delete Job

Remove a completed job and its results.

<Tabs>
  <Tab title="DELETE">
    ```http theme={null}
    DELETE /api/v1/denoiser/jobs/{job_id}
    X-API-Key: {api_key}
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    response = requests.delete(
        f"https://api.audiopod.ai/api/v1/denoiser/jobs/{job_id}",
        headers={"X-API-Key": api_key}
    )

    if response.status_code == 204:
        print(f"Job {job_id} and associated files deleted successfully")
    ```
  </Tab>
</Tabs>

### Health Check

Check the denoising service availability and status.

<Tabs>
  <Tab title="GET">
    ```http theme={null}
    GET /api/v1/denoiser/health
    X-API-Key: {api_key}
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    response = requests.get(
        "https://api.audiopod.ai/api/v1/denoiser/health",
        headers={"X-API-Key": api_key}
    )

    if response.status_code == 200:
        health_status = response.json()
        print(f"Service status: {health_status['status']}")
    ```
  </Tab>
</Tabs>

**Health Response:**

```json theme={null}
{
  "status": "available"
}
```

## Error Handling

<AccordionGroup>
  <Accordion title="400 Bad Request - Invalid Audio">
    **Causes:** - Audio file corrupted or invalid format - File contains no audio content - Unsupported codec
    **Solutions:** - Use supported formats (WAV, MP3, M4A, MP4) - Verify file integrity - Check audio content exists
  </Accordion>

  <Accordion title="413 Payload Too Large - Over Your Plan's Upload Limit">
    **Causes:** - The uploaded file is larger than your plan allows per upload
    **Solutions:** - Upgrade your plan for larger uploads - Trim or compress the file before uploading
  </Accordion>

  <Accordion title="422 Unprocessable Entity - Invalid Request or Denoising Failed">
    **Causes:** - `quality_mode` is not one of `balanced`, `studio` or `ultra` - Audio quality too poor for processing - Extreme noise levels - Very short audio duration
    **Solutions:** - Try different quality mode - Use spectral processing for specific noise types - Ensure minimum 5 seconds duration
  </Accordion>

  <Accordion title="402 Payment Required - Insufficient Credits">
    **Causes:** - Not enough credits for processing duration
    **Solutions:** - Purchase additional credits - Check credit requirements before processing
  </Accordion>
</AccordionGroup>

## Pricing

Signed-in accounts are billed from the **account credit balance** at the rate
of the chosen quality mode, with a 10-credit minimum per job. API-key calls pay
the API price of the chosen mode. Call `POST /api/v1/denoiser/quote` to see the
exact cost before you start a job.

| Service | Quality mode | Cost |
| - | - | - |
| AI Denoising | `balanced` | 330 credits/minute |
| AI Denoising | `studio` (default) | 660 credits/minute |
| AI Denoising | `ultra` | 1,320 credits/minute |
| Spectral Processing | — | 660 credits/minute |

### Cost Examples

| Duration | Method | Credits |
| - | - | - |
| 10 minutes | AI Denoising (balanced) | 3,300 |
| 10 minutes | AI Denoising (studio) | 6,600 |
| 10 minutes | AI Denoising (ultra) | 13,200 |
| 30 minutes | Spectral | 19,800 |
| 1 hour | AI Denoising (studio) | 39,600 |

## Next Steps

<Columns cols={2}>
  <Card title="Voice Cloning" icon="users" href="/api-reference/voice-management">
    Use cleaned audio for better voice model training.
  </Card>

  <Card title="Speech-to-Text" icon="waveform" href="/api-reference/speech-to-text">
    Improve transcription accuracy with clean audio.
  </Card>
</Columns>


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