API Reference

Complete endpoint documentation

Generate Speech

POST/api/v1/tts🔒 Auth required

Submit text for speech synthesis. Returns immediately with a job_id for polling. Supports idempotency keys for safe retries.

Request Body

Field	Type	Description
text*	string	Text to convert (up to 500,000 characters)¹
voice*	string	Voice ID (e.g., google:en-US-Chirp3-HD-Charon)
model_type*	string	"premium" or "ultra"
speed	number	Speech rate 0.25-4.0 (default: 1.0)
format	string	"text" or "ssml" (default: text), "markup" only for Premium Chirp voices.
speaker_type	string	"single" or "multi" (ultra only)
voice_speaker_1	string	First speaker voice (multi only)
voice_speaker_2	string	Second speaker voice (multi only)
webhook_url	string	URL for completion callback (enterprise)
metadata	object	Custom metadata returned in webhook

Example Request

curl -X POST https://aitts.theproductivepixel.com/api/v1/tts \
  -H "Authorization: Bearer tts_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: unique-request-id" \
  -d '{
    "text": "Hello world!",
    "voice": "google:en-US-Chirp3-HD-Charon",
    "model_type": "premium"
  }'

Response

{
  "success": true,
  "data": {
    "job_id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "pending",
    "poll_url": "/api/v1/tts/550e8400-e29b-41d4-a716-446655440000",
    "chars_charged": 12
  }
}

¹ Ultra voices perform best with text under 4,000 characters.

💡 Tip: Use Idempotency-Key header for safe retries. Same key + same request = same response.

Get Job Status

GET/api/v1/tts/:job_id🔒 Auth required

Check the status of a TTS job. Poll until status is 'completed' or 'failed'.

Example Request

curl https://aitts.theproductivepixel.com/api/v1/tts/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer tts_YOUR_KEY"

Response

{
  "success": true,
  "data": {
    "job_id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "completed",
    "created_at": "2026-01-07T10:00:00.000Z",
    "audio_url": "https://storage.googleapis.com/...",
    "audio_url_expires_at": "2026-01-08T10:00:00.000Z",
    "chars_charged": 12
  }
}

Status values:

pending - Job queued
processing - Audio being generated
completed - Audio ready (check audio_url)
failed - Generation failed (check error)

List Voices

GET/api/v1/voices🔒 Auth required

Get available voices. Supports filtering and pagination. Use ETag for efficient caching.

Request Body

Field	Type	Description
language	query	Filter by language (e.g., en-US)
model_type	query	Filter by "premium" or "ultra"
provider	query	Filter by provider (e.g., google)
limit	query	Max results (default: all, max: 500)
offset	query	Pagination offset

Example Request

curl "https://aitts.theproductivepixel.com/api/v1/voices?language=en-US&model_type=premium" \
  -H "Authorization: Bearer tts_YOUR_KEY"

Response

{
  "success": true,
  "data": {
    "voices": [
      {
        "voice_id": "google:en-US-Chirp3-HD-Charon",
        "provider": "google",
        "language": "en-US",
        "name": "en-US-Chirp3-HD-Charon",
        "model_type": "premium",
        "gender": "male",
        "sample_url": null,
        "supports_ssml": false,
        "supports_markup": true,
        "supports_multispeaker": false
      }
    ],
    "total_voices": 150,
    "voices_version": "a1b2c3d4e5f6"
  }
}

Get Usage

GET/api/v1/usage🔒 Auth required

Get your API usage statistics. Response varies by account type.

Example Request

curl https://aitts.theproductivepixel.com/api/v1/usage \
  -H "Authorization: Bearer tts_YOUR_KEY"

Response

// Standard account
{
  "success": true,
  "data": {
    "account_type": "standard",
    "credits_balance": 50.00
  }
}

// Enterprise account
{
  "success": true,
  "data": {
    "account_type": "enterprise",
    "period_start": "2026-01-01T00:00:00.000Z",
    "period_end": "2026-01-31T23:59:59.999Z",
    "characters_used": 5000000,
    "quota_limit": 30000000,
    "quota_remaining": 25000000,
    "request_count": 1250,
    "overage_rate_per_1m": 38
  }
}

Error Responses

All errors follow this format:

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable description"
  }
}

Code	HTTP	Description
UNAUTHORIZED	401	Invalid or missing API key
FORBIDDEN	403	Key lacks required permissions
JOB_NOT_FOUND	404	Job ID not found or not owned by you
VALIDATION_ERROR	400	Invalid request parameters
INVALID_VOICE	400	Voice ID format invalid
INSUFFICIENT_CREDITS	402	Not enough credits for request
QUOTA_EXCEEDED	402	Enterprise quota exceeded
RATE_LIMIT_EXCEEDED	429	Too many requests
MAINTENANCE	503	API temporarily disabled. Retry after 300s.
IDEMPOTENCY_MISMATCH	422	Same key used with different request
GENERATION_FAILED	500	Audio generation failed

Rate Limits

Tier	Requests	Window
Free	10	15 minutes
Premium	100	15 minutes
Enterprise	1,000	15 minutes

Rate limit headers included in all responses: X-RateLimit-Remaining, X-RateLimit-Reset

Back to Documentation