Back to Details

dashscope

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

DashScope

DashScope

Requires 
DASHSCOPE_API_KEY
in 
.env
. Get one at https://dashscope.aliyun.com/.
需要在
.env
文件中配置
DASHSCOPE_API_KEY
。可前往https://dashscope.aliyun.com/获取该密钥。

Current API

当前API

CRITICAL: DashScope's 
/compatible-mode/v1/
only supports 
/chat/completions
and 
/embeddings
. Image generation, TTS, and ASR all use DashScope-native endpoints — not OpenAI-compatible paths.
All three tools use 
Authorization: Bearer $DASHSCOPE_API_KEY
.
重要提示： DashScope的
/compatible-mode/v1/
接口仅支持
/chat/completions
和
/embeddings
。图像生成、文本转语音（TTS）和自动语音识别（ASR）均使用DashScope原生接口，而非兼容OpenAI的路径。
这三个工具均使用
Authorization: Bearer $DASHSCOPE_API_KEY
进行身份验证。

Image Generation

图像生成

text
POST https://dashscope.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation
  • Model: 
    qwen-image-2.0-pro
    (default), 
    qwen-image-max
    , 
    wan2.7-image
    , 
    z-image-turbo
  • Body: 
    {model, input: {messages: [{role: "user", content: [{text: "prompt"}]}]}, parameters: {size: "W*H", n, prompt_extend, watermark}}
  • Size format uses asterisk: 
    "1024*1024"
    not 
    "1024x1024"
  • Response: 
    output.choices[0].message.content[0].image
    (URL, valid ~24h) — must download separately
text
POST https://dashscope.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation
  • 模型：
    qwen-image-2.0-pro
    （默认）、
    qwen-image-max
    、
    wan2.7-image
    、
    z-image-turbo
  • 请求体：
    {model, input: {messages: [{role: "user", content: [{text: "prompt"}]}]}, parameters: {size: "W*H", n, prompt_extend, watermark}}
  • 尺寸格式使用星号分隔： 
    "1024*1024"
    ，而非
    "1024x1024"
  • 响应：
    output.choices[0].message.content[0].image
    （图片URL，有效期约24小时）——需单独下载

Text-to-Speech

文本转语音（TTS）

text
POST https://dashscope.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation
Same endpoint as image gen, different body.
  • Model: 
    qwen3-tts-flash
    (default), 
    qwen3-tts-instruct-flash
    , 
    qwen-tts-2025-05-22
  • Body: 
    {model, input: {text, voice: "Cherry", language_type: "Auto"}}
  • Response: 
    output.audio.url
    (WAV, valid ~24h) — must download separately
text
POST https://dashscope.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation
与图像生成使用相同的接口，但请求体不同。
  • 模型：
    qwen3-tts-flash
    （默认）、
    qwen3-tts-instruct-flash
    、
    qwen-tts-2025-05-22
  • 请求体：
    {model, input: {text, voice: "Cherry", language_type: "Auto"}}
  • 响应：
    output.audio.url
    （WAV格式音频URL，有效期约24小时）——需单独下载

ASR with Word-Level Timestamps

带词级时间戳的自动语音识别（ASR）

text
POST https://dashscope.aliyuncs.com/api/v1/services/audio/asr/transcription
Header: X-DashScope-Async: enable
  • Model: 
    qwen3-asr-flash-filetrans
    (NOT 
    qwen3-asr-flash
    — the sync version has no word timestamps)
  • Body: 
    {model, input: {file_url: "https://public-url/audio.mp3"}, parameters: {enable_words: true, language_hints: ["zh","en"]}}
  • Returns 
    task_id
    → poll 
    GET /api/v1/tasks/{task_id}
    until 
    SUCCEEDED
    → download 
    output.result.transcription_url
    → JSON with 
    transcripts[].sentences[].words[]
  • Timestamps in 
    begin_time
    /
    end_time
    are in milliseconds — the tool normalizes to seconds
text
POST https://dashscope.aliyuncs.com/api/v1/services/audio/asr/transcription
Header: X-DashScope-Async: enable
  • 模型：
    qwen3-asr-flash-filetrans
    （注意：不是
    qwen3-asr-flash
    ，同步版本不支持词级时间戳）
  • 请求体：
    {model, input: {file_url: "https://public-url/audio.mp3"}, parameters: {enable_words: true, language_hints: ["zh","en"]}}
  • 返回
    task_id
    → 轮询
    GET /api/v1/tasks/{task_id}
    直到状态为
    SUCCEEDED
    → 下载
    output.result.transcription_url
    对应的文件 → 得到包含
    transcripts[].sentences[].words[]
    的JSON数据
  • begin_time
    /
    end_time
    中的时间戳单位为毫秒——工具会自动将其转换为秒

OpenMontage Usage

OpenMontage 使用方法

Image via selector

通过选择器生成图像

python
from tools.graphics.image_selector import ImageSelector

result = ImageSelector().execute({
    "preferred_provider": "dashscope",
    "prompt": "一只猫坐在沙发上",
    "output_path": "projects/my-video/assets/images/cat.png",
})
python
from tools.graphics.image_selector import ImageSelector

result = ImageSelector().execute({
    "preferred_provider": "dashscope",
    "prompt": "一只猫坐在沙发上",
    "output_path": "projects/my-video/assets/images/cat.png",
})

TTS via selector

通过选择器生成TTS

python
from tools.audio.tts_selector import TTSSelector

result = TTSSelector().execute({
    "preferred_provider": "dashscope",
    "text": "如果 AI 真的会改变未来，普通人到底该怎么参与？",
    "voice": "Cherry",
    "output_path": "projects/my-video/assets/audio/narration.wav",
})
python
from tools.audio.tts_selector import TTSSelector

result = TTSSelector().execute({
    "preferred_provider": "dashscope",
    "text": "如果 AI 真的会改变未来，普通人到底该怎么参与？",
    "voice": "Cherry",
    "output_path": "projects/my-video/assets/audio/narration.wav",
})

ASR directly (word timestamps for subtitles)

直接调用ASR（用于生成带时间戳的字幕）

python
from tools.analysis.dashscope_asr import DashscopeAsr

result = DashscopeAsr().execute({
    "audio_url": "https://example.com/narration.wav",
    "output_path": "projects/my-video/assets/audio/transcription.json",
})
python
from tools.analysis.dashscope_asr import DashscopeAsr

result = DashscopeAsr().execute({
    "audio_url": "https://example.com/narration.wav",
    "output_path": "projects/my-video/assets/audio/transcription.json",
})

result.data["words"] is a flat list of {text, begin_time_seconds, end_time_seconds}

result.data["words"] 是一个扁平化列表，每个元素包含{text, begin_time_seconds, end_time_seconds}

undefined
undefined

Recommended Workflow

推荐工作流程

  1. Image: Generate a sample first. Check 
    prompt_extend: true
    (default) — DashScope rewrites your prompt for better results. Disable if you need literal prompt adherence.
  2. TTS: Generate a 10-15 second sample before full narration. Approve voice and pacing before committing to full generation.
  3. ASR: Audio must be at a publicly accessible URL. Upload to any public host (S3, etc.) first. Local paths are rejected with a clear error.
  4. Subtitles: Build from 
    result.data["words"]
    — each word has 
    begin_time_seconds
    and 
    end_time_seconds
    . Group words into caption phrases by language semantics, not fixed character count.
  1. 图像生成：先生成样图。默认开启
    prompt_extend: true
    ——DashScope会自动优化你的提示词以获得更好效果。如果需要严格遵循原提示词，可禁用该选项。
  2. 文本转语音：在生成完整旁白前，先生成10-15秒的样音。确认音色和语速合适后，再生成完整内容。
  3. 自动语音识别：音频文件必须位于可公开访问的URL。需先上传至公共存储服务（如S3等）。本地路径会被直接拒绝并返回明确错误。
  4. 字幕生成：基于
    result.data["words"]
    构建字幕——每个单词都包含
    begin_time_seconds
    和
    end_time_seconds
    。需根据语义将单词组合成字幕短语，而非按固定字符数分组。

Parameters

参数说明

Image (
dashscope_image
)

图像生成参数（
dashscope_image
）

  • prompt
    (required): text prompt
  • model
    : default 
    qwen-image-2.0-pro
  • size
    : default 
    "1024*1024"
    — asterisk separator, not "x"
  • n
    : 1-6 images
  • negative_prompt
    : things to avoid (max 500 chars)
  • prompt_extend
    : default 
    true
    — auto-rewrite prompt for better results
  • watermark
    : default 
    false
  • seed
    : for reproducibility
  • prompt
    （必填）：文本提示词
  • model
    ：默认值为
    qwen-image-2.0-pro
  • size
    ：默认值为
    "1024*1024"
    ——使用星号分隔，而非"x"
  • n
    ：生成图像数量，范围1-6
  • negative_prompt
    ：需要避免的内容（最多500字符）
  • prompt_extend
    ：默认值为
    true
    ——自动优化提示词以获得更好效果
  • watermark
    ：默认值为
    false
  • seed
    ：用于生成可复现的结果

TTS (
dashscope_tts
)

文本转语音参数（
dashscope_tts
）

  • text
    (required): text to synthesize (max 600 chars for qwen3-tts-flash)
  • model
    : default 
    qwen3-tts-flash
  • voice
    : default 
    "Cherry"
    — other voices: 
    "Ethan"
    , 
    "Chelsie"
    , etc.
  • language_type
    : default 
    "Auto"
    — 
    "Chinese"
    , 
    "English"
    , 
    "Japanese"
    , 
    "Korean"
  • instructions
    : natural language delivery instructions (only for 
    qwen3-tts-instruct-flash
    )
  • text
    （必填）：需要合成的文本（qwen3-tts-flash模型最多支持600字符）
  • model
    ：默认值为
    qwen3-tts-flash
  • voice
    ：默认值为
    "Cherry"
    ——其他可选音色包括
    "Ethan"
    、
    "Chelsie"
    等
  • language_type
    ：默认值为
    "Auto"
    ——可选值包括
    "Chinese"
    、
    "English"
    、
    "Japanese"
    、
    "Korean"
  • instructions
    ：自然语言风格指令（仅适用于
    qwen3-tts-instruct-flash
    模型）

ASR (
dashscope_asr
)

自动语音识别参数（
dashscope_asr
）

  • audio_url
    (required): must be publicly accessible URL
  • model
    : 
    qwen3-asr-flash-filetrans
    (only model that supports word timestamps)
  • language_hints
    : default 
    ["zh", "en"]
  • enable_words
    : default 
    true
    — required for word-level timestamps
  • poll_interval_seconds
    : default 
    5.0
  • timeout_seconds
    : default 
    300
  • audio_url
    （必填）：必须是可公开访问的URL
  • model
    ：
    qwen3-asr-flash-filetrans
    （唯一支持词级时间戳的模型）
  • language_hints
    ：默认值为
    ["zh", "en"]
  • enable_words
    ：默认值为
    true
    ——开启后才能获取词级时间戳
  • poll_interval_seconds
    ：默认值为5.0
  • timeout_seconds
    ：默认值为300

Troubleshooting

故障排查

  • Image size error: Use 
    "W*H"
    with asterisk, not 
    "WxH"
    . Example: 
    "2048*2048"
    .
  • TTS no audio URL: Check 
    output.audio.url
    — if empty, the model name or voice may be wrong.
  • ASR "file not accessible": 
    audio_url
    must be publicly reachable. DashScope servers fetch the file; local paths and auth-gated URLs don't work.
  • ASR poll timeout: Increase 
    timeout_seconds
    (default 300). Long audio files take longer to transcribe.
  • ASR no word timestamps: Ensure 
    enable_words: true
    and model is 
    qwen3-asr-flash-filetrans
    (not the sync 
    qwen3-asr-flash
    ).
  • Auth error (401): Verify 
    DASHSCOPE_API_KEY
    is set. Use 
    Authorization: Bearer $KEY
    header.
  • 图像尺寸错误：使用
    "W*H"
    格式（星号分隔），而非
    "WxH"
    。例如：
    "2048*2048"
    。
  • TTS无音频URL：检查
    output.audio.url
    ——如果为空，可能是模型名称或音色选择错误。
  • ASR提示"文件无法访问"：
    audio_url
    必须是可公开访问的地址。DashScope服务器会主动拉取文件，本地路径和需要身份验证的URL均无法使用。
  • ASR轮询超时：增大
    timeout_seconds
    的值（默认300）。音频文件越长，转录所需时间越久。
  • ASR无词级时间戳：确保已开启
    enable_words: true
    ，且使用的模型是
    qwen3-asr-flash-filetrans
    （而非同步版本
    qwen3-asr-flash
    ）。
  • 身份验证错误（401）：确认已配置
    DASHSCOPE_API_KEY
    ，且请求头使用
    Authorization: Bearer $KEY
    格式。

Safety

安全注意事项

Never print or write the API key to logs, metadata, patches, or project artifacts. 
.env.example
should contain only empty variable names. The tool's 
_safe_error()
method redacts the key from error messages.
切勿将API密钥打印或写入日志、元数据、补丁或项目产物中。
.env.example
文件应仅包含空的变量名。工具的
_safe_error()
方法会在错误信息中自动屏蔽密钥。