Speech-to-text

Buy a transcript of an audio file. The endpoint has the shape of the OpenAI transcriptions API, so an unchanged OpenAI client works. It also reads the JSON form that OpenRouter uses.

Only a deployment that is registered to transcribe can win the job. A chat deployment never wins one.

This job is not the same as Audio input. Audio input sends a clip to a chat model that can hear. This job returns the words of the clip.

Quickstart

curl https://router.inference.ai.exchange/v1/audio/transcriptions \
  -H "Authorization: Bearer sk-liquid-..." \
  -F model=whisper-1 \
  -F [email protected] \
  -F response_format=verbose_json

from openai import OpenAI

client = OpenAI(base_url="https://router.inference.ai.exchange/v1", api_key="sk-liquid-...")

with open("meeting.mp3", "rb") as audio:
    transcript = client.audio.transcriptions.create(model="whisper-1", file=audio)
print(transcript.text)

Find a model

A control works only when an offer for the model declares it. Read the model card before you send diarize or keyterms.

• GET /v1/models?kind=transcription lists the models as cards, with kind audio_transcription and modality transcription.
• parameters lists diarize and keyterms when an offer declared them. A name that is not a key is not supported, so omit it.
• pricing gives the price of one second of audio.

See Modalities. If no offer declared a control that you sent, the answer is 400 unsupported_parameter, and param names the feature, such as transcription.diarize.

Controls

diarize and keyterms are offer features. language, timestamp_granularities and the audio limits are matched against what an offer registered.

Speakers and key terms

diarize and keyterms are offer features: transcription.diarize and transcription.keyterms. Only an offer that declared the feature can win a request that sets the field.

curl https://router.inference.ai.exchange/v1/audio/transcriptions \
  -H "Authorization: Bearer sk-liquid-..." \
  -F model=<model> \
  -F [email protected] \
  -F response_format=verbose_json \
  -F diarize=true \
  -F 'keyterms[]=Liquid Inference' \
  -F 'keyterms[]=nano-USD'

• With diarize, each segment has a speaker, such as speaker_0. Without it, a segment has no speaker. diarize without verbose_json gets 400 invalid_request.
• With keyterms, the transcript spells each term as you gave it. A list of more than 100 terms, or a term over 100 characters, gets 400 invalid_request.

Audio by link

Send an https:// link in url and the exchange fetches the file.

{
  "model": "<model>",
  "input_references": [{ "type": "audio", "url": "https://example.com/call.wav" }]
}

• The link must use https and name a public host. The exchange refuses an IP address, a host in its own network, a port that is not the default port, a login in the link, and a redirect to any of these.
• The file has the same limits as a file that you send: 25 MB and two hours.
• The fetch stops after 20 seconds and three redirects.
• A link that the exchange cannot read gets 400, and the message says why. It does not repeat the link.

Audio limits

The exchange reads WAV, FLAC, MP3, Ogg, WebM, M4A and AAC from the bytes of the file. It does not trust the name or the format field.

• A file can be 25 MB and two hours at most.
• A file with no readable length gets 400, because the exchange cannot fix a cap without it.
• An offer can also limit the container, the length (max_duration_seconds) and the size (max_bytes). A request that breaks a limit does not reach that offer.

Response

json returns the text, the usage and the exchange block.

{
  "text": "Welcome to the meeting.",
  "usage": { "type": "duration", "seconds": 4 },
  "exchange": { "...": "..." }
}

verbose_json adds language, duration (the seconds that the exchange measured), segments and words. A segment or a word is present only when you asked for that granularity. A segment has id, start, end and text, and a speaker with diarize.

{ "id": 0, "start": 0.0, "end": 3.4, "text": "Welcome to the meeting.", "speaker": "speaker_0" }

text returns plain text. Its exchange block comes back as JSON in the x-liquid-exchange response header.

Billing

The price is for each second of audio. The exchange reads the length from the file, so the cap is known before dispatch. It is exactly the most that you can pay.

The provider meters the seconds that it worked on. You pay that figure, never more than the cap.

Request parameters

Send multipart/form-data with the audio in file, or JSON with the audio in input_references.

* Send file or input_references. Send one audio entry only.

stream is not supported. The transcript comes whole.

Errors

Next steps

• Audio input: send audio to a chat model.
• Speech: turn text into speech.
• Modalities: the map of all modalities.