API reference
Speech, transcription and images (OpenAI-compatible)
Text-to-speech, speech-to-text, translation and image generation on the OpenAI-compatible routes, with how each is measured, billed and limited.
Speech, audio and image models are called on the same OpenAI-compatible routes and with the same key as chat models, so the official OpenAI SDKs work with only the base URL and key changed:
| Variable | Value |
|---|---|
API_KEY | sk_… (your project API key) |
API_BASE_URL | https://api.hayonix.ai/v1 |
INFERENCE_BASE_URL | https://api.hayonix.ai/v1 |
| Method | Path | Model type | What it does |
|---|---|---|---|
POST | /v1/audio/speech | text_to_speech | Speech from text, streamed as it is produced |
POST | /v1/audio/transcriptions | speech_to_text | Text from an audio upload, with timings |
POST | /v1/audio/translations | speech_to_text | English text from audio in any language |
POST | /v1/images/generations | image | Images from a prompt |
Text to speech
The body has model, input (up to 4096 characters), voice, and optionally response_format (mp3 by default, or opus, aac, flac, wav, pcm) and speed (0.25–4). The voices a model offers are listed in its capabilities.voices; OpenAI's voice names are accepted where the model has a voice of that name. The answer is the audio itself, sent as it is produced, so playback can start before synthesis ends. pcm is raw 16-bit mono samples at 24 kHz.
jq -n --arg model "$SPEECH_MODEL" '{
model: $model,
input: "The quick brown fox jumps over the lazy dog.",
voice: "af_heart",
response_format: "wav"
}' |
curl -sS --fail-with-body "$INFERENCE_BASE_URL/audio/speech" \
-H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" -d @- \
-o speech.wavTranscription and translation
Upload the audio as multipart/form-data (file, up to 25 MB, in any common format) with model, and optionally language (an ISO-639-1 code; detected when omitted), prompt (words or style to expect), temperature and response_format: json (the default), text, srt, vtt or verbose_json. verbose_json adds the language, the duration and timed segments; add timestamp_granularities[]=word for word timings as well. Translations take the same form (without language) and always answer in English.
curl -sS --fail-with-body "$INFERENCE_BASE_URL/audio/transcriptions" \
-H "Authorization: Bearer $API_KEY" \
-F model="$TRANSCRIPTION_MODEL" -F file=@speech.wav \
-F response_format=verbose_json -F 'timestamp_granularities[]=word' |
jq -r '"transcript: \(.text)", (.words[] | " \(.start)s \(.word)"), "billed: \(.usage.seconds) s of audio"'The usage object of a transcription ({"type": "duration", "seconds": …}) is the audio length you are billed for.
Images
The body has model, prompt, and optionally n (1–4), size (WIDTHxHEIGHT, sides of 256–2048 pixels in steps of 64, at most 2 megapixels; auto is the model's default), quality (hd or high run twice the model's standard steps), output_format (png, jpeg, webp) and output_compression. Images come back base64-encoded in data[].b64_json. Image links (response_format: "url") are not offered: such a request is refused with unsupported_parameter.
status=$(jq -n --arg model "$IMAGE_MODEL" '{
model: $model,
prompt: "a lighthouse on a cliff at dusk, watercolour",
size: "512x512",
n: 1
}' |
curl -sS "$INFERENCE_BASE_URL/images/generations" \
-H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" -d @- \
-o image.json -w '%{http_code}')
if [ "$status" = 200 ]; then
jq -r '.data[0].b64_json' image.json | base64 -d > image.png
echo "image: saved image.png"
fiImage models run on GPU capacity; when none is serving a model, its requests get 503 model_unavailable (the playground shows this as "not being served").
Billing
Each route bills one measured quantity at the model's price (pricing.units on the model):
| Route | Billed per | Measured by |
|---|---|---|
| Speech | Input character (Unicode code point) | The input you send, counted before synthesis |
| Transcription, translation | Millisecond of audio (prices are shown per minute) | The length the model decoded from your file |
| Images | Image, by size tier (up to 512×512, up to 1024×1024, up to 2 megapixels) | The images returned; an hd image counts twice |
Before the model is called, each request reserves credit for its upper bound: the input's characters, the images asked for, or the longest audio the upload could contain (read from a WAV header, otherwise from the file size, at most two hours). An organization without enough credit gets 402 before anything runs. When the request ends, the reservation settles for what was measured and the rest is released. A speech stream you stop early is charged for the characters the delivered audio covers (an estimate, marked as such in usage); an image request you abandon before it answers is not charged.
These routes cannot be used in batches, and these models are served on the shared fleet only, not on dedicated endpoints.
Limits
Requests per minute are limited per organization and model as for every model; the second limit counts the route's own unit per minute, reported in headers named after it: x-ratelimit-*-audio-seconds (transcription and translation), x-ratelimit-*-characters (speech) and x-ratelimit-*-images (images). See Limits and quotas.
Errors
Errors use the standard envelope. Beyond the inference errors:
| Status | code | When |
|---|---|---|
| 400 | invalid_content_type, invalid_multipart | A transcription that is not a well-formed multipart/form-data upload |
| 400 | missing_parameter, invalid_value | A required field is missing or out of range (param names it) |
| 400 | unsupported_parameter | A parameter this model cannot honour (streaming transcription, instructions, image url responses, …) |
| 400 | route_not_available_for_batch | One of these routes in a batch |
| 413 | payload_too_large | An upload over the size limit |