EchoEntry API Documentation

Getting Started

EchoEntry API converts spoken numbers into accurate digits. Perfect for healthcare apps, warehouse systems, IVR, and any application requiring numeric voice input.

Base URL: https://api.echoentry.ai

Authentication

All API requests require an API key passed in the X-Api-Key header.

🚀 Try It Now with Demo Key:
Use demo_key_12345 to test the API immediately (shared, 100 calls/day limit)

# Demo key - for testing only
X-Api-Key: demo_key_12345

# Production - request your own key
X-Api-Key: your_api_key_here
            

⚠️ Security: All requests must use HTTPS. Never hardcode API keys in public frontends or commit them to version control.

Endpoints

POST /v1/transcribe

Transcribe spoken digits from audio to text

Request Parameters

Parameter	Type	Required	Description
`file`	File	Required	Audio file containing spoken digits (WAV, WEBM, MP3, OGG, M4A, FLAC)
`X-Api-Key`	Header	Required	Your API authentication key

Code Examples

cURL

curl -X POST https://api.echoentry.ai/v1/transcribe \ -H "X-Api-Key: demo_key_12345" \ -F "[email protected];type=audio/wav"

Python

import requests

url = "https://api.echoentry.ai/v1/transcribe"
headers = {
    "X-Api-Key": "demo_key_12345"  # Use your own key for production
}
files = {
    "file": open("audio.wav", "rb")
}

response = requests.post(url, headers=headers, files=files)
data = response.json()

print(data["digits"])  # Output: "123"
            

JavaScript (Node.js)

const FormData = require('form-data');
const fs = require('fs');
const axios = require('axios');

const form = new FormData();
form.append('file', fs.createReadStream('audio.wav'));

axios.post('https://api.echoentry.ai/v1/transcribe', form, {
  headers: {
    ...form.getHeaders(),
    'X-Api-Key': 'demo_key_12345'  // Use your own key for production
  }
}).then(response => {
  console.log(response.data.digits);  // Output: "123"
});
            

Response Format

Success Response (200 OK)

{
  "success": true,
  "filename": "audio.wav",
  "raw_text": "one hundred twenty three",
  "digits": "123",
  "request_id": "",
  "api_key_used": "test_123"
}
                

Field	Type	Description
`success`	Boolean	Whether the transcription was successful
`filename`	String	Original filename of the uploaded audio
`raw_text`	String	Full transcription text before digit extraction
`digits`	String	Extracted digits only (main output)
`request_id`	String	Unique identifier for this request (future use)
`api_key_used`	String	The API key used for this request

Error Responses

401 Unauthorized - Missing API Key

{
  "detail": "Missing X-Api-Key header."
}
                

401 Unauthorized - Invalid API Key

{
  "detail": "Invalid or inactive API key."
}
                

400 Bad Request - Invalid File Format

{
  "detail": "File must be audio format. Accepted extensions: .wav, .webm, .mp3, .ogg, .m4a, .flac"
}
                

500 Internal Server Error - Inference Failed

{
  "detail": "Inference error: [error details]"
}
                

Best Practices

Audio Quality

Sample rate: 16kHz recommended (model is optimized for this)
Format: WAV or WEBM preferred for best quality
Duration: 1-3 seconds optimal (speak number once, then pause)
Background noise: Minimize for best accuracy

Optimal Use Cases

1-3 digit numbers: 95-99% accuracy
4+ digit numbers: Experimental, lower accuracy
Supported accents: US, UK, Irish, Australian, Canadian English

Speaking Tips

Speak clearly and at normal pace
Say number once, then pause
Examples: "forty one" (41), "five sixty four" (564), "one oh five" (105)
For zero: Say "zero" or "oh" interchangeably

Rate Limiting

Current Beta Limits:

Demo key: 100 calls/day (shared across all users)
Personal keys: 1,000 calls/month per key
Rate limit: 10 calls/minute per key

Note: Limits are documented but not yet enforced. We're monitoring usage and will add enforcement if needed.

Pricing

🎉 Free During Beta

EchoEntry API is completely free during the beta phase while we validate demand and gather feedback.

Key Type	Price	Monthly Limit	Best For
Demo Key	Free	100 calls/day (shared)	Quick testing, code examples
Personal Key	Free	1,000 calls/month	Development, small projects, prototypes

Future: Usage-based pricing may be introduced after beta validation. Early users will get grandfathered rates and advance notice before any pricing changes.

Support & Status

📊 Beta Status:

Best-effort uptime (no formal SLA yet)
Service may experience downtime during updates
Breaking changes will be announced via email

Get Help

Need help? Have questions? Found a bug?

Email: [email protected]
Response time: Within 24-48 hours (best-effort)
Issues: Please include your API key (or "demo_key_12345") and error details