Skip to main content
POST
Audio Understand
gemini-3-flash-audio, the model behind this endpoint, is a preview model (release_stage: "preview" on /v1/models).
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
required
Audio file. Supports mp3, wav, m4a, ogg, webm, flac. Max 25 MB inline (~30 minutes of mono 16kHz mp3).
string
required
Free-form text question about the audio, up to 4,000 characters. 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.
string
default:"audio-understand"
Either the alias audio-understand (recommended) or a pinned SKU like gemini-3-flash-audio. See Audio models.
number
Deprecated and ignored. Still accepted so existing clients keep working; billing comes from the audio itself (see Pricing).

Response

200 OK with the answer text and a Kyma billing block.
string
The model’s answer to your question.
string
The Kyma model SKU that served the request.
string
upstream_usage (billed from the input the model consumed: your audio and your question) or file_bound (the model reported no usage, so the file’s own length bound was billed).
number
Final cost charged for this request.

Pricing

Billed per minute, rounded up (a 30-second clip costs 1 minute = 0.002592).Thebilledlengthistheinputthemodelconsumed,measuredfromtheaudioitself,andyourquestioncountstowardit(averylongquestioncanaddaminute).Beforethecall,yourbalancemustcoverthefile′smaximumpossiblelength;ashortbalancegetsa‘402‘andnothingischarged.1−hourfile:0.002592). The billed length is the input the model consumed, measured from the audio itself, and your question counts toward it (a very long question can add a minute). Before the call, your balance must cover the file's maximum possible length; a short balance gets a `402` and nothing is charged. 1-hour file: 0.156.

Errors

Examples

Mood and music brief for a video clip

Speaker emotion check

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