Vox API v1

Production base URL: https://vox.myspeakingscore.com
Sandbox base URL: Available on request

Authentication

Send your key as a Bearer token. Production keys start with vox_live_; sandbox keys start with vox_test_, only work against the sandbox host, and are never billed. Keep keys on your server only.

shell

curl https://vox.myspeakingscore.com/v1/health \
  -H "Authorization: Bearer vox_live_…"

javascript

const res = await fetch("https://vox.myspeakingscore.com/v1/health", {
  headers: { Authorization: `Bearer ${process.env.VOX_API_KEY}` },
});

Errors & limits

401 missing, invalid or revoked key
402 subscription inactive or payment failed
429 rate limited — retry after the Retry-After header
5xx server error — not billed, safe to retry with the same request

GET/v1/health

Check that the API is reachable and your key is valid. Not billed.

shell

curl https://vox.myspeakingscore.com/v1/health \
  -H "Authorization: Bearer $VOX_API_KEY"

response

{ "status": "ok", "environment": "production" }

POST/v1/curricula/record

Record a learner attempt against one of your curriculum items.

shell

curl https://vox.myspeakingscore.com/v1/curricula/record \
  -H "Authorization: Bearer $VOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"curriculum_id":"unit-4","item_id":"q2","learner_ref":"your-learner-123"}'

response

{ "request_id": "req_…", "recorded": true }

POST/v1/score/general

General speaking score for a single audio answer.

shell

curl https://vox.myspeakingscore.com/v1/score/general \
  -H "Authorization: Bearer $VOX_API_KEY" \
  -F audio=@answer.wav \
  -F prompt="Describe your hometown."

response

{ "request_id": "req_…", "overall": 6.5, "fluency": 6.0, "grammar": 6.5, "pronunciation": 7.0 }

POST/v1/score/int

International exam-style band score with criteria breakdown.

shell

curl https://vox.myspeakingscore.com/v1/score/int \
  -H "Authorization: Bearer $VOX_API_KEY" \
  -F audio=@part2.wav \
  -F part=2

response

{ "request_id": "req_…", "band": 6.5, "criteria": { "fluency": 6, "lexical": 7, "grammar": 6, "pronunciation": 7 } }

POST/v1/pronunciation/analyze

Word and phoneme-level pronunciation feedback against a reference text.

shell

curl https://vox.myspeakingscore.com/v1/pronunciation/analyze \
  -H "Authorization: Bearer $VOX_API_KEY" \
  -F audio=@read.wav \
  -F reference_text="The weather is lovely today."

response

{ "request_id": "req_…", "accuracy": 0.86, "words": [{ "word": "weather", "score": 0.72, "phonemes": [ … ] }] }

POST/v1/evaluate

Preview — not yet enabled. Multipart: audio (WAV/MP3/M4A/WebM, 1 s minimum), mode (pronunciation · toefl_speaking · ielts_speaking · combined), optional transcript, task_type, prompt, accent_target, learner_language. Limits: pronunciation 30 s / 10 MB, TOEFL 60 s / 20 MB, IELTS and combined 150 s / 30 MB, whole request 30 MB. Over-limit audio returns 413 audio_too_long or audio_too_large; bad input returns 400 (invalid_mode, missing_audio, unsupported_format, audio_too_short, invalid_field). TOEFL/IELTS results are unofficial estimates, returned only where scoring exists; otherwise that section is not_implemented, and 501 if nothing could be scored. One accepted request = one billable call; rejected and 501 requests are never billed.

shell

curl https://vox.myspeakingscore.com/v1/evaluate \
  -H "Authorization: Bearer $VOX_API_KEY" \
  -F audio=@answer.wav \
  -F mode=combined \
  -F task_type=independent \
  -F learner_language=it

response

{ "request_id": "req_…", "mode": "combined",
  "pronunciation": { "status": "ok", "overall": 82, "accuracy": 0.9, "fluency": 0.8, "completeness": null, "words": [ … ] },
  "toefl": { "status": "not_implemented" },
  "ielts": { "status": "ok", "unofficial": true, "overall": 6.5, "criteria": { … } } }