Skip to main content
Specialized models

Audio understanding (Qwen3-Omni-Captioner)

Qwen3-Omni-Captioner, an open-source model built on Qwen3-Omni, generates detailed audio descriptions—covering speech, ambient sounds, music, and sound effects—without prompts. It identifies speaker emotions, musical elements (style, instruments), and sensitive information for audio analysis, security audits, intent recognition, and video editing. This model does not support fine-grained acoustic feature analysis such as timbre, pitch, or tone/intonation.

Supported models

  • Singapore
  • China (Beijing)

Model

Context window

Max input

Max output

Input cost

Output cost

Free quota

(Note)

(tokens)

(per 1M tokens)

qwen3-omni-30b-a3b-captioner

65,536

32,768

32,768

$3.81

$3.06

1 million tokens

Valid for 90 days after activating Model Studio

Token conversion rule for audio: Total tokens = Audio duration (in seconds) × 12.5. If the audio duration is less than one second, it is counted as one second.

Getting started

Prerequisites Qwen3-Omni-Captioner is available through API only. Console-based testing is not supported. These code samples analyze online audio via a URL, not local files. Learn how to pass local files and audio file limits.
  • OpenAI compatible
  • DashScope
  • Python
  • Node.js
  • curl
import os
from openai import OpenAI

client = OpenAI(
    # API keys differ by region. To get an API key, see https://www.alibabacloud.com/help/en/model-studio/get-api-key
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    # The following URL is for the Singapore region. Replace {WorkspaceId} with your actual workspace ID. For Beijing, use the URL shown in the China (Beijing) tab.
    base_url="https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1",
)

completion = client.chat.completions.create(
    model="qwen3-omni-30b-a3b-captioner",
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "input_audio",
                    "input_audio": {
                        "data": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20240916/xvappi/%E8%A3%85%E4%BF%AE%E5%99%AA%E9%9F%B3.wav"
                    }
                }
            ]
        }
    ]
)
print(completion.choices[0].message.content)
The audio clip begins with a sudden, loud, metallic clanking that dominates the soundstage, immediately indicating an industrial or workshop environment. The clanking is rhythmic, consistent, and has a sharp, resonant quality, suggestive of metal tools striking metal surfaces-likely a hammer, wrench, or similar instrument being used on a hard metal object. The sound is harsh and slightly distorted, with audible clipping on each impact, likely due to the microphone’s proximity and the high volume of the sound.
As the initial clanking fades, a male voice enters, speaking in Mandarin Chinese with a tone of exasperation and complaint. His voice is clear, close-mic’d, and free from distortion. He says: “Oh my, how can I possibly work quietly like this?”. His intonation is conversational, informal, and marked by a rising, questioning inflection, typical of everyday speech rather than performance or formal address. The accent is standard Putonghua, with no strong regional markers, suggesting he is a native Mandarin speaker from the northern or central regions of China.
During the speaker’s utterance, the metallic clanking resumes, overlapping with his voice. The timing and nature of these sounds indicate the speaker is directly reacting to the ongoing noise-likely caused by another person in the same space. The environment is acoustically “dry” with minimal echo, implying a small or medium-sized room with sound-absorbing materials, further supporting the workshop or industrial setting. There are no other background noises, music, or ambient sounds, and no evidence of a public or commercial space.
The recording quality is moderate: the microphone captures both the low-end thuds and the sharp metallic transients, but the loud clanking causes digital clipping, resulting in a harsh, “crunchy” distortion during the impacts. The speaker’s voice, however, remains clear and intelligible. The overall impression is of a candid, real-world interaction-possibly a worker or office employee complaining about an interruption in a noisy environment.
In summary, the audio depicts a Mandarin-speaking man in a workshop or industrial setting, reacting with frustration to ongoing metallic clanking that disrupts his work. The recording is informal, clear, and grounded in a context of manual labor or technical work, with no evidence of scripted performance, music, or extraneous activity.

How it works

  • Single-turn interaction: Each request is independent. Multi-turn conversation is not supported.
  • Fixed task: Generates English audio descriptions only. Instructions such as system messages cannot change behavior, output format, or content focus.
  • Audio input only: Accepts audio only—no text prompts. The message parameter format is fixed.
    messages=[
            {
                "role": "user",
                "content": [
                    {
                        "type": "input_audio",
                        "input_audio": {
                            "data": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20240916/xvappi/%E8%A3%85%E4%BF%AE%E5%99%AA%E9%9F%B3.wav"
                        }
                    }
                ]
            }
        ]
    

Streaming output

Streaming output returns results incrementally as they are generated, reducing wait time.
  • OpenAI compatible
  • DashScope
Set stream to true to enable streaming output.
Python
import os
from openai import OpenAI

client = OpenAI(
    # API keys for the Singapore and Beijing regions are different. To obtain an API key, see https://www.alibabacloud.com/help/en/model-studio/get-api-key
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    # The following URL is for the Singapore region. Replace {WorkspaceId} with your actual workspace ID. For Beijing, use the URL shown in the China (Beijing) tab.
    base_url="https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1",
)

completion = client.chat.completions.create(
    model="qwen3-omni-30b-a3b-captioner",
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "input_audio",
                    "input_audio": {
                        "data": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20240916/xvappi/%E8%A3%85%E4%BF%AE%E5%99%AA%E9%9F%B3.wav"
                    }
                }
            ]
        }
    ],
    stream=True,
    stream_options={"include_usage": True},

)
for chunk in completion:
    # If stream_options.include_usage is True, the choices field of the last chunk is an empty list and should be skipped. You can get the token usage from chunk.usage.
    if chunk.choices and chunk.choices[0].delta.content != "":
        print(chunk.choices[0].delta.content,end="")

Pass local file (Base64 encoding or file path)

Two methods to upload local files:
  • Use Base64 encoding
  • Direct file path (Recommended for greater transmission stability)
Upload methods:
  • Pass by file path
  • Pass by Base64 encoding
Pass the file path directly. Supported by DashScope Python and Java SDKs only, not HTTP. Path formats vary by SDK and OS.

Specify the file path

System

SDK

Input file path

Example

Linux or macOS

Python SDK

file://{absolute_path_of_the_file}

file:///home/images/test.mp3

Java SDK

Windows operating system

Python SDK

file://{absolute_path_of_the_file}

file://D:/images/test.mp3

Java SDK

file:///{absolute_path_of_the_file}

file:///D:/images/test.mp3

Limits:
  • File path is recommended for transmission stability. Base64 also works for files under 1 MB.
  • When passing by file path, audio files must be under 10 MB.
  • When using Base64, the encoded string must be under 10 MB. Note: Base64 increases file size.
  • Pass by file path
  • Pass by Base64 encoding
File path passing is supported by DashScope Python and Java SDKs only, not HTTP.
Python
import dashscope
import os

# The following URL is for the Singapore region. Replace {WorkspaceId} with your actual workspace ID. For Beijing, use the URL shown in the China (Beijing) tab.
dashscope.base_http_api_url = 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1'

# Replace ABSOLUTE_PATH/welcome.mp3 with the absolute path of your local audio file.
# The full path of the local file must be prefixed with file:// to ensure a valid path, for example: file:///home/images/test.mp3
audio_file_path = "file://ABSOLUTE_PATH/welcome.mp3"
messages = [
    {
        "role": "user",
        # Pass the file path prefixed with file:// in the audio parameter.
        "content": [{"audio": audio_file_path}],
    }
]

response = dashscope.MultiModalConversation.call(
    # API keys differ by region. To get an API key, see https://www.alibabacloud.com/help/en/model-studio/get-api-key
    # If you have not configured the environment variable, replace the following line with your Model Studio API key: api_key="sk-xxx"
    api_key=os.getenv('DASHSCOPE_API_KEY'),
    model="qwen3-omni-30b-a3b-captioner",
    messages=messages)

print("Output:")
print(response["output"]["choices"][0]["message"].content[0]["text"])

API reference

For Qwen3-Omni-Captioner parameters, see Text Generation.

Error codes

If the model call fails and returns an error message, see Error codes for resolution.

FAQ

How to compress an audio file to the required size?

# Basic conversion command (universal template)
# -i: Specifies the input file path. Example: input.mp3

# -b:a: Sets the audio bitrate.
  # Common values: 64 kbps (low quality, for voice and low-bandwidth streaming), 128k (medium quality, for general audio and podcasts), 192 kbps (high quality, for music and broadcasting).
  # A higher bitrate results in better audio quality and a larger file size.

# -ar: Sets the audio sample rate, which is the number of samples per second.
 # Common values: 8000 Hz, 22050 Hz, 44100 Hz (standard sample rate).
 # A higher sample rate results in a larger file size.

# -ac: Sets the number of audio channels. Common values: 1 (mono), 2 (stereo). Mono files are smaller.

# -y: Overwrites the output file if it exists (no value needed). # output.mp3: Specifies the output file path.

ffmpeg -i input.mp3 -b:a 128k -ar 44100 -ac 1 output.mp3 -y

Limitations

Audio file limits:
  • Duration: Up to 40 minutes.
  • Number of files: Only one audio file is supported per request.
  • File formats: AMR, WAV (CodecID: GSM_MS), WAV (PCM), 3GP, 3GPP, AAC, and MP3.
  • File input methods: Public URL, Base64 encoding, or local file path.
  • File size:
    • Public URL: No more than 1 GB.
    • File path: The audio file must be smaller than 10 MB.
    • Base64 encoding: The encoded string must be under 10 MB. Pass local file.
    To compress a file, see How to compress an audio file to the required size?
Token Plan
Statistics and Monitoring
Support