Skip to main content
POST
Audio Understand
Synchronous endpoint for audio understanding beyond transcription. Upload a clip, ask a question — get back a natural-language answer that captures the parts a transcript loses: tone, mood, music style, ambient SFX, speaker emotion, language.

When to use this vs transcribe

A good rule of thumb: if the answer can be reconstructed from transcript text, use transcribe. If it depends on how something sounds, use audio-understand.

Request

multipart/form-data upload.
file
file
required
Audio file. Supports mp3, wav, m4a, ogg, webm, flac. Max 25 MB inline (~30 minutes of mono 16kHz mp3).
question
string
required
Free-form text question about the audio. Be specific about what you want — “What is the mood?” is fine, but “Describe the music style, BPM, and any background SFX” gets more useful answers.
model
string
default:"audio-understand"
Either the alias audio-understand (recommended) or a pinned SKU like gemini-3-flash-audio. See Audio models.
duration_sec
number
Optional duration hint in seconds. When supplied, billing rounds up from this exact value. When omitted, Kyma estimates duration from file size (assumes 32 kbps mp3) which can over-estimate for high-bitrate inputs. Pass the real duration when you have it — that’s what ffprobe gives you in one line.

Response

200 OK with the answer text and a Kyma billing block.
answer
string
The model’s answer to your question.
model
string
The Kyma model SKU that served the request.
billing.duration_source
string
Either caller_hint (you passed duration_sec) or size_estimate (Kyma estimated from file bytes).
billing.cost_usd
number
Final cost charged for this request.

Pricing

Billed per minute, rounded up (a 30-second clip costs 1 minute = 0.000648).1hourfile:0.000648). 1-hour file: 0.039.

Errors

Examples

Mood and music brief for a video clip

Speaker emotion check

Pass exact duration for accurate billing

See also

  • Audio Transcriptions - speech-to-text
  • Audio models - SKUs behind the audio-understand alias
  • watch-cli - open-source CLI that pairs this endpoint with transcribe to give agents full audio understanding from any social video URL