dashscope

DashScope

需要在 .env 中设置 DASHSCOPE_API_KEY。请访问 https://dashscope.aliyun.com/ 获取。

当前 API

重要： DashScope 的 /compatible-mode/v1/ 仅支持 /chat/completions 和 /embeddings。图像生成、TTS 和 ASR 均使用 DashScope 原生端点，而非 OpenAI 兼容路径。

这三个工具均使用 Authorization: Bearer $DASHSCOPE_API_KEY。

图像生成

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 小时）——必须另行下载

文本转语音

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，有效期约 24 小时）——必须另行下载

带词级时间戳的 ASR

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 用法

通过选择器生成图像

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"] is a flat list of {text, begin_time_seconds, end_time_seconds}

推荐工作流

1. **图像：**先生成一张样图。检查 prompt_extend: true（默认值）——DashScope 会改写提示词，以获得更好的效果。如果需要严格遵循提示词，请禁用此选项。
2. **TTS：**在生成完整旁白前，先生成一段 10-15 秒的样音。确认音色和语速后，再进行完整生成。
3. ASR：音频必须位于可公开访问的 URL。请先上传到任意公共托管服务（如 S3）。本地路径会被拒绝，并返回明确的错误。
4. **字幕：**根据 result.data["words"] 构建——每个词都包含 begin_time_seconds 和 end_time_seconds。根据语言语义将词语组合成字幕短语，而非按固定字符数分组。

参数

图像（dashscope_image）

• 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）

• 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（必填）：必须是可公开访问的 URL
• model：qwen3-asr-flash-filetrans（唯一支持词级时间戳的模型）
• language_hints：默认为 ["zh", "en"]
• enable_words：默认为 true——获取词级时间戳时必填
• poll_interval_seconds：默认为 5.0
• timeout_seconds：默认为 300

故障排查

• 图像尺寸错误： 使用带星号的 "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 请求头。

安全

切勿将 API 密钥打印或写入日志、元数据、补丁或项目文件。.env.example 只能包含空的变量名。工具的 _safe_error() 方法会从错误消息中删除密钥。