BRASILTradução de apoio para consulta. Código e identificadores técnicos preservados. Consultar referência original ↗
Qwen-ASR - Transcrever áudio
Enviar transcrição assíncrona
Processo assíncrono
A transcrição assíncrona segue um padrão de envio de pesquisa:
- Enviar uma tarefa: Envie a solicitação. O servidor retorna um
task_id. - Obtenha o resultado: pesquise a API de resultado com o
task_idaté que a tarefa seja concluída.
###SDK
- Ligue
async_call()(Python) ouasyncCall()(Java) para enviar. O método retorna um objeto de tarefa com umtask_id. - Ligue
fetch()com o objeto de tarefa outask_id. O SDK pesquisa automaticamente até que a tarefa seja concluída ou expire.
###API REST
- Use este endpoint para enviar uma tarefa e obter um
task_id. - Consulte o resultado com o
task_id.
Formatos de áudio
Os URLs dos arquivos de áudio devem ser acessíveis publicamente.
Cada faixa de áudio em channel_id é cobrado separadamente. Por exemplo, [0, 1] para um único arquivo incorre em duas cobranças.
OpenAPI
openapi: 3.1.0
info:
title: Qwen-ASR Audio File Recognition API
description: API reference for Qwen-ASR audio file recognition. Supports OpenAI-compatible, DashScope synchronous, and DashScope asynchronous protocols.
version: 1.0.0
servers:
- url: https://maas.qwencloudapi.com
description: Singapore
security:
- bearer: []
paths:
/api/v1/services/audio/asr/transcription:
post:
operationId: asrDashScopeAsync
summary: Create transcription task
description: Create an async audio transcription task.
security:
- bearer: []
parameters:
- name: X-DashScope-Async
in: header
required: true
description: Must be set to `enable` for asynchronous task submission.
schema:
type: string
enum:
- enable
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/AsyncASRRequest"
responses:
"200":
description: Task created successfully
content:
application/json:
schema:
$ref: "#/components/schemas/AsyncASRSubmitResponse"
x-codeSamples:
- lang: bash
label: cURL
source: |-
curl --location --request POST 'https://maas.qwencloudapi.com/api/v1/services/audio/asr/transcription' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header "Content-Type: application/json" \
--header "X-DashScope-Async: enable" \
--data '{
"model": "qwen3-asr-flash-filetrans",
"input": {
"file_url": "https://dashscope.oss-cn-beijing.aliyuncs.com/audios/welcome.mp3"
},
"parameters": {
"channel_id":[
0
],
"enable_itn": false
}
}'
- lang: python
label: Python
source: |-
import requests
import json
import os
url = "https://maas.qwencloudapi.com/api/v1/services/audio/asr/transcription"
# If you have not configured the environment variable, replace the following line with your API key: DASHSCOPE_API_KEY = "sk-xxx"
DASHSCOPE_API_KEY = os.getenv("DASHSCOPE_API_KEY")
headers = {
"Authorization": f"Bearer {DASHSCOPE_API_KEY}",
"Content-Type": "application/json",
"X-DashScope-Async": "enable"
}
payload = {
"model": "qwen3-asr-flash-filetrans",
"input": {
"file_url": "https://dashscope.oss-cn-beijing.aliyuncs.com/audios/welcome.mp3"
},
"parameters": {
"channel_id": [0],
# "language": "zh",
"enable_itn": False
}
}
response = requests.post(url, headers=headers, data=json.dumps(payload))
if response.status_code == 200:
print(f"task_id: {response.json()['output']['task_id']}")
else:
print("task failed!")
print(response.json())
- lang: java
label: Java
source: |-
import com.google.gson.Gson;
import com.google.gson.annotations.SerializedName;
import okhttp3.*;
import java.io.IOException;
public class Main {
private static final String API_URL = "https://maas.qwencloudapi.com/api/v1/services/audio/asr/transcription";
public static void main(String[] args) {
// If you have not configured the environment variable, replace the following line with your API key: String apiKey = "sk-xxx"
String apiKey = System.getenv("DASHSCOPE_API_KEY");
OkHttpClient client = new OkHttpClient();
Gson gson = new Gson();
String payloadJson = """
{
"model": "qwen3-asr-flash-filetrans",
"input": {
"file_url": "https://dashscope.oss-cn-beijing.aliyuncs.com/audios/welcome.mp3"
},
"parameters": {
"channel_id": [0],
"enable_itn": false
}
}
""";
RequestBody body = RequestBody.create(payloadJson, MediaType.get("application/json; charset=utf-8"));
Request request = new Request.Builder()
.url(API_URL)
.addHeader("Authorization", "Bearer " + apiKey)
.addHeader("Content-Type", "application/json")
.addHeader("X-DashScope-Async", "enable")
.post(body)
.build();
try (Response response = client.newCall(request).execute()) {
if (response.isSuccessful() && response.body() != null) {
String respBody = response.body().string();
// Parse JSON with Gson.
ApiResponse apiResp = gson.fromJson(respBody, ApiResponse.class);
if (apiResp.output != null) {
System.out.println("task_id: " + apiResp.output.taskId);
} else {
System.out.println(respBody);
}
} else {
System.out.println("task failed! HTTP code: " + response.code());
if (response.body() != null) {
System.out.println(response.body().string());
}
}
} catch (IOException e) {
e.printStackTrace();
}
}
static class ApiResponse {
@SerializedName("request_id")
String requestId;
Output output;
}
static class Output {
@SerializedName("task_id")
String taskId;
@SerializedName("task_status")
String taskStatus;
}
}
components:
securitySchemes:
bearer:
type: http
scheme: bearer
description: DashScope API key. Get your API key from [QwenCloud console](https://home.qwencloud.com/api-keys).
schemas:
OpenAIASRRequest:
type: object
required:
- model
- messages
properties:
model:
type: string
description: The model name. Only applicable to Qwen3-ASR-Flash.
examples:
- qwen3-asr-flash
messages:
type: array
description: The list of messages.
items:
type: object
required:
- role
- content
properties:
role:
type: string
description: The role of the message sender.
enum:
- system
- user
content:
type: array
description: The content of the message.
items:
type: object
properties:
type:
type: string
description: Set to `input_audio` for audio input.
enum:
- input_audio
input_audio:
type: object
description: The audio input object.
properties:
data:
type: string
description: "The audio to recognize. Supports URLs of Internet-accessible files and Base64-encoded data (Data URL format: `data:<mediatype>;base64,<data>`)."
text:
type: string
description: "Context for customized recognition (System Message only). Provide background text, entity vocabularies, and other reference information. Length limit: 10,000 tokens."
asr_options:
type: object
description: Specifies whether to enable certain features. Not a standard OpenAI parameter — pass it through `extra_body` when using an OpenAI SDK.
properties:
language:
type: string
description: If you know the language of the audio, specify it to improve recognition accuracy. Specify only one language. If the audio contains multiple languages, do not specify this parameter.
enum:
- zh
- yue
- en
- ja
- de
- ko
- ru
- fr
- pt
- ar
- it
- es
- hi
- id
- th
- tr
- uk
- vi
- cs
- da
- fil
- fi
- is
- ms
- no
- pl
- sv
enable_itn:
type: boolean
description: Specifies whether to enable Inverse Text Normalization (ITN). Applicable only to Chinese and English audio.
default: false
stream:
type: boolean
description: Specifies whether to use streaming output. We recommend setting this to `true` to improve responsiveness and reduce the risk of timeouts.
default: false
stream_options:
type: object
description: Configuration for streaming output. Takes effect only when `stream` is `true`.
properties:
include_usage:
type: boolean
description: Specifies whether to include token consumption information in the last data block of the response.
default: false
OpenAIASRResponse:
type: object
properties:
id:
type: string
description: The unique identifier for this call.
example: chatcmpl-487abe5f-d4f2-9363-a877-xxxxxxx
choices:
type: array
description: The output information of the model.
items:
type: object
properties:
finish_reason:
type: string
description: "`null` during generation. `stop` when finished naturally. `length` when output exceeded maximum length."
enum:
- stop
- length
- null
example: stop
index:
type: integer
description: The index of the current object in the `choices` array.
example: 0
message:
type: object
description: The message object output by the model.
properties:
role:
type: string
description: The role of the output message. Always `assistant`.
example: assistant
content:
type: string
description: The speech recognition result text.
example: Welcome to QwenCloud.
annotations:
type: array
description: Output annotation information, such as language and emotion.
items:
type: object
properties:
type:
type: string
description: Set to `audio_info`.
example: audio_info
language:
type: string
description: The language of the recognized audio.
enum:
- zh
- yue
- en
- ja
- de
- ko
- ru
- fr
- pt
- ar
- it
- es
- hi
- id
- th
- tr
- uk
- vi
- cs
- da
- fil
- fi
- is
- ms
- no
- pl
- sv
example: zh
emotion:
type: string
description: The emotion of the recognized audio.
enum:
- surprised
- neutral
- happy
- sad
- disgusted
- angry
- fearful
example: neutral
example:
- emotion: neutral
language: zh
type: audio_info
example:
- finish_reason: stop
index: 0
message:
annotations:
- emotion: neutral
language: zh
type: audio_info
content: Welcome to QwenCloud.
role: assistant
created:
type: integer
description: The UNIX timestamp (in seconds) when the request was created.
example: 1767683986
model:
type: string
description: The model used for this request.
example: qwen3-asr-flash
object:
type: string
description: Always `chat.completion`.
example: chat.completion
usage:
type: object
description: Token consumption information.
properties:
completion_tokens:
type: integer
description: The number of tokens in the model's output.
example: 12
completion_tokens_details:
type: object
properties:
text_tokens:
type: integer
description: The number of tokens in the model's output text.
example: 12
prompt_tokens:
type: integer
description: The number of tokens in the input.
example: 42
prompt_tokens_details:
type: object
properties:
audio_tokens:
type: integer
description: The length of the input audio in tokens. Each second of audio converts to 25 tokens. Audio shorter than 1 second is counted as 1 second.
example: 42
text_tokens:
type: integer
description: Ignore this parameter.
example: 0
seconds:
type: integer
description: The duration of the audio in seconds.
example: 1
total_tokens:
type: integer
description: The total number of tokens in the input and output.
example: 54
examples:
- summary: Non-streaming response
value:
choices:
- finish_reason: stop
index: 0
message:
annotations:
- emotion: neutral
language: zh
type: audio_info
content: Welcome to QwenCloud.
role: assistant
created: 1767683986
id: chatcmpl-487abe5f-d4f2-9363-a877-xxxxxxx
model: qwen3-asr-flash
object: chat.completion
usage:
completion_tokens: 12
completion_tokens_details:
text_tokens: 12
prompt_tokens: 42
prompt_tokens_details:
audio_tokens: 42
text_tokens: 0
seconds: 1
total_tokens: 54
DashScopeASRRequest:
type: object
required:
- model
- input
properties:
model:
type: string
description: The model name. Only applicable to Qwen3-ASR-Flash.
examples:
- qwen3-asr-flash
input:
type: object
required:
- messages
description: The input object.
properties:
messages:
type: array
description: The list of messages.
items:
type: object
required:
- role
- content
properties:
role:
type: string
description: The role of the message sender.
enum:
- system
- user
content:
type: array
description: The content of the message.
items:
type: object
properties:
audio:
type: string
description: The audio to recognize (User Message). Supports URLs, Base64-encoded data, and local file paths (SDK only).
text:
type: string
description: "Context for customized recognition (System Message). Length limit: 10,000 tokens."
parameters:
type: object
description: Additional parameters.
properties:
asr_options:
type: object
description: Specifies whether to enable certain features. Supported only by Qwen3-ASR-Flash.
properties:
language:
type: string
description: If you know the language of the audio, specify it to improve recognition accuracy. Specify only one language. If the audio contains multiple languages, do not specify this parameter.
enum:
- zh
- yue
- en
- ja
- de
- ko
- ru
- fr
- pt
- ar
- it
- es
- hi
- id
- th
- tr
- uk
- vi
- cs
- da
- fil
- fi
- is
- ms
- no
- pl
- sv
enable_itn:
type: boolean
description: Specifies whether to enable Inverse Text Normalization (ITN). Applicable only to Chinese and English audio.
default: false
DashScopeASRResponse:
type: object
properties:
request_id:
type: string
description: The unique identifier for this call. The Java SDK returns this as `requestId`.
example: 568e2bf0-d6f2-97f8-9f15-a57b11dc6977
output:
type: object
description: The call result.
properties:
choices:
type: array
description: The model output, included when `result_format` is `message`.
items:
type: object
properties:
finish_reason:
type: string
description: "`null` during generation. `stop` when finished naturally. `length` when output exceeded maximum length."
enum:
- stop
- length
- null
example: stop
message:
type: object
description: The message object output by the model.
properties:
role:
type: string
description: The role of the output message. Always `assistant`.
example: assistant
content:
type: array
description: The output message content.
items:
type: object
properties:
text:
type: string
description: The speech recognition result text.
example: Welcome to QwenCloud.
example:
- text: Welcome to QwenCloud.
annotations:
type: array
description: Output annotation information.
items:
type: object
properties:
type:
type: string
description: Set to `audio_info`.
example: audio_info
language:
type: string
description: The language of the recognized audio.
enum:
- zh
- yue
- en
- ja
- de
- ko
- ru
- fr
- pt
- ar
- it
- es
- hi
- id
- th
- tr
- uk
- vi
- cs
- da
- fil
- fi
- is
- ms
- no
- pl
- sv
example: zh
emotion:
type: string
description: The emotion of the recognized audio.
enum:
- surprised
- neutral
- happy
- sad
- disgusted
- angry
- fearful
example: neutral
example:
- language: zh
type: audio_info
emotion: neutral
example:
- finish_reason: stop
message:
annotations:
- language: zh
type: audio_info
emotion: neutral
content:
- text: Welcome to QwenCloud.
role: assistant
usage:
type: object
description: Token consumption information.
properties:
input_tokens_details:
type: object
properties:
text_tokens:
type: integer
description: Ignore this parameter.
example: 0
output_tokens_details:
type: object
properties:
text_tokens:
type: integer
description: The length of the recognized text output in tokens.
example: 6
seconds:
type: integer
description: The duration of the audio in seconds.
example: 1
examples:
- summary: DashScope synchronous response
value:
output:
choices:
- finish_reason: stop
message:
annotations:
- language: zh
type: audio_info
emotion: neutral
content:
- text: Welcome to QwenCloud.
role: assistant
usage:
input_tokens_details:
text_tokens: 0
output_tokens_details:
text_tokens: 6
seconds: 1
request_id: 568e2bf0-d6f2-97f8-9f15-a57b11dc6977
AsyncASRRequest:
type: object
required:
- model
- input
properties:
model:
type: string
description: The model name. Only applicable to Qwen3-ASR-Flash-Filetrans.
examples:
- qwen3-asr-flash-filetrans
input:
type: object
required:
- file_url
description: The input object.
properties:
file_url:
type: string
description: The URL of the audio file to be recognized. Must be accessible over the Internet.
parameters:
type: object
description: Additional parameters.
properties:
language:
type: string
description: If you know the language of the audio, specify it to improve recognition accuracy.
enum:
- zh
- yue
- en
- ja
- de
- ko
- ru
- fr
- pt
- ar
- it
- es
- hi
- id
- th
- tr
- uk
- vi
- cs
- da
- fil
- fi
- is
- ms
- no
- pl
- sv
enable_itn:
type: boolean
description: Specifies whether to enable Inverse Text Normalization (ITN). Applicable only to Chinese and English audio.
default: false
enable_words:
type: boolean
description: "Controls whether to return word-level timestamps. When `false`, returns sentence-level timestamps. When `true`, returns word-level timestamps (supported for Chinese, English, Japanese, Korean, German, French, Spanish, Italian, Portuguese, and Russian). Also affects sentence segmentation: `false` uses VAD-based segmentation, `true` uses VAD and punctuation-based segmentation."
default: false
text:
type: string
description: "Context for customized recognition. Provide background text, entity vocabularies, and other reference information. Length limit: 10,000 tokens."
channel_id:
type: array
items:
type: integer
description: "Indexes of audio tracks to recognize in a multi-track audio file. Index starts from 0. Default: `[0]`. Each specified track is billed separately."
default:
- 0
AsyncASRSubmitResponse:
type: object
properties:
request_id:
type: string
description: The unique identifier for this call.
example: 92e3decd-0c69-47a8-xxxxxxxxxxxx
output:
type: object
properties:
task_id:
type: string
description: The task ID. Use this to query the task result.
example: 8fab76d0-0eed-4d20-xxxxxxxxxxxx
task_status:
type: string
description: The task status.
enum:
- PENDING
- RUNNING
- SUCCEEDED
- FAILED
- UNKNOWN
example: PENDING
examples:
- summary: Task submitted
value:
request_id: 92e3decd-0c69-47a8-xxxxxxxxxxxx
output:
task_id: 8fab76d0-0eed-4d20-xxxxxxxxxxxx
task_status: PENDING
AsyncASRGetResponse:
type: object
properties:
request_id:
type: string
description: The unique identifier for this call.
example: 1dca6c0a-0ed1-4662-aa39-xxxxxxxxxxxx
output:
type: object
properties:
task_id:
type: string
description: The task ID.
example: 8fab76d0-0eed-4d20-929f-xxxxxxxxxxxx
task_status:
type: string
description: The task status.
enum:
- PENDING
- RUNNING
- SUCCEEDED
- FAILED
- UNKNOWN
example: SUCCEEDED
result:
type: object
description: The recognition result (available when task_status is SUCCEEDED).
properties:
transcription_url:
type: string
description: The download URL for the recognition result JSON file. Valid for 24 hours.
example: https://dashscope-result.oss-cn-beijing.aliyuncs.com/result.json?Expires=1761631066&OSSAccessKeyId=LTAIxxxx&Signature=xxxx
submit_time:
type: string
description: The time when the task was submitted.
example: 2025-10-27 13:57:45.948
scheduled_time:
type: string
description: The time when the task was scheduled (start of execution).
example: 2025-10-27 13:57:46.018
end_time:
type: string
description: The time when the task ended.
example: 2025-10-27 13:57:47.079
task_metrics:
type: object
description: Task metrics with subtask status statistics.
properties:
TOTAL:
type: integer
description: The total number of subtasks.
example: 1
SUCCEEDED:
type: integer
description: The number of successful subtasks.
example: 0
FAILED:
type: integer
description: The number of failed subtasks.
example: 0
code:
type: string
description: Error code. Returned only when the task fails.
example: FILE_403_FORBIDDEN
message:
type: string
description: Error message. Returned only when the task fails.
example: FILE_403_FORBIDDEN
usage:
type: object
description: Token consumption information.
properties:
seconds:
type: integer
description: The duration of the audio in seconds.
example: 3
examples:
- summary: SUCCEEDED
value:
request_id: 1dca6c0a-0ed1-4662-aa39-xxxxxxxxxxxx
output:
task_id: 8fab76d0-0eed-4d20-929f-xxxxxxxxxxxx
task_status: SUCCEEDED
submit_time: 2025-10-27 13:57:45.948
scheduled_time: 2025-10-27 13:57:46.018
end_time: 2025-10-27 13:57:47.079
result:
transcription_url: https://dashscope-result.oss-cn-beijing.aliyuncs.com/result.json?Expires=1761631066&OSSAccessKeyId=LTAIxxxx&Signature=xxxx
usage:
seconds: 3
- summary: RUNNING
value:
request_id: 6769df07-2768-4fb0-ad59-xxxxxxxxxxxx
output:
task_id: 9be1700a-0f8e-4778-be74-xxxxxxxxxxxx
task_status: RUNNING
submit_time: 2025-10-27 14:19:31.150
scheduled_time: 2025-10-27 14:19:31.233
task_metrics:
TOTAL: 1
SUCCEEDED: 0
FAILED: 0
- summary: FAILED
value:
request_id: 3d141841-858a-466a-9ff9-xxxxxxxxxxxx
output:
task_id: c58c7951-7789-4557-9ea3-xxxxxxxxxxxx
task_status: FAILED
submit_time: 2025-10-27 15:06:06.915
scheduled_time: 2025-10-27 15:06:06.967
end_time: 2025-10-27 15:06:07.584
code: FILE_403_FORBIDDEN
message: FILE_403_FORBIDDEN