API Guide - Podonos

Quickstart

Create an account, retrieve an API key from the dashboard, and send an audio file to receive a score in under 2 minutes.

Install the Python client

pip install podonos

Evaluate a file

import podonos
import os

client = podonos.Client(api_key=os.getenv('PODONOS_API_KEY'))

result = client.evaluate(audio_url='https://your-bucket.example.com/sample.wav')

print(result.mos_score)
print(result.sub_scores)

{
  "mos_score": 4.12,
  "confidence_low": 3.97,
  "confidence_high": 4.27,
  "sub_scores": {
    "naturalness": 0.83,
    "prosody": 0.80,
    "pronunciation": 0.85
  },
  "eval_ms": 1820,
  "eval_id": "evl_01j2k3m4n5p6"
}

Authentication

All API calls require an API key in the Authorization header with the Bearer scheme. Create keys from your account dashboard.

curl https://api.podonosvoice.com/v1/evaluate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"audio_url": "https://example.com/sample.wav"}'

Treat the API key as secret. If exposed, rotate it in the dashboard.

POST /v1/evaluate

Score one audio file and return its MOS score plus sub-scores. Supply the file by URL or base64-encoded binary.

POST /v1/evaluate

Request body

{
  "audio_url":  "string"   // HTTPS URL, mutually exclusive with audio_b64
  "audio_b64":  "string"   // base64-encoded audio, mutually exclusive with audio_url
  "format":     "string"   // optional: wav | mp3 | flac | ogg (auto-detected if omitted)
}

Response

Returns EvalResult; field meanings appear in the Response schema below.

POST /v1/batch

Send up to 100 audio files per request. Pro and Scale plans include this feature. A batch ID is returned; obtain results by webhook or polling the history endpoint.

POST /v1/batch

{
  "items": [
    { "id": "sample-01", "audio_url": "https://example.com/01.wav" },
    { "id": "sample-02", "audio_url": "https://example.com/02.wav" }
  ],
  "webhook_url": "https://your-server.example.com/webhook"  // optional
}

{
  "batch_id": "bat_01j2k3m4n5p6",
  "status": "queued",
  "item_count": 2
}

GET /v1/evaluations

List your account's evaluations in pages, ordered newest first by creation time.

GET /v1/evaluations

Query parameters

limit   integer  Number of results to return (max 100, default 20)
before  string   Return results before this eval_id (cursor pagination)
after   string   Return results after this eval_id

Response schema

Evaluation outputs use this common structure:

eval_id          string   Unique evaluation identifier
mos_score        float    Mean Opinion Score estimate (1.0 - 5.0)
confidence_low   float    Lower bound of 95% confidence interval
confidence_high  float    Upper bound of 95% confidence interval
sub_scores       object
  naturalness    float    0.0 - 1.0
  prosody        float    0.0 - 1.0
  pronunciation  float    0.0 - 1.0
eval_ms          integer  Evaluation latency in milliseconds
created_at       string   ISO 8601 timestamp

Error codes

HTTP status	Code	Description
400	`invalid_audio`	Corrupt or unsupported file, or file exceeds 50MB
401	`unauthorized`	API key absent or invalid
422	`missing_field`	Required request field absent
429	`quota_exceeded`	Monthly quota exhausted; upgrade or await next cycle
500	`internal_error`	Server error; retry using exponential backoff

Rate limits

Each API key has plan-specific request limits:

Plan	Requests/minute	Concurrent requests
Free	10	2
Pro	60	10
Scale	300	30

HTTP 429 responses include Retry-After, which specifies when to try again.