Skip to content
Hayonix

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:

Environment variables
VariableValue
API_KEYsk_… (your project API key)
API_BASE_URLhttps://api.hayonix.ai/v1
INFERENCE_BASE_URLhttps://api.hayonix.ai/v1
MethodPathModel typeWhat it does
POST/v1/audio/speechtext_to_speechSpeech from text, streamed as it is produced
POST/v1/audio/transcriptionsspeech_to_textText from an audio upload, with timings
POST/v1/audio/translationsspeech_to_textEnglish text from audio in any language
POST/v1/images/generationsimageImages 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.wav

Transcription 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"
fi

Image 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):

RouteBilled perMeasured by
SpeechInput character (Unicode code point)The input you send, counted before synthesis
Transcription, translationMillisecond of audio (prices are shown per minute)The length the model decoded from your file
ImagesImage, 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:

StatuscodeWhen
400invalid_content_type, invalid_multipartA transcription that is not a well-formed multipart/form-data upload
400missing_parameter, invalid_valueA required field is missing or out of range (param names it)
400unsupported_parameterA parameter this model cannot honour (streaming transcription, instructions, image url responses, …)
400route_not_available_for_batchOne of these routes in a batch
413payload_too_largeAn upload over the size limit