DashScope 是阿里云百炼（Alibaba Cloud Bailian）的集成封装，提供一个统一入口调用图像生成、文本转语音（TTS）和语音识别（ASR）三类能力，并可用于 OpenMontage 项目的素材生成流程。
用途
该工具面向需要同时处理图像、语音合成和语音转写的工作流，典型场景是视频制作：先生成配图，再合成旁白，最后对旁白音频做带词级时间戳的转写以生成字幕。
准备与鉴权
需要 DASHSCOPE_API_KEY，配置在 .env 文件中，可在 https://dashscope.aliyun.com/ 获取。三个能力均使用 Authorization: Bearer $DASHSCOPE_API_KEY 头进行鉴权。
需要注意：DashScope 的 /compatible-mode/v1/ 仅支持 /chat/completions 和 /embeddings，图像生成、TTS 和 ASR 都使用 DashScope 原生端点，而非 OpenAI 兼容路径。
主要能力
图像生成
端点：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（含角色与文本提示）以及 parameters（size、n、prompt_extend、watermark）。尺寸格式使用星号分隔，例如 "1024*1024"，而非 "1024x1024"。
返回结果位于 output.choices[0].message.content[0].image，是一个有效约 24 小时的 URL，需要另行下载。
文本转语音
使用与图像生成相同的端点，但请求体不同。
支持模型：qwen3-tts-flash（默认）、qwen3-tts-instruct-flash、qwen-tts-2025-05-22。
请求体包含 model、input.text 和 input.voice（默认 "Cherry"），以及 language_type（默认 "Auto"）。
返回结果位于 output.audio.url，为 WAV 格式，有效约 24 小时，需要另行下载。
带词级时间戳的语音识别
端点：POST https://dashscope.aliyuncs.com/api/v1/services/audio/asr/transcription，需带请求头 X-DashScope-Async: enable。
使用模型 qwen3-asr-flash-filetrans（注意：不是 qwen3-asr-flash，同步版本没有词级时间戳）。
请求体包含 model、input.file_url（公开可访问的音频 URL）以及 parameters（enable_words、language_hints）。该接口返回 task_id，需轮询 GET /api/v1/tasks/{task_id} 直到状态为 SUCCEEDED，再下载 output.result.transcription_url 获取 JSON，其中包含 transcripts[].sentences[].words[]。返回中的 begin_time/end_time 为毫秒，工具会归一化为秒。
使用方式
在 OpenMontage 中可通过选择器或直接调用的方式使用。
图像（通过选择器）：
from tools.graphics.image_selector import ImageSelector
result = ImageSelector().execute({ "preferred_provider": "dashscope", "prompt": "一只猫坐在沙发上", "output_path": "projects/my-video/assets/images/cat.png", })
TTS（通过选择器）：
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（直接调用，用于字幕的词级时间戳）：
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"] 是一个扁平列表，每项包含 {text, begin_time_seconds, end_time_seconds}。
推荐流程
图像：先生成样例。注意 prompt_extend 默认为 true，DashScope 会重写提示词以获得更好效果；若需要严格遵循原始提示词可将其禁用。
TTS：在生成完整旁白前，先生成 10-15 秒的样例，确认音色与节奏后再进行完整生成。
ASR：音频必须是公开可访问的 URL，需先上传到公开主机（如 S3 等），本地路径会被拒绝并返回明确错误。
字幕：基于 result.data["words"] 构建，每个词有 begin_time_seconds 和 end_time_seconds。应按语言语义而非固定字数将词分组成字幕短语。
参数
图像（dashscope_image）：prompt（必填）；model（默认 qwen-image-2.0-pro）；size（默认 "1024*1024"，用星号分隔）；n（1-6 张）；negative_prompt（最多 500 字符）；prompt_extend（默认 true）；watermark（默认 false）；seed（用于可复现）。
TTS（dashscope_tts）：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）：audio_url（必填，公开可访问）；model（qwen3-asr-flash-filetrans，唯一支持词级时间戳的模型）；language_hints（默认 ["zh", "en"]）；enable_words（默认 true，词级时间戳必需）；poll_interval_seconds（默认 5.0）；timeout_seconds（默认 300）。
适用场景与限制
适用于在视频或其他多媒体项目中批量生成配图、旁白语音及带时间戳的字幕数据。
限制方面：三个能力的输出 URL 有效期约 24 小时，需及时下载；ASR 仅接受公开可访问的音频 URL，不支持本地路径和需鉴权的 URL；TTS 单次文本长度受限（qwen3-tts-flash 最多 600 字符）；词级时间戳仅 qwen3-asr-flash-filetrans 支持。
排查
图像尺寸报错：使用 "WH" 星号分隔而非 "WxH"，例如 "20482048"。
TTS 无音频 URL：检查 output.audio.url，若为空可能是模型名或音色有误。
ASR 提示 "file not accessible"：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 头。
安全
切勿将 API key 打印或写入日志、元数据、补丁或项目产物。.env.example 中应只包含空变量名。工具的 _safe_error() 方法会从错误信息中脱敏该 key。