API Documentation

Welcome to Echo Audio API. This comprehensive guide will help you integrate professional audio enhancement into your applications.

Getting Started

To use the Echo API, you need:

1. Project ID - Uniquely identifies your project
2. API Key - Authenticates your requests
3. Secret Key - Additional security credential

How to get credentials:

1. Go to the Projects page
2. Click Create Project and enter a project name
3. View and copy your Project ID, API Key, and Secret Key
4. Store these securely - the Secret Key is only shown once

Authentication

All API requests require authentication. Include your credentials in the Authorization header:

Authorization: Bearer {PROJECT_ID}:{API_KEY}:{SECRET_KEY}

Example with cURL:

curl -H "Authorization: Bearer proj_abc123:echo_key_xyz:echo_secret_def" \
  https://api.echo.audio/v1/enhance

Example with JavaScript Fetch:

const credentials = `${projectId}:${apiKey}:${secretKey}`;
const authHeader = `Bearer ${credentials}`;

fetch('https://api.echo.audio/v1/enhance', {
  method: 'POST',
  headers: {
    'Authorization': authHeader,
    'Content-Type': 'application/json'
  },
  body: formData
});

API Endpoints

{
  "job_id": "job_abc123xyz",
  "status": "processing",
  "message": "Audio file received and queued for processing"
}

curl -X POST https://api.echo.audio/api/v1/public/upload \
  -H "Authorization: Bearer proj_abc:echo_key_xyz:echo_secret_def" \
  -F "file=@recording.wav"

const formData = new FormData();
formData.append('file', audioFile);

const response = await fetch('https://api.echo.audio/api/v1/public/upload', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${projectId}:${apiKey}:${secretKey}`
  },
  body: formData
});

const data = await response.json();
console.log('Job ID:', data.job_id);

{
  "job_id": "job_abc123xyz",
  "status": "processing",
  "message": "Your audio is being enhanced"
}

{
  "job_id": "job_abc123xyz",
  "status": "completed",
  "text": "Full transcript of the audio...",
  "audio_url": "https://storage.echo.audio/...",
  "processing_time": 45,
  "quality_score": 0.92
}

{
  "job_id": "job_abc123xyz",
  "status": "failed",
  "error": "Unsupported audio format"
}

curl -X GET https://api.echo.audio/api/v1/public/result/job_abc123 \
  -H "Authorization: Bearer proj_abc:echo_key_xyz:echo_secret_def"

async function pollResult(jobId) {
  let result;
  
  while (true) {
    const response = await fetch(
      `https://api.echo.audio/api/v1/public/result/${jobId}`,
      {
        headers: {
          'Authorization': `Bearer ${projectId}:${apiKey}:${secretKey}`
        }
      }
    );
    
    result = await response.json();
    
    if (result.status === 'completed') {
      console.log('Transcript:', result.text);
      return result;
    } else if (result.status === 'failed') {
      throw new Error(result.error);
    }
    
    // Wait 2 seconds before polling again
    await new Promise(resolve => setTimeout(resolve, 2000));
  }
}

Error Codes

Rate Limits & Quotas

Best Practices

• Store credentials securely: Never hardcode API keys in client-side code. Use environment variables or backend proxies.
• Use exponential backoff: When polling results, increase wait time gradually to avoid excessive requests.
• Implement proper error handling: Always check response status codes and error messages.
• Monitor usage: Check your usage statistics regularly on the dashboard to avoid exceeding quotas.
• Cache results: Store processed results to avoid re-processing the same audio files.
• Rotate credentials: Periodically revoke old projects and create new ones for enhanced security.
• Use specific file formats: WAV and FLAC provide best quality, MP3 is more compact.
• Handle timeouts: Set appropriate timeout values for your requests (recommended: 5-10 minutes for large files).

Code Examples

Python Example:

import requests
import time

PROJECT_ID = "proj_abc123"
API_KEY = "echo_key_xyz"
SECRET_KEY = "echo_secret_def"

credentials = f"{PROJECT_ID}:{API_KEY}:{SECRET_KEY}"
headers = {"Authorization": f"Bearer {credentials}"}

# Upload file
with open('recording.wav', 'rb') as f:
    response = requests.post(
        'https://api.echo.audio/api/v1/public/upload',
        headers=headers,
        files={'file': f}
    )
    job_id = response.json()['job_id']

# Poll for results
while True:
    response = requests.get(
        f'https://api.echo.audio/api/v1/public/result/{job_id}',
        headers=headers
    )
    result = response.json()
    
    if result['status'] == 'completed':
        print(f"Transcript: {result['text']}")
        break
    elif result['status'] == 'failed':
        print(f"Error: {result['error']}")
        break
    
    time.sleep(2)

Node.js Example:

const fs = require('fs');
const fetch = require('node-fetch');

const PROJECT_ID = 'proj_abc123';
const API_KEY = 'echo_key_xyz';
const SECRET_KEY = 'echo_secret_def';

const credentials = `${PROJECT_ID}:${API_KEY}:${SECRET_KEY}`;

async function processAudio(filePath) {
  // Upload
  const formData = new FormData();
  formData.append('file', fs.createReadStream(filePath));
  
  const uploadRes = await fetch('https://api.echo.audio/api/v1/public/upload', {
    method: 'POST',
    headers: { 'Authorization': `Bearer ${credentials}` },
    body: formData
  });
  
  const { job_id } = await uploadRes.json();
  
  // Poll
  let completed = false;
  while (!completed) {
    const resultRes = await fetch(
      `https://api.echo.audio/api/v1/public/result/${job_id}`,
      { headers: { 'Authorization': `Bearer ${credentials}` } }
    );
    
    const result = await resultRes.json();
    
    if (result.status === 'completed') {
      console.log('Transcript:', result.text);
      completed = true;
    } else if (result.status === 'failed') {
      throw new Error(result.error);
    }
    
    await new Promise(r => setTimeout(r, 2000));
  }
}

processAudio('recording.wav');

Support & Contact

For issues, questions, or feature requests, please contact our support team at support@echo.audio

API Status Page: status.echo.audio

Rate Limit Headers: Check response headers for remaining quota:

• X-RateLimit-Limit - Total requests allowed
• X-RateLimit-Remaining - Requests remaining
• X-RateLimit-Reset - When limit resets (Unix timestamp)