Text-to-Speech

Endpoint

POST /v1/audio/speech

OpenAI-compatible text-to-speech. Returns raw audio bytes (mp3, wav, or opus). Drop-in compatible with the OpenAI client.audio.speech.create() API.

Request Body

| Field | Type | Default | Description | |---|---|---|---| | model | string | "auto" | TTS model (see Providers). Use "auto" for health-aware routing. | | input | string | required | Text to speak. 1–10,000 chars. | | voice | string | "alloy" | One of alloy, echo, fable, onyx, nova, shimmer (Workers AI MeloTTS). | | response_format | string | "mp3" | One of "mp3", "wav", "opus", "flac". Actual formats served depend on provider. | | speed | number | 1.0 | Playback speed multiplier, 0.25–4.0. Honoured by providers that expose it. | | project_id | string | — | Body-level project tag. Alternative to x-gateway-project-id header. |

Required Header

| Header | Required | Description | |---|---|---| | Authorization: Bearer <GATEWAY_API_KEY> | yes | Gateway API key. | | x-gateway-project-id | yes (or body project_id) | 1–64 chars [a-zA-Z0-9._:-]. | | x-gateway-force-provider | no | Pin to workers_ai or groq. |

Providers

| Provider | Model | Voices | Status | |---|---|---|---| | Cloudflare Workers AI | @cf/myshell-ai/melotts | alloy, echo, fable, onyx, nova, shimmer | Enabled — no external key, uses Workers AI binding. | | Groq PlayAI | playai-tts | — | :warning: Disabled — Groq deprecated playai-tts on their free tier. Kept in the registry for future re-enablement but currently returns no_tts_provider. |

Response

Binary audio bytes. The Content-Type matches the served format:

| Format | Content-Type | |---|---| | mp3 | audio/mpeg | | wav | audio/wav | | opus | audio/opus |

Response Headers:

| Header | Description | |---|---| | x-gateway-provider | Provider that served the request (e.g. workers_ai). | | x-gateway-model | Exact model used. | | x-gateway-project-id | Echoes the resolved project id. |

Examples

curl

curl https://ai-gateway.sassmaker.com/v1/audio/speech \
  -H "Authorization: Bearer <GATEWAY_API_KEY>" \
  -H "x-gateway-project-id: my_project" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "auto",
    "input": "Hello world. This is the free AI gateway speaking.",
    "voice": "nova",
    "response_format": "mp3"
  }' \
  --output speech.mp3

JavaScript

const response = await fetch('https://ai-gateway.sassmaker.com/v1/audio/speech', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer <GATEWAY_API_KEY>',
    'x-gateway-project-id': 'my_project',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'auto',
    input: 'Hello world. This is the free AI gateway speaking.',
    voice: 'nova',
    response_format: 'mp3',
  }),
});

const audioBlob = await response.blob();
const url = URL.createObjectURL(audioBlob);
new Audio(url).play();

console.log('Served by:', response.headers.get('x-gateway-provider'));

OpenAI SDK

import OpenAI from 'openai';
import fs from 'fs';

const client = new OpenAI({
  baseURL: 'https://ai-gateway.sassmaker.com/v1',
  apiKey: '<GATEWAY_API_KEY>',
  defaultHeaders: { 'x-gateway-project-id': 'my_project' },
});

const mp3 = await client.audio.speech.create({
  model: 'auto',
  voice: 'shimmer',
  input: 'Hello from Claude and the free AI gateway.',
});

const buffer = Buffer.from(await mp3.arrayBuffer());
await fs.promises.writeFile('speech.mp3', buffer);

Error Codes

| Status | code | Meaning | |---|---|---| | 400 | invalid_project_id | Missing/invalid project_id. | | 502 | provider_error | All TTS candidates failed. Last upstream error is included in the message. | | 503 | no_tts_provider | No TTS binding/key configured. |