API Reference

The ProsodyAI REST API allows you to analyze speech emotion from any programming language.

Base URL

https://api.prosody.ai/v1

Authentication

All API requests require authentication via API key:

curl https://api.prosody.ai/v1/analyze \
  -H "Authorization: Bearer psk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"audio_url": "https://..."}'

Or using the X-API-Key header:

curl https://api.prosody.ai/v1/analyze \
  -H "X-API-Key: psk_your_api_key" \
  ...

Endpoints Overview

Method	Endpoint	Description
`POST`	`/analyze`	Analyze single audio segment
`POST`	`/analyze/batch`	Analyze multiple audio segments
`WS`	`/stream`	Real-time streaming analysis
`POST`	`/sessions`	Create conversation session
`POST`	`/sessions/{id}/utterances`	Add utterance to session
`GET`	`/sessions/{id}`	Get session predictions
`POST`	`/webhooks`	Create webhook
`GET`	`/webhooks`	List webhooks
`DELETE`	`/webhooks/{id}`	Delete webhook
`POST`	`/fine-tune`	Create fine-tune job
`GET`	`/fine-tune/{id}`	Get fine-tune status

Request Format

All requests should use JSON with Content-Type: application/json, except for audio uploads which support multipart/form-data.

Response Format

All responses are JSON:

{
  "emotion": "happy",
  "confidence": 0.92,
  "valence": 0.7,
  "arousal": 0.5,
  "dominance": 0.6,
  "state": "satisfied",
  "metrics": {
    "csatPredicted": 4.5,
    "escalationRisk": "low"
  }
}

Error Responses

Errors return appropriate HTTP status codes with details:

{
  "error": {
    "code": "invalid_audio_format",
    "message": "Unsupported audio format: video/mp4",
    "details": {
      "supported_formats": ["audio/wav", "audio/mp3", "audio/ogg"]
    }
  }
}

Rate Limits

Plan	Requests/min	Concurrent
Free	60	5
Starter	300	20
Pro	1,000	50
Enterprise	Custom	Custom

Rate limit headers are included in all responses:

X-RateLimit-Limit: Requests allowed per minute
X-RateLimit-Remaining: Requests remaining
X-RateLimit-Reset: Unix timestamp when limit resets

SDKs

Official SDKs handle authentication, retries, and type safety:

TypeScript/JavaScript - @prosody/sdk
Python - prosody-sdk
LangChain - @prosody/langchain

API Reference

On this page