Qwen-Audio-ASR-Filetrans non-real-time speech recognition Python SDK

​

Prerequisites

• You have activated the service and Obtain an API key. Please Configure API key as an environment variable instead of hardcoding it in your code to prevent security risks caused by code leakage.

• Install the latest DashScope SDK.

​

Quick start

• Submit the task asynchronously and wait synchronously: after submitting the task, block the current thread until the task finishes and return the recognition result.
• Submit the task asynchronously and query the result asynchronously: after submitting the task, call the query interface to retrieve the result whenever you need it.

​

Submit asynchronously and wait synchronously

1. Call the Core resource (client.audio.asr) (jobs.create/transcribe) and set the Request parameters.

2. Call the Core resource (client.audio.asr) (jobs.wait, or the one-step transcribe) to wait synchronously for the task to finish. A task can be in one of the following states: PENDING, RUNNING, SUCCEEDED, and FAILED. While the task is in the PENDING or RUNNING state, the wait interface blocks. When the task reaches the SUCCEEDED or FAILED state, the wait interface stops blocking and returns the task result. jobs.wait returns the final-state Job (for the structure, see Response).

import os
import json
import dashscope

# If you have not configured the API key in an environment variable, replace the following line with your own API key: api_key="sk-xxx"
# Singapore (ap-southeast-1). For another region, replace ap-southeast-1 in the URL.
# API keys are region-specific. See https://docs.qwencloud.com/developer-guides/getting-started/regions
client = dashscope.Client(
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    base_url="https://ap-southeast-1.maas.qwencloudapi.com/api/v1",
)

# Submit the recorded file transcription task and wait synchronously for the task to complete
job = client.audio.asr.transcribe(
    ['{YOUR_AUDIO_URL}'],
    model='qwen-audio-3.1-asr-flash-filetrans',
)

print(json.dumps(job.model_dump(), indent=4, ensure_ascii=False))
print('transcription done!')

​

Submit asynchronously and query the result asynchronously

1. Call the Core resource (client.audio.asr) (jobs.create/transcribe) and set the Request parameters.

2. Call Core resource (client.audio.asr) (jobs.fetch) in a loop until you get the final task result. When the task status is SUCCEEDED or FAILED, stop polling and process the result. jobs.fetch returns a Job (for the structure, see Response).

import os
import json
import dashscope

# If you have not configured the API key in an environment variable, replace the following line with your own API key: api_key="sk-xxx"
# Singapore (ap-southeast-1). For another region, replace ap-southeast-1 in the URL.
# API keys are region-specific. See https://docs.qwencloud.com/developer-guides/getting-started/regions
client = dashscope.Client(
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    base_url="https://ap-southeast-1.maas.qwencloudapi.com/api/v1",
)

# Submit the recorded file transcription task
job = client.audio.asr.jobs.create(
    model='qwen-audio-3.1-asr-flash-filetrans',
    file_urls=['{YOUR_AUDIO_URL}'],
)

# Poll the task until the final result is returned
while True:
    if job.status == 'SUCCEEDED' or job.status == 'FAILED':
        break
    job = client.audio.asr.jobs.fetch(job.task_id)

print(json.dumps(job.model_dump(), indent=4, ensure_ascii=False))
print('transcription done!')

​

Service endpoints

import os
import dashscope

# Singapore (ap-southeast-1). For another region, replace ap-southeast-1 in the URL.
# API keys are region-specific. See https://docs.qwencloud.com/developer-guides/getting-started/regions
client = dashscope.Client(
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    base_url="https://ap-southeast-1.maas.qwencloudapi.com/api/v1",
)

• API keys differ across regions. Make sure you use the API key for the corresponding region.
• The endpoint is set when constructing the Client and affects all API calls made through that Client.

​

Request parameters

vocab = {"Zhang San": 5, "Li Si": 5}
job = client.audio.asr.jobs.create(
    model="qwen-audio-3.1-asr-flash-filetrans",
    file_urls=['{YOUR_AUDIO_URL}'],
    parameters={"vocabulary": vocab},
)

​

Response

​

Job

{
    "task_id": "00000000-0000-0000-0000-000000000001",
    "status": "PENDING",
    "submitted_at": "2026-10-29 10:00:00.000",
    "scheduled_at": null,
    "finished_at": null,
    "output": {
        "task_id": "00000000-0000-0000-0000-000000000001",
        "task_status": "PENDING",
        "submit_time": "2026-10-29 10:00:00.000"
    },
    "usage": null
}

​

Job.output

{
    "task_id": "00000000-0000-0000-0000-000000000001",
    "task_status": "PENDING",
    "submit_time": "2026-10-29 10:00:00.000"
}

{
    "task_id": "00000000-0000-0000-0000-000000000001",
    "task_status": "RUNNING",
    "submit_time": "2026-10-29 10:00:00.000",
    "scheduled_time": "2026-10-29 10:00:00.100"
}

{
    "task_id": "00000000-0000-0000-0000-000000000001",
    "task_status": "SUCCEEDED",
    "submit_time": "2026-10-29 10:00:00.000",
    "scheduled_time": "2026-10-29 10:00:00.100",
    "end_time": "2026-10-29 10:00:01.000",
    "results": [
        {
            "file_url": "{YOUR_AUDIO_URL}",
            "transcription_url": "{TRANSCRIPTION_URL}",
            "subtask_status": "SUCCEEDED"
        }
    ]
}

{
    "task_id": "00000000-0000-0000-0000-000000000001",
    "task_status": "FAILED",
    "submit_time": "2026-10-29 10:00:00.000",
    "scheduled_time": "2026-10-29 10:00:00.100",
    "end_time": "2026-10-29 10:00:01.000",
    "code": "SERVER_ERROR",
    "file_url": "{YOUR_AUDIO_URL}",
    "subtask_status": "FAILED",
    "results": [
        {
            "file_url": "{YOUR_AUDIO_URL}",
            "subtask_status": "FAILED",
            "results": []
        }
    ]
}

​

Recognition result description

{
    "file_url":"{YOUR_AUDIO_URL}",
    "properties":{
        "audio_format":"pcm_s16le",
        "channels":[
            0
        ],
        "original_sampling_rate":16000,
        "original_duration_in_milliseconds":3834
    },
    "transcripts":[
        {
            "channel_id":0,
            "content_duration_in_milliseconds":3720,
            "text":"Hello world, this is Alibaba Speech Lab.",
            "sentences":[
                {
                    "begin_time":100,
                    "end_time":3820,
                    "text":"Hello world, this is Alibaba Speech Lab.",
                    "sentence_id":1,
                    "speaker_id":0, //This field is displayed only when automatic speaker diarization is enabled
                    "words":[
                        {
                            "begin_time":100,
                            "end_time":596,
                            "text":"Hello ",
                            "punctuation":""
                        },
                        {
                            "begin_time":596,
                            "end_time":844,
                            "text":"world",
                            "punctuation":", "
                        }
                        // Other content is omitted here
                    ]
                }
            ]
        }
    ]
}

​

Key interfaces

​

Core resource (client.audio.asr)

def transcribe(
  file_urls: List[str],
  *,
  model: str = "qwen-audio-3.1-asr-flash-filetrans",
  parameters: Optional[Dict[str, Any]] = None,
  phrase_id: Optional[str] = None,
  timeout: float = 86400.0,
  submit_timeout: Optional[float] = None,
  poll_interval: float = 1.0,
  max_interval: float = 8.0,
  api_key: Optional[str] = None,
  workspace: Optional[str] = None,
) -> Job

def wait(
  job: Union[Job, str],
  *,
  poll_interval: float = 1.0,
  max_interval: float = 8.0,
  timeout: float = 86400.0,
  api_key: Optional[str] = None,
  workspace: Optional[str] = None,
) -> Job

def fetch(
  task_id: str,
  *,
  timeout: Optional[float] = None,
  api_key: Optional[str] = None,
  workspace: Optional[str] = None,
) -> Job

​

jobs.create

def create(
  *,
  model: str,
  file_urls: List[str],
  parameters: Optional[Dict[str, Any]] = None,
  phrase_id: Optional[str] = None,
  timeout: Optional[float] = None,
  api_key: Optional[str] = None,
  workspace: Optional[str] = None,
) -> Job

​

Error codes

{
    "task_id": "7bac899c-06ec-4a79-8875-xxxxxxxxxxxx",
    "task_status": "SUCCEEDED",
    "submit_time": "2024-12-16 16:30:59.170",
    "scheduled_time": "2024-12-16 16:30:59.204",
    "end_time": "2024-12-16 16:31:02.375",
    "results": [
        {
            "file_url": "{YOUR_AUDIO_URL}",
            "code": "InvalidFile.DownloadFailed",
            "message": "The audio file cannot be downloaded.",
            "subtask_status": "FAILED"
        }
    ],
    "task_metrics": {
        "TOTAL": 1,
        "SUCCEEDED": 0,
        "FAILED": 1
    }
}

​

FAQ

​

Features

​

Q: Is Base64-encoded audio supported?

​

Q: How do I make an audio file available at a publicly accessible URL?

• The temporary URL is valid for 48 hours and cannot be used after it expires. Do not use it in a production environment.
• The API for obtaining an upload credential is limited to 100 QPS and does not support scaling out. Do not use it in production environments, high-concurrency scenarios, or stress testing scenarios.
• For production environments, use a stable storage service such as OSS to ensure long-term file availability and avoid rate limiting issues.

​

Q: How long does it take to get the recognition result?

​

Troubleshooting

​

Q: Polling never returns a result?

​

Q: Why can't the speech be recognized (no recognition result)?

ffprobe -v error -show_entries format=format_name -show_entries stream=codec_name,sample_rate,channels -of default=noprint_wrappers=1 input.xxx