Txt2Voice API (1.0.0)

Text-to-speech delivered as phone calls. Submit a text message and a recipient phone number. The service converts the text to natural-sounding speech and delivers it as an automated voice call.

All endpoints are relative to:

https://api.spirius.com/txt2voice

• Natural-sounding speech in 43 languages across 45 BCP 47 tags (English and Portuguese each have two regional variants)
• Automatic translation: text written in another language is spoken in the selected language (e.g. Swedish text with language: de is read in German)
• Delivery style controlled with plain-language instructions; no markup needed
• Male or female voice selection via the gender field
• Message status queries: GET /v1/messages/{transaction_id}
• Automatic reattempts on unanswered or busy calls (final delivery report after the last attempt. Allow around 5 minutes before treating a message as undelivered)
• Optional voicemail detection (machine_detection, default off): playback waits for an answering-machine greeting to end so the recorded message is complete; adds a few seconds of delay after a human answers
• Delivery report webhooks with retry
• Simple HTTP endpoint for easy integration

The caller ID (sender) shown to the recipient is resolved from the first available of these, in priority order:

1. The sender field in the request.
2. The account's configured default sender.
3. The Spirius default sender ID.

So a request that sends no sender and whose account has no configured default falls back to the Spirius default sender ID. Caller IDs are phone numbers in strict E.164 format. Client-specific caller IDs (the request sender and the account's configured default) must be registered with Spirius before use; the Spirius default sender ID is always available and needs no registration. A request with an unregistered sender is rejected immediately (HTTP 422 on the REST API, request=false on the Simple HTTP interface) with instructions. To register a number, contact Spirius support. Alphanumeric SMS sender IDs cannot be used for voice calls. For calls to Swedish destinations, the caller ID must additionally be a number provisioned through Spirius (Swedish anti-spoofing regulation); contact support to set one up.

The REST endpoint does not use SSML or prosody markup. Instead, pass an optional instructions field describing in plain language how the text should be spoken:

{
  "to": "+46701234567",
  "text": "Välkommen till Spirius! Vi ser fram emot att hjälpa dig.",
  "language": "sv",
  "instructions": "Läs med en varm och välkomnande röst."
}

More examples:

A one-time code, read slowly and clearly:

{
  "to": "+46701234567",
  "text": "Din pin kod är 7 9 5 2",
  "language": "sv",
  "instructions": "Read the code slowly and clearly."
}

A service alert:

{
  "to": "+46701234567",
  "text": "This is an alert. Your server is unreachable.",
  "language": "en-US",
  "instructions": "Speak in a professional tone."
}

The instructions may be written in any language and are interpreted independently of the message language; they shape how the message is spoken and are not read aloud. Put the words you want spoken in text; keep instructions to delivery guidance only. For the most reliable results we recommend writing instructions in English or in the message's spoken language.

Keep instructions simple and focused on delivery, as in the examples above. A single clear direction works best; stacking several emotional cues tends to push the voice too far and sound unnatural. Start from a tested phrasing and experiment from there.

How you separate numbers controls how they are read.

One digit at a time (codes, PINs). Separate the digits with spaces:

• "Your code is 4 7 1 1" → "four, seven, one, one"
• "Your code is 4711" (no separators) → "four thousand seven hundred eleven"

Mixing single and multi-digit numbers. Separate every value with a comma and a space. A space alone is enough when every value is a single digit, but with multi-digit values a comma is needed so they are read as whole numbers rather than individual digits. Comma-and-space always works, so prefer it:

• "2, 4, 98, 25" → "two, four, ninety-eight, twenty-five"

Decimal numbers. Always use a dot as the decimal separator; it is read correctly regardless of the selected language (a comma would be treated as a value separator instead):

• "2.50, 7.95, 4.55" → "two point five zero, seven point nine five, four point five five"

The REST language field takes a BCP 47 tag. English and Portuguese require the regional variant (en-US/en-GB, pt-PT/pt-BR); every other language uses the bare tag. Codes are case-insensitive and the default is en-GB.

language selects the spoken language. Text written in a different language is automatically translated to it before it is spoken — for example "Välkommen till Spirius" with language: de is read in German ("Willkommen bei Spirius").

Automatic translation can be imperfect and may reword, alter, or drop details — including digits. For messages that must be delivered exactly — PIN codes, one-time passwords, reference numbers — write the text in the intended spoken language and set language to match, so the wording and numbers are preserved. Translation is a convenience for free-form text, not a guarantee of accuracy.

The account must have the Txt2Voice API permission enabled.

• POST /v1/messages (REST): HTTP Basic Auth (Authorization header).
• GET /v1/sendtts (Simple HTTP): credentials via User and Pass query parameters.

1. Submit message via POST /v1/messages or GET /v1/sendtts
2. Receive 202 Accepted with a TransactionId
3. Service generates audio, initiates phone call
4. On call completion, delivery report sent to configured webhook URL

Unanswered or busy calls are automatically reattempted (2 reattempts at 2-minute intervals); the delivery report is sent once, after the final attempt.

GET /v1/messages/{transaction_id} returns the current state of a transaction (Basic auth, same credentials as sending):

{
  "transaction_id": "fa7a2ada-d3d4-4c93-a125-fec9ecd84f92",
  "status": "completed",
  "created": "2026-07-13T09:36:08Z",
  "duration_seconds": 24,
  "failure_code": null
}

status is accepted (in progress, including the retry window), completed (delivered; duration_seconds set) or failed (failure_code set: 1 = call could not be delivered, 5 = internal error). Unknown transaction ids return 404.

GET /v1/sendtts is the drop-in replacement for the previous Txt2Voice service; existing integrations only change the host name. New integrations should use POST /v1/messages instead; this interface exists for migration and will eventually be deprecated.

Query parameters (all values URI-encoded; names are case sensitive):

Success response (HTTP 202):

request=true&TransactionId=fa7a2ada-d3d4-4c93-a125-fec9ecd84f92

Failure response (HTTP 200 with request=false, or HTTP 400 for malformed parameters):

request=false&error=Unsupported language: XX

Examples:

GET /txt2voice/v1/sendtts?User=myuser&Pass=mypassword&To=%2B46701234567&Msg=Hello+world
GET /txt2voice/v1/sendtts?User=myuser&Pass=mypassword&To=%2B46701234567&Lang=SE&Msg=Din+kod+%C3%A4r+4+7+2+9

The second example sends "Din kod är" followed by the digits 4 7 2 9. Writing digits with spaces between them makes the voice read them one by one.

Reports are delivered via HTTP GET to the account's configured DLR URL with query parameters TransactionId, Result, StatusCode, ProgressTime (listened seconds), Sequence (always end, the final report), and ExternalReferenceId. The format is identical to the previous Txt2Voice service:

Result=1&StatusCode=1&Sequence=end&TransactionId=fa7a2ada-d3d4-4c93-a125-fec9ecd84f92&ProgressTime=24

If the DLR URL is temporarily unreachable, delivery is retried for a limited period; if it stays unreachable, delivery is suspended and the reports are no longer sent (you can still query each transaction's outcome with GET /v1/messages/{transaction_id}). Keep your DLR endpoint reachable and returning a 2xx status. For an unanswered call the report arrives after the last call reattempt (up to ~5 minutes after submission).