Endpoint reference

Speech generation

POST /v1/audio/speech · Synchronous

This route accepts strict JSON. Unknown fields, malformed values, wrong-operation keys, and package settings outside the locked configuration are rejected before provider execution.

Required headers

Header	Value	Notes
`Authorization`	`Bearer $URTHEPRODUCT_API_KEY`	Required. Must be sent from a trusted server.
`Idempotency-Key`	8–128 safe characters	Required on POST. Reuse only for retries of the same logical request.
`Content-Type`	`application/json`	Required on POST.

Request fields

Field	Type	Required	Rules
`text`	string	Yes	1–24,000 characters of authorized script.
`voice`	string	No	1–80 characters; approved voice only.
`language`	language tag	No	Two/three-letter language with optional region.
`output_format`	enum	No	mp3 or wav.

Request example

curl "https://urtheproduct.com/v1/audio/speech" \
+  -X POST \
+  -H "Authorization: Bearer $URTHEPRODUCT_API_KEY" \
+  -H "Idempotency-Key: logical-request-001" \
+  -H "Content-Type: application/json" \
+  -d '{  "text": "Welcome to the product tour.",  "voice": "approved_default",  "language": "en",  "output_format": "mp3"}'

{
  "text": "Welcome to the product tour.",
  "voice": "approved_default",
  "language": "en",
  "output_format": "mp3"
}

Success response

{
  "id": "usage-event-id",
  "object": "generation",
  "operation": "audio.speech",
  "output": { "url": "short-lived-private-signed-url", "expires_at": "..." },
  "usage": { "charged_units": 1, "remaining_units": 59 }
}

Operation-specific behavior

Voice, language, duration, and format must be approved in the package.
Do not submit impersonation, unauthorized cloning, or scripts you lack rights to use.

Failures and retries

Schema failures return 422 validation_error without charging quota. Wrong scope returns 403 forbidden. Rate/concurrency pressure returns 429 rate_limited. Provider safety pauses return 503 provider_unavailable. Follow the error and retry table and reuse the same idempotency key for the same logical request.