Skip to content

API_REFERENCE.md

Latest commit

 

History

History
704 lines (554 loc) · 11 KB

API_REFERENCE.md

File metadata and controls

704 lines (554 loc) · 11 KB
Raw

API Reference

Complete API documentation for TextAudio TTS Platform.

Base URL: http://localhost:8000/api/v1

Interactive Documentation: http://localhost:8000/docs (Swagger UI)

Authentication

TextAudio uses session-based authentication with magic links.

Session Token

Include session token in requests:

Header:

X-Session-Token: your-session-token

Query Parameter:

?token=your-session-token

Endpoints

Files

Upload File

Extract text from document for TTS processing.

POST /api/v1/files/upload
Content-Type: multipart/form-data

Request:

file: <binary>

Response (200 OK):

{
  "file_id": "uuid",
  "filename": "document.pdf",
  "format": "pdf",
  "text": "Extracted text...",
  "language": "en",
  "confidence": 0.95,
  "token_count": 150,
  "size_bytes": 1024
}

Estimate Cost

Estimate tokens and cost for TTS conversion.

POST /api/v1/files/estimate
Content-Type: application/json

Request:

{
  "text": "Your text here",
  "tts_engine": "chatterbox",
  "use_voice_cloning": false
}

Response (200 OK):

{
  "token_count": 150,
  "estimated_cost": 2.50,
  "base_fee": 2.00,
  "token_fee": 0.50
}

Jobs

Create Job

Create a new TTS conversion job.

POST /api/v1/jobs
Content-Type: application/json
X-Session-Token: <token>

Request:

{
  "session_id": "uuid",
  "text": "Text to convert" or "file_id": "uuid",
  "tts_engine": "chatterbox",
  "language": "en",
  "audio_format": "mp3",
  "use_voice_cloning": false,
  "voice_sample_id": null,
  "playback_speed": 1.0,
  "auto_detect_language": true
}

Response (201 Created):

{
  "job_id": "uuid",
  "status": "pending",
  "estimated_cost": 2.50,
  "is_free": false,
  "token": "session-token"
}

Get Job Status

Retrieve job details.

GET /api/v1/jobs/{job_id}
X-Session-Token: <token>

Response (200 OK):

{
  "id": "uuid",
  "status": "completed",
  "progress": 100,
  "text": "Original text",
  "language": "en",
  "tts_engine": "chatterbox",
  "audio_format": "mp3",
  "audio_path": "/path/to/audio.mp3",
  "created_at": "2025-12-12T10:00:00Z",
  "completed_at": "2025-12-12T10:05:00Z",
  "error_message": null
}

Status Values:

  • pending: Job queued
  • processing: TTS in progress
  • completed: Audio ready
  • failed: Error occurred

Get Job Progress (SSE)

Real-time progress updates via Server-Sent Events.

GET /api/v1/jobs/{job_id}/progress
X-Session-Token: <token>

Response (text/event-stream):

event: progress
data: {"status": "processing", "progress": 25}

event: progress
data: {"status": "processing", "progress": 50}

event: progress
data: {"status": "completed", "progress": 100, "audio_url": "/api/v1/audio/download/{job_id}"}

List Jobs

Get all jobs for current session.

GET /api/v1/jobs/list
X-Session-Token: <token>

Response (200 OK):

{
  "jobs": [
    {
      "id": "uuid",
      "status": "completed",
      "text_preview": "First 100 characters...",
      "language": "en",
      "created_at": "2025-12-12T10:00:00Z"
    }
  ],
  "total": 10
}

Get Job Text

Retrieve full text for a job.

GET /api/v1/jobs/{job_id}/text
X-Session-Token: <token>

Response (200 OK):

{
  "job_id": "uuid",
  "text": "Full text content...",
  "language": "en",
  "token_count": 150
}

Delete Job

Delete a job and its audio file.

DELETE /api/v1/jobs/{job_id}
X-Session-Token: <token>

Response (200 OK):

{
  "message": "Job deleted successfully"
}

Bulk Delete Jobs

Delete multiple jobs.

POST /api/v1/jobs/bulk-delete
Content-Type: application/json
X-Session-Token: <token>

Request:

{
  "job_ids": ["uuid1", "uuid2", "uuid3"]
}

Response (200 OK):

{
  "deleted_count": 3,
  "failed": []
}

Audio

Download Audio

Download completed audio file.

GET /api/v1/audio/download/{job_id}
X-Session-Token: <token>

Response (200 OK):

Content-Type: audio/mpeg
Content-Disposition: attachment; filename="job-{job_id}.mp3"

<binary audio data>

Stream Audio

Stream audio file (supports range requests).

GET /api/v1/audio/stream/{job_id}
X-Session-Token: <token>

Response (200 OK or 206 Partial Content):

Content-Type: audio/mpeg
Accept-Ranges: bytes
Content-Length: 1024000

<binary audio data>

Preview

Generate Preview

Generate 2-sentence audio preview.

POST /api/v1/preview/generate
Content-Type: application/json
X-Session-Token: <token>

Request:

{
  "session_id": "uuid",
  "file_id": "uuid",
  "tts_engine": "chatterbox",
  "language": "en",
  "use_voice_cloning": false,
  "voice_sample_id": null,
  "playback_speed": 1.0
}

Response (200 OK):

{
  "preview_url": "/api/v1/preview/audio/{preview_id}",
  "duration_seconds": 5.2,
  "expires_at": "2025-12-12T10:05:00Z"
}

Rate Limit: 3 previews per session per hour

Get Preview Audio

Download preview audio.

GET /api/v1/preview/audio/{preview_id}
X-Session-Token: <token>

Response (200 OK):

Content-Type: audio/mpeg

<binary audio data>

Credits

Get Credit Balance

Retrieve current credit balance.

GET /api/v1/credits/balance
X-Session-Token: <token>

Response (200 OK):

{
  "balance": 10.50,
  "total_earned": 20.00,
  "total_spent": 9.50,
  "pending_credits": 1.00,
  "pending_reason": "retry_bonus_tier_1"
}

Get Credit History

List all credit transactions.

GET /api/v1/credits/history
X-Session-Token: <token>

Response (200 OK):

{
  "transactions": [
    {
      "id": 123,
      "amount": 5.00,
      "type": "earned",
      "description": "Promo code redemption",
      "created_at": "2025-12-12T10:00:00Z"
    },
    {
      "id": 124,
      "amount": -2.50,
      "type": "spent",
      "description": "TTS job completion",
      "created_at": "2025-12-12T10:05:00Z"
    }
  ],
  "total": 2
}

Transaction Types:

  • earned: Credits added
  • spent: Credits used
  • refunded: Credits returned
  • bonus: Retry bonus credits

Redeem Promo Code

Apply a promotional code.

POST /api/v1/credits/redeem-promo
Content-Type: application/json
X-Session-Token: <token>

Request:

{
  "code": "WELCOME2025"
}

Response (200 OK):

{
  "success": true,
  "credits_added": 5.00,
  "new_balance": 15.50,
  "message": "Promo code redeemed successfully"
}

Errors:

  • 404: Code not found
  • 410: Code expired or deactivated
  • 409: Code already used (for unique codes)

Manual Retry Job

Retry failed job with credit bonus.

POST /api/v1/credits/jobs/{job_id}/retry
X-Session-Token: <token>

Response (200 OK):

{
  "job_id": "uuid",
  "bonus_credits": 0.50,
  "retry_tier": 1,
  "remaining_retries": 26,
  "message": "Job queued for retry"
}

Refund Job

Request instant credit refund for job.

POST /api/v1/credits/jobs/{job_id}/refund
X-Session-Token: <token>

Response (200 OK):

{
  "refunded_amount": 2.50,
  "new_balance": 13.00,
  "message": "Credits refunded successfully"
}

Sessions

Create Session

Create new anonymous session.

POST /api/v1/sessions/create

Response (201 Created):

{
  "session_id": "uuid",
  "token": "session-token",
  "expires_at": "2025-12-19T10:00:00Z"
}

Link Email

Associate email with session (optional).

POST /api/v1/sessions/link-email
Content-Type: application/json

Request:

{
  "session_token": "token",
  "email": "user@example.com"
}

Response (200 OK):

{
  "message": "Email linked successfully",
  "email": "user@example.com"
}

Delete All Data

Delete session and all associated data.

POST /api/v1/sessions/delete-all-data
Content-Type: application/json
X-Session-Token: <token>

Response (200 OK):

{
  "message": "All data deleted successfully",
  "jobs_deleted": 5,
  "files_deleted": 5
}

Admin

Authentication: Requires X-Admin-Token header

Create Promo Code

POST /api/v1/admin/promo-codes
Content-Type: application/json
X-Admin-Token: <admin-token>

Request:

{
  "code": "WELCOME2025",
  "credit_amount": 5.00,
  "code_type": "unique_event",
  "max_uses": 100
}

Response (201 Created):

{
  "code": "WELCOME2025",
  "credit_amount": 5.00,
  "code_type": "unique_event",
  "max_uses": 100,
  "current_uses": 0,
  "active": true
}

List Promo Codes

GET /api/v1/admin/promo-codes
X-Admin-Token: <admin-token>

Response (200 OK):

{
  "codes": [
    {
      "code": "WELCOME2025",
      "credit_amount": 5.00,
      "max_uses": 100,
      "current_uses": 42,
      "active": true
    }
  ]
}

Deactivate Promo Code

DELETE /api/v1/admin/promo-codes/{code}
X-Admin-Token: <admin-token>

Response (200 OK):

{
  "message": "Promo code deactivated"
}

System

Health Check

GET /health

Response (200 OK):

{
  "status": "healthy",
  "service": "textaudio-api",
  "version": "1.0.0"
}

Detailed Health Check

GET /health/detailed

Response (200 OK):

{
  "status": "healthy",
  "dependencies": {
    "database": "healthy",
    "redis": "healthy",
    "chatterbox": "healthy",
    "text_processor": "healthy"
  },
  "uptime_seconds": 3600
}

Error Responses

Standard Error Format

{
  "detail": "Error message",
  "error_code": "VALIDATION_ERROR",
  "status_code": 400
}

Common Status Codes

  • 200 OK: Request successful
  • 201 Created: Resource created
  • 400 Bad Request: Invalid request data
  • 401 Unauthorized: Missing or invalid authentication
  • 403 Forbidden: Insufficient permissions
  • 404 Not Found: Resource not found
  • 409 Conflict: Resource conflict (e.g., duplicate)
  • 422 Unprocessable Entity: Validation error
  • 429 Too Many Requests: Rate limit exceeded
  • 500 Internal Server Error: Server error
  • 503 Service Unavailable: Service temporarily unavailable

Rate Limits

  • File Upload: 5 per hour per IP
  • Cost Estimation: 10 per hour per IP
  • Preview Generation: 3 per session per hour

Rate limit headers:

X-RateLimit-Limit: 5
X-RateLimit-Remaining: 3
X-RateLimit-Reset: 1639392000

Supported Languages

Arabic (ar), Danish (da), German (de), Greek (el), English (en), Spanish (es), Finnish (fi), French (fr), Hebrew (he), Hindi (hi), Italian (it), Japanese (ja), Korean (ko), Malay (ms), Dutch (nl), Norwegian (no), Polish (pl), Portuguese (pt), Russian (ru), Swedish (sv), Swahili (sw), Turkish (tr), Chinese (zh)

WebSocket/SSE Support

TextAudio uses Server-Sent Events (SSE) for real-time updates. WebSocket support is not currently implemented.

Related Documentation