Platform API Reference
Reference for the MSJ Oratio platform REST API, including speech generation, history, account keys, and billing.
Create an account
Sign up free to get started
Get your API key
Generate a key in API Keys
Make your first call
POST to /api/tts with text & voiceId
All platform API requests use this base URL. The standalone Voice API uses https://api.msjoratio.com — see Voice API docs.
Customer speech and history endpoints accept an MSJ Oratio key using either header format. The API Keys and billing management endpoints require a signed-in browser session. Keys from this page do not authenticate directly to the standalone Voice API.
orat_. Create keys in API Keys.| Plan | Characters / month | Max per request | Voice qualities | API rate |
|---|---|---|---|---|
| Free | 1,000 | 500 | Standard only | 10 req/min |
| Pro ($29/mo) | 500,000 | 1,600 | Standard, Premium, Ultra | 100 req/min |
POST /api/tts returns 429 with remaining balance details.curl -X POST https://msjoratio.com/api/tts \
-H "Authorization: Bearer orat_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"text": "Hello from MSJ Oratio!",
"voiceId": "chatterbox-default"
}'const response = await fetch("https://msjoratio.com/api/tts", {
method: "POST",
headers: {
"Authorization": "Bearer orat_YOUR_API_KEY",
"Content-Type": "application/json",
},
body: JSON.stringify({
text: "Hello from MSJ Oratio!",
voiceId: "chatterbox-default",
}),
});
const { generation, credits } = await response.json();
console.log(generation.audioUrl); // "/api/tts/audio/clx1abc..."
console.log(credits.remaining); // 499870import requests
response = requests.post(
"https://msjoratio.com/api/tts",
headers={"Authorization": "Bearer orat_YOUR_API_KEY"},
json={
"text": "Hello from MSJ Oratio!",
"voiceId": "chatterbox-default",
},
)
data = response.json()
print(data["generation"]["audioUrl"])
print(data["credits"]["remaining"])Speech Generation
/api/tts Auth RequiredQueue text-to-speech generation for a selected voice. Returns HTTP 202 with a processing generation; poll /api/generations/:id and fetch /api/tts/audio/:id when complete. Credits are charged by character count.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| text | string | Required | Text to convert to speech. Max 500 chars (Free) or 1,600 chars (Pro) per request. |
| voiceId | string | Required | Voice identifier from the current catalog ("chatterbox-default", "chatterbox-voice-b", or "platform-02-msj"). |
| style | string | Optional | Override the voice default style. Falls back to the voice built-in style. |
Request Body
{
"text": "Hello, welcome to MSJ Oratio.",
"voiceId": "chatterbox-default",
"style": "Natural"
}Response
{
"generation": {
"id": "clx1abc...",
"text": "Hello, welcome to MSJ Oratio.",
"voiceName": "Chatterbox Default",
"style": "Natural",
"characterCount": 30,
"duration": null,
"quality": null,
"status": "processing",
"audioUrl": null,
"createdAt": "2026-03-18T10:00:00Z"
},
"credits": {
"used": 130,
"limit": 500000,
"remaining": 499870
}
}Error Codes
/api/tts Auth RequiredReturns available or owned voice profiles for the authenticated account. Use scope=available or scope=owned.
Response
{
"voices": [
{
"id": "chatterbox-default",
"name": "Chatterbox Default",
"engine": "chatterbox",
"voiceVersion": "v1",
"language": "en"
},
{
"id": "chatterbox-voice-b",
"name": "Chatterbox Voice B",
"engine": "chatterbox",
"voiceVersion": "v1",
"language": "en"
},
{
"id": "platform-02-msj",
"name": "MSJ",
"engine": "chatterbox",
"voiceVersion": "v2",
"language": "en"
}
]
}Speech Transcription
/api/stt Auth RequiredSend multipart/form-data with an audio file to the local GPU speech-recognition worker. The account must have transcription entitlement. Limit: 10 MB and 2 minutes; upload and rate limits apply.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| audio | file | Required | Audio file to transcribe |
| language | string | Optional | Language code or auto |
Request Body
Content-Type: multipart/form-data audio=<file> language=en
Response
{ "transcription": "Spoken words here.", "text": "Spoken words here.", "model": "faster-whisper-tiny-local", "duration": 3.2 }Error Codes
Generations & Dashboard
/api/generations Auth RequiredRetrieve all past voice generations for the authenticated user, ordered by most recent first.
Response
{
"generations": [
{
"id": "clx1abc...",
"text": "Hello world",
"voiceName": "Aria",
"style": "Warm & Expressive",
"duration": 1.3,
"status": "completed",
"quality": 94.2,
"createdAt": "2026-03-18T10:00:00Z"
}
]
}Error Codes
/api/generations/:id Auth RequiredPoll an owned generation after POST /api/tts. When status is completed, download its audio from /api/tts/audio/:id.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| id | string | Required | Generation ID returned by POST /api/tts |
Response
{ "generation": { "id": "clx1abc...", "status": "completed", "audioUrl": "/api/tts/audio/clx1abc..." } }Error Codes
/api/tts/audio/:id Auth RequiredDownload the audio for a completed generation owned by the authenticated account. Returns audio bytes, not JSON.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| id | string | Required | Completed generation ID |
Response
Content-Type: audio/wav <binary audio>
Error Codes
/api/generations/:id Auth RequiredPermanently delete a specific generation by ID. Only the owner can delete their own generations.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| id | string | Required | Generation ID (path parameter) |
Response
{ "success": true }Error Codes
/api/dashboard Auth RequiredGet real-time credit usage, subscription status, aggregate stats, weekly activity chart data, and the 5 most recent generations.
Response
{
"user": { "name": "John", "email": "john@example.com" },
"credits": {
"used": 1250,
"limit": 500000,
"remaining": 498750,
"resetAt": "2026-03-01T00:00:00Z",
"percentUsed": 0
},
"subscription": {
"plan": "pro",
"isActive": true,
"periodEnd": "2026-04-18T00:00:00Z"
},
"stats": {
"totalGenerations": 47,
"thisMonthGenerations": 12,
"totalMinutes": 23.4,
"avgQuality": 93.7
},
"weeklyUsage": [
{ "day": "Mon", "count": 3, "characters": 450 }
],
"recentGenerations": [...]
}Error Codes
API Keys
/api/keys Auth RequiredList masked API key metadata for the signed-in account. Browser session required; API keys cannot manage keys.
Response
{
"keys": [
{
"id": "clx2def...",
"name": "Production",
"maskedKey": "orat_••••••••••••••••••••••••",
"lastUsed": null,
"createdAt": "2026-03-18T10:00:00Z"
}
]
}Error Codes
/api/keys Auth RequiredCreate a platform API key with a descriptive name. The secret is returned only once. Browser session required.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| name | string | Required | Descriptive label for the key (max 100 characters) |
Request Body
{
"name": "Production Backend"
}Response
{
"key": {
"id": "clx2def...",
"name": "Production Backend",
"secret": "orat_a1b2c3d4e5f6...",
"maskedKey": "orat_••••••••••••••••••••••••",
"createdAt": "2026-03-18T10:00:00Z"
}
}Error Codes
/api/keys/:id Auth RequiredRevoke and delete a key. Only its owner can delete it, using a browser session.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| id | string | Required | API key ID (path parameter) |
Response
{ "deleted": true }Error Codes
Billing & Subscription
/api/stripe/checkout Auth RequiredInitiate a Stripe checkout session for the Pro plan. If the user already has an active subscription, returns a billing portal URL instead.
Response
{ "url": "https://checkout.stripe.com/c/pay_..." }Error Codes
/api/stripe/portal Auth RequiredCreate a Stripe billing portal session for managing subscription, payment methods, and invoices.
Response
{ "url": "https://billing.stripe.com/p/session/..." }Error Codes
Authentication
/api/registerPublicCreate a new user account with email and password. Password is hashed with bcrypt (12 rounds). Returns a clean user object without the password hash.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| name | string | Optional | User display name |
| string | Required | Unique email address | |
| password | string | Required | Password (minimum 8 characters) |
Request Body
{
"name": "John Doe",
"email": "john@example.com",
"password": "secureP@ss123"
}Response
{
"user": {
"id": "clx3ghi...",
"email": "john@example.com",
"name": "John Doe"
}
}Error Codes
Three Chatterbox voices are available: the bundled default, Voice B with a reference-conditioned sound, and MSJ with the approved reference. The pinned model supports English generation.
| ID | Name | Quality | Accent | Category |
|---|---|---|---|---|
| chatterbox-default | Chatterbox Default | Premium | Built-in voice | Professional |
| chatterbox-voice-b | Chatterbox Voice B | Premium | Reference-conditioned English | Professional |
| platform-02-msj | MSJ | Premium | MSJ reference | Professional |