Audio Understand
curl --request POST \
--url https://kymaapi.com/v1/audio/understand \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"question": "<string>",
"model": "<string>",
"duration_sec": 123
}
'import requests
url = "https://kymaapi.com/v1/audio/understand"
payload = {
"question": "<string>",
"model": "<string>",
"duration_sec": 123
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({question: '<string>', model: '<string>', duration_sec: 123})
};
fetch('https://kymaapi.com/v1/audio/understand', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://kymaapi.com/v1/audio/understand",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'question' => '<string>',
'model' => '<string>',
'duration_sec' => 123
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://kymaapi.com/v1/audio/understand"
payload := strings.NewReader("{\n \"question\": \"<string>\",\n \"model\": \"<string>\",\n \"duration_sec\": 123\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://kymaapi.com/v1/audio/understand")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"question\": \"<string>\",\n \"model\": \"<string>\",\n \"duration_sec\": 123\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://kymaapi.com/v1/audio/understand")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"question\": \"<string>\",\n \"model\": \"<string>\",\n \"duration_sec\": 123\n}"
response = http.request(request)
puts response.read_body{
"answer": "<string>",
"model": "<string>",
"billing.duration_source": "<string>",
"billing.cost_usd": 123
}Audio Understand
Audio scene Q&A. Hears tone, music, SFX, language, speaker emotion. Custom Kyma endpoint, no OpenAI equivalent.
POST
/
v1
/
audio
/
understand
Audio Understand
curl --request POST \
--url https://kymaapi.com/v1/audio/understand \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"question": "<string>",
"model": "<string>",
"duration_sec": 123
}
'import requests
url = "https://kymaapi.com/v1/audio/understand"
payload = {
"question": "<string>",
"model": "<string>",
"duration_sec": 123
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({question: '<string>', model: '<string>', duration_sec: 123})
};
fetch('https://kymaapi.com/v1/audio/understand', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://kymaapi.com/v1/audio/understand",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'question' => '<string>',
'model' => '<string>',
'duration_sec' => 123
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://kymaapi.com/v1/audio/understand"
payload := strings.NewReader("{\n \"question\": \"<string>\",\n \"model\": \"<string>\",\n \"duration_sec\": 123\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://kymaapi.com/v1/audio/understand")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"question\": \"<string>\",\n \"model\": \"<string>\",\n \"duration_sec\": 123\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://kymaapi.com/v1/audio/understand")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"question\": \"<string>\",\n \"model\": \"<string>\",\n \"duration_sec\": 123\n}"
response = http.request(request)
puts response.read_body{
"answer": "<string>",
"model": "<string>",
"billing.duration_source": "<string>",
"billing.cost_usd": 123
}Audio understanding is retired. As of 2026-10-08 no model is served on this endpoint:
gemini-3-flash-audio, its only model, had no customer request in the preceding 90 days. The endpoint still exists; a request returns 404 model_not_found, and nothing is charged. The audio-understand alias was removed with it. For speech-to-text, /v1/audio/transcriptions is live. This page is no longer in the docs navigation; it records how the endpoint behaved.curl -X POST https://kymaapi.com/v1/audio/understand \
-H "Authorization: Bearer $KYMA_API_KEY" \
-F "file=@clip.mp3" \
-F "model=gemini-3-flash-audio" \
-F "question=Describe the mood, music, and any background sounds."
When to use this vs transcribe
| Question | Endpoint |
|---|---|
| What words are spoken? | /v1/audio/transcriptions |
| Is the speaker angry, calm, tired? | this endpoint |
| What kind of music is playing? | this endpoint |
| Are there sirens, applause, traffic in the background? | this endpoint |
| What language is being spoken? | either |
transcribe. If it depends on how something sounds, this endpoint was the one.
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:"gemini-3-flash-audio"
gemini-3-flash-audio, retired 2026-10-08. The audio-understand alias was removed the same day.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.
{
"answer": "The speaker is reciting a line in a deep, slow voice with theatrical gravitas. There is a low ambient drone underneath but no music. The mood is somber and resolute — a deity's vow rather than a casual remark.",
"model": "gemini-3-flash-audio",
"billing": {
"duration_sec": 5,
"billable_minutes": 1,
"cost_usd": 0.002592,
"balance_usd": 41.468,
"duration_source": "upstream_usage"
}
}
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
Nothing is charged: no model is served. Whilegemini-3-flash-audio was served it cost $0.002592 a minute, billed per minute and rounded up, on the length of the audio plus your question.
Errors
| Status | error.type | error.code | When |
|---|---|---|---|
400 | invalid_request | — | Missing file or question field |
400 | invalid_request_error | invalid_parameter | question is over 4,000 characters (param: "question"). Not charged |
400 | invalid_request_error | invalid_parameter | file is empty, 0 bytes (param: "file"). Not charged |
400 | invalid_request | not_an_audio_model | model is not an audio-understanding SKU |
401 | auth_error | — | Missing or invalid API key |
404 | not_found_error | model_not_found | The model is retired; since 2026-10-08 that is every request, including one with no model. Not charged |
402 | billing_error | insufficient_credits | Insufficient credits |
408 | timeout | audio_upload_timeout | The upload did not finish arriving in time, usually a slow connection. Retry |
413 | invalid_request | — | File > 25 MB |
415 | invalid_request | unsupported_audio_type | The file is not one of the supported formats. Not charged |
429 | rate_limit_error | audio_concurrent_limit | Your tier’s audio concurrency cap is reached. Retry-After: 5 |
502 | provider_error | audio_understand_failed | The model call failed |
503 | provider_error | — | Audio understanding is not available right now. Retry shortly |
Examples
Mood and music brief for a video clip
curl -X POST https://kymaapi.com/v1/audio/understand \
-H "Authorization: Bearer $KYMA_API_KEY" \
-F "file=@scene.mp3" \
-F "model=gemini-3-flash-audio" \
-F "question=Describe the mood, dominant instruments, tempo, and any background sounds."
Speaker emotion check
curl -X POST https://kymaapi.com/v1/audio/understand \
-H "Authorization: Bearer $KYMA_API_KEY" \
-F "file=@call-recording.mp3" \
-F "model=gemini-3-flash-audio" \
-F "question=Is the speaker frustrated, neutral, or pleased? One word, then a one-sentence justification."
See also
- Audio Transcriptions - speech-to-text
- Audio models - the audio models served today
watch-cli- open-source CLI that pairs this endpoint withtranscribeto give agents full audio understanding from any social video URL