DashScope
Requires DASHSCOPE_API_KEY in .env. Get one at https://dashscope.aliyun.com/.
Current 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.
Image Generation
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-to-Speech
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
ASR with Word-Level Timestamps
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
OpenMontage Usage
Image via selector
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
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)
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}
Recommended Workflow
- Image: Generate a sample first. Check
prompt_extend: true (default) — DashScope rewrites your prompt for better results. Disable if you need literal prompt adherence.
- TTS: Generate a 10-15 second sample before full narration. Approve voice and pacing before committing to full generation.
- 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.
- 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.
Parameters
Image (dashscope_image)
prompt (required): text promptmodel: default qwen-image-2.0-prosize: default "1024*1024" — asterisk separator, not "x"n: 1-6 imagesnegative_prompt: things to avoid (max 500 chars)prompt_extend: default true — auto-rewrite prompt for better resultswatermark: default falseseed: for reproducibility
TTS (dashscope_tts)
text (required): text to synthesize (max 600 chars for qwen3-tts-flash)model: default qwen3-tts-flashvoice: 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)
ASR (dashscope_asr)
audio_url (required): must be publicly accessible URLmodel: qwen3-asr-flash-filetrans (only model that supports word timestamps)language_hints: default ["zh", "en"]enable_words: default true — required for word-level timestampspoll_interval_seconds: default 5.0timeout_seconds: default 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.
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.
1---2name: dashscope3description: DashScope (Alibaba Cloud Bailian / 阿里云百炼) integration — image generation (qwen-image-2.0-pro), text-to-speech (qwen3-tts-flash), and ASR with word-level timestamps (qwen3-asr-flash-filetrans). Use when generating images via Qwen-Image, narrating via Qwen-TTS, or transcribing with word-level timestamps via Qwen-ASR.4---5
6# DashScope
7
8Requires `DASHSCOPE_API_KEY` in `.env`. Get one at https://dashscope.aliyun.com/.
9
10## Current API
11
12**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.
13
14All three tools use `Authorization: Bearer $DASHSCOPE_API_KEY`.
15
16### Image Generation
17
18```text
19POST https://dashscope.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation
20```
21
22- Model: `qwen-image-2.0-pro` (default), `qwen-image-max`, `wan2.7-image`, `z-image-turbo`
23- Body: `{model, input: {messages: [{role: "user", content: [{text: "prompt"}]}]}, parameters: {size: "W*H", n, prompt_extend, watermark}}`
24- **Size format uses asterisk:** `"1024*1024"` not `"1024x1024"`
25- Response: `output.choices[0].message.content[0].image` (URL, valid ~24h) — must download separately
26
27### Text-to-Speech
28
29```text
30POST https://dashscope.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation
31```
32
33Same endpoint as image gen, different body.
34
35- Model: `qwen3-tts-flash` (default), `qwen3-tts-instruct-flash`, `qwen-tts-2025-05-22`
36- Body: `{model, input: {text, voice: "Cherry", language_type: "Auto"}}`
37- Response: `output.audio.url` (WAV, valid ~24h) — must download separately
38
39### ASR with Word-Level Timestamps
40
41```text
42POST https://dashscope.aliyuncs.com/api/v1/services/audio/asr/transcription
43Header: X-DashScope-Async: enable
44```
45
46- Model: `qwen3-asr-flash-filetrans` (NOT `qwen3-asr-flash` — the sync version has no word timestamps)
47- Body: `{model, input: {file_url: "https://public-url/audio.mp3"}, parameters: {enable_words: true, language_hints: ["zh","en"]}}`
48- Returns `task_id` → poll `GET /api/v1/tasks/{task_id}` until `SUCCEEDED` → download `output.result.transcription_url` → JSON with `transcripts[].sentences[].words[]`
49- Timestamps in `begin_time`/`end_time` are in **milliseconds** — the tool normalizes to seconds
50
51## OpenMontage Usage
52
53### Image via selector
54
55```python
56from tools.graphics.image_selector import ImageSelector
57
58result = ImageSelector().execute({
59 "preferred_provider": "dashscope",
60 "prompt": "一只猫坐在沙发上",
61 "output_path": "projects/my-video/assets/images/cat.png",
62})
63```
64
65### TTS via selector
66
67```python
68from tools.audio.tts_selector import TTSSelector
69
70result = TTSSelector().execute({
71 "preferred_provider": "dashscope",
72 "text": "如果 AI 真的会改变未来，普通人到底该怎么参与？",
73 "voice": "Cherry",
74 "output_path": "projects/my-video/assets/audio/narration.wav",
75})
76```
77
78### ASR directly (word timestamps for subtitles)
79
80```python
81from tools.analysis.dashscope_asr import DashscopeAsr
82
83result = DashscopeAsr().execute({
84 "audio_url": "https://example.com/narration.wav",
85 "output_path": "projects/my-video/assets/audio/transcription.json",
86})
87
88# result.data["words"] is a flat list of {text, begin_time_seconds, end_time_seconds}
89```
90
91## Recommended Workflow
92
931. **Image:** Generate a sample first. Check `prompt_extend: true` (default) — DashScope rewrites your prompt for better results. Disable if you need literal prompt adherence.
942. **TTS:** Generate a 10-15 second sample before full narration. Approve voice and pacing before committing to full generation.
953. **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.
964. **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.
97
98## Parameters
99
100### Image (`dashscope_image`)
101- `prompt` (required): text prompt
102- `model`: default `qwen-image-2.0-pro`
103- `size`: default `"1024*1024"` — **asterisk separator, not "x"**
104- `n`: 1-6 images
105- `negative_prompt`: things to avoid (max 500 chars)
106- `prompt_extend`: default `true` — auto-rewrite prompt for better results
107- `watermark`: default `false`
108- `seed`: for reproducibility
109
110### TTS (`dashscope_tts`)
111- `text` (required): text to synthesize (max 600 chars for qwen3-tts-flash)
112- `model`: default `qwen3-tts-flash`
113- `voice`: default `"Cherry"` — other voices: `"Ethan"`, `"Chelsie"`, etc.
114- `language_type`: default `"Auto"` — `"Chinese"`, `"English"`, `"Japanese"`, `"Korean"`
115- `instructions`: natural language delivery instructions (only for `qwen3-tts-instruct-flash`)
116
117### ASR (`dashscope_asr`)
118- `audio_url` (required): **must be publicly accessible URL**
119- `model`: `qwen3-asr-flash-filetrans` (only model that supports word timestamps)
120- `language_hints`: default `["zh", "en"]`
121- `enable_words`: default `true` — required for word-level timestamps
122- `poll_interval_seconds`: default `5.0`
123- `timeout_seconds`: default `300`
124
125## Troubleshooting
126
127- **Image size error:** Use `"W*H"` with asterisk, not `"WxH"`. Example: `"2048*2048"`.
128- **TTS no audio URL:** Check `output.audio.url` — if empty, the model name or voice may be wrong.
129- **ASR "file not accessible":** `audio_url` must be publicly reachable. DashScope servers fetch the file; local paths and auth-gated URLs don't work.
130- **ASR poll timeout:** Increase `timeout_seconds` (default 300). Long audio files take longer to transcribe.
131- **ASR no word timestamps:** Ensure `enable_words: true` and model is `qwen3-asr-flash-filetrans` (not the sync `qwen3-asr-flash`).
132- **Auth error (401):** Verify `DASHSCOPE_API_KEY` is set. Use `Authorization: Bearer $KEY` header.
133
134## Safety
135
136Never 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.
calesthio