Skip to main content

DashScope Python SDK 1.x 歷史用法參考

DashScope Python SDK 1.x 介面的歷史用法速查與 1.x 到 2.0 的遷移對照,供存量項目參考。

本文面向仍在使用 DashScope Python SDK 1.x 的存量項目,集中收錄 1.x 介面的典型用法,並給出對應的 2.0 寫法。
新項目請直接使用 SDK 2.0:1.x 已進入凍結維護(只修缺陷、不增功能),1.x 與 2.0 在同一個 dashscope 包內並存(2.0.1 起提供),存量代碼無需刪除 1.x 依賴即可逐步遷移。Assistants / Threads / Runs 系列 API 已隨 1.x 下線,服務端不再支援,請勿在新代碼中使用。

介面遷移總對照

能力1.x 介面2.0 介面
文字生成Generation.call / AioGeneration.callclient.chat.completions.create
多模態對話MultiModalConversation.callclient.multimodal.chat.create
圖像生成ImageSynthesis.call/async_call/fetch/waitclient.images.generate / client.images.jobs.*
視頻生成VideoSynthesis.call/async_call/fetch/waitclient.videos.generate / client.videos.jobs.*
錄音檔案轉寫Transcription.async_call/fetch/waitclient.audio.asr.transcribe / client.audio.asr.jobs.*
即時語音辨識Recognition.start/send_audio_frame/stopclient.audio.asr.recognize(...) 上下文管理器
語音合成SpeechSynthesizer(tts_v2 回調式)client.audio.tts.synthesize/stream/connect
文字向量TextEmbedding.call / BatchTextEmbeddingclient.embeddings.create / client.embeddings.jobs.*
重排序TextReRank.callclient.rerank.create
智能體應用Application.callclient.apps.completions.create
檔案管理Files.upload/list/get/deleteclient.files.upload/list/get/delete
模型列表Models.list/getclient.models.list/get

客戶端構造與鑒權

1.x 通過模組級全域變數配置;2.0 通過 Client 構造參數配置(優先順序:構造參數 > dashscope.settings > 環境變數 > ~/.dashscope/config.toml)。
# 1.x:全域變數
import dashscope
dashscope.api_key = os.getenv("DASHSCOPE_API_KEY")
dashscope.base_http_api_url = "https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1"
# 2.0:客戶端構造
import dashscope
client = dashscope.Client(
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    workspace="{WorkspaceId}",
    region="cn-beijing",
)

文字生成

# 1.x
from dashscope import Generation
response = Generation.call(
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    model="qwen-plus",
    messages=messages,
    result_format="message",
)
if response.status_code == 200:
    print(response.output.choices[0].message.content)
else:
    print(f"HTTP返回碼:{response.status_code}")
    print(f"錯誤碼:{response.code}")
    print(f"錯誤資訊:{response.message}")
# 2.0
from dashscope.v2 import DashScopeError
try:
    response = client.chat.completions.create(
        model="qwen-plus",
        messages=messages,
    )
    print(response.choices[0].message.content)
except DashScopeError as e:
    print(f"HTTP返回碼:{e.status_code}")
    print(f"錯誤碼:{e.code}")
    print(f"錯誤資訊:{e.message}")

多模態對話

# 1.x
from dashscope import MultiModalConversation
response = MultiModalConversation.call(
    api_key=os.getenv('DASHSCOPE_API_KEY'),
    model='qwen3-vl-plus',
    messages=[{
        "role": "user",
        "content": [
            {"image": "https://example.com/image.png"},
            {"text": "請問圖片裡有什麼?"},
        ],
    }])
print(response.output.choices[0].message.content[0]['text'])
# 2.0:content parts 形狀保留,取值扁平化
response = client.multimodal.chat.create(
    model='qwen3-vl-plus',
    messages=[{
        "role": "user",
        "content": [
            {"image": "https://example.com/image.png"},
            {"text": "請問圖片裡有什麼?"},
        ],
    }])
print(response.output_text)

圖像生成

# 1.x:同步 call(阻塞到出圖)
from dashscope import ImageSynthesis
rsp = ImageSynthesis.call(api_key=os.getenv("DASHSCOPE_API_KEY"),
                          model=ImageSynthesis.Models.wanx_v1,
                          prompt=prompt,
                          n=1,
                          style='<watercolor>',
                          size='1024*1024')
if rsp.status_code == HTTPStatus.OK:
    for result in rsp.output.results:
        print(result.url)
else:
    print('Failed, status_code: %s, code: %s, message: %s' %
          (rsp.status_code, rsp.code, rsp.message))
# 2.0:generate 一步式(提交併等待);枚舉類改字串
job = client.images.generate(
    model="wanx2.1-t2i-turbo",
    prompt=prompt,
    n=1,
    size='1024*1024',
)
for url in job.image_urls:
    print(url)
分步任務(1.x async_call/fetch/wait)對應 client.images.jobs.create/fetch/wait;任務狀態判定由 rsp.output.task_status == 'SUCCEEDED' 改為 job.succeeded。

視頻生成

# 1.x
from dashscope import VideoSynthesis
rsp = VideoSynthesis.call(api_key=api_key,
                          model='wan3.0-video',
                          prompt=prompt,
                          resolution="720P",
                          ratio="16:9",
                          duration=15,
                          watermark=True)
if rsp.status_code == HTTPStatus.OK:
    print("video_url:", rsp.output.video_url)
# 2.0
job = client.videos.generate(
    model='wan3.0-video',
    prompt=prompt,
    resolution="720P",
    ratio="16:9",
    duration=15,
    watermark=True,
)
print("video_url:", job.video_url)
1.x VideoSynthesis 的 extend_prompt 預設為 True;2.0 為 prompt_extend 且預設由服務端決定,依賴舊預設的調用需顯式傳 prompt_extend=True。

錄音檔案轉寫

# 1.x:async_call 提交 + wait 等待
from dashscope.audio.asr import Transcription
task_response = Transcription.async_call(
    model='paraformer-v2',
    file_urls=['{YOUR_AUDIO_URL}'],
    language_hints=['zh', 'en'],
)
transcribe_response = Transcription.wait(task=task_response.output.task_id)
if transcribe_response.status_code == HTTPStatus.OK:
    print(json.dumps(transcribe_response.output, indent=4, ensure_ascii=False))
# 2.0:transcribe 一步式;簽名外參數走 parameters
job = client.audio.asr.transcribe(
    ['{YOUR_AUDIO_URL}'],
    model='paraformer-v2',
    parameters={'language_hints': ['zh', 'en']},
)
print(json.dumps(job.model_dump(), indent=4, ensure_ascii=False))
分步控制(原 async_call + 迴圈 fetch)對應 client.audio.asr.jobs.create + 迴圈 jobs.fetch。

即時語音辨識

1.x 使用回調類(Recognition + RecognitionCallback);2.0 改為上下文管理器 + 事件迭代。
# 1.x(回調式,節選)
from dashscope.audio.asr import Recognition
class Callback(RecognitionCallback):
    def on_result(self, result): ...
recognition = Recognition(model='paraformer-realtime-v2', callback=Callback())
recognition.start()
recognition.send_audio_frame(chunk)
recognition.stop()
# 2.0(事件迭代式,發送與接收並發)
from concurrent.futures import ThreadPoolExecutor

def receive_events(rec):
    for event in rec.events():
        print(event)

with client.audio.asr.recognize(
        model='paraformer-realtime-v2',
        format='pcm',
        sample_rate=16000,
) as recognition:
    with ThreadPoolExecutor(max_workers=1) as pool:
        receiver = pool.submit(receive_events, recognition)
        for chunk in iter_pcm_chunks():  # 由應用提供即時 PCM 幀
            recognition.send_audio_frame(chunk)
        recognition.stop()
        receiver.result()
本地檔案一次識別(1.x Recognition.call(file))對應 for event in client.audio.asr.recognize_file(path, model=...):。

語音合成

1.x tts_v2 使用回調收音頻;2.0 改為迭代/會話式。
# 1.x(回調式,節選)
from dashscope.audio.tts_v2 import SpeechSynthesizer, ResultCallback
class Callback(ResultCallback):
    def on_data(self, data: bytes): audio.write(data)
synthesizer = SpeechSynthesizer(
    model="cosyvoice-v3-flash",
    voice="longanyang",
    callback=Callback(),
)
synthesizer.streaming_call(text)
synthesizer.streaming_complete()
# 2.0:connect 會話(分段發送 + 逐段收音頻)
with client.audio.tts.connect(
        model="cosyvoice-v3-flash",
        voice="longanyang",
        format="mp3",
) as session:
    session.send_text(text)
    session.flush()
    session.stop()  # 結束任務,等待剩餘音頻返回
    for chunk in session.audio_chunks():
        audio.write(chunk)
一次性合成(短文字整段返回)用 client.audio.tts.synthesize(text, model=..., voice=...);純流式用 client.audio.tts.stream(text, ...) 迭代 bytes。

文字向量與重排序

# 1.x
resp = dashscope.TextEmbedding.call(
    model="qwen3.7-text-embedding",
    input="衣服的質量槓槓的",
)
if resp.status_code == HTTPStatus.OK:
    print(resp)
# 2.0
resp = client.embeddings.create(
    model="qwen3.7-text-embedding",
    input="衣服的質量槓槓的",
)
for item in resp.embeddings:
    print(item.index, len(item.embedding))
批量向量(1.x BatchTextEmbedding)對應 client.embeddings.jobs.create/fetch/wait。重排序 TextReRank.call 對應 client.rerank.create,取值由 resp.output.results[i] 改為 resp.results[i]。

智能體應用調用

# 1.x
from dashscope import Application
response = Application.call(
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    app_id='APP_ID',
    prompt='你是誰?')
if response.status_code != HTTPStatus.OK:
    print(f'code={response.status_code}, message={response.message}')
else:
    print(response.output.text)
# 2.0
from dashscope.v2 import DashScopeError
try:
    response = client.apps.completions.create(
        app_id='APP_ID',
        prompt='你是誰?')
    print(response.text)
except DashScopeError as e:
    print(f'code={e.code}, message={e.message}')
應用流式調用保留 incremental_output 參數(幀形態由它決定),逐幀取值由 response.output.text 改為 partial.text。

行為差異要點

遷移時除介面名外,還需要注意以下行為差異:
  • 錯誤處理:1.x 在響應物件上自查 status_code/code;2.0 預設失敗直接拋 DashScopeError 異常族(含 e.code/e.status_code/e.request_id/e.message),需要信封風格可構造 Client(raise_on_error=False)。
  • 流式輸出:1.x Generation.call(stream=True) 預設每幀重放全量文字(需 incremental_output=True 才增量);2.0 流式一律增量。百鍊應用(apps.completions)保留 incremental_output 開關。
  • 非同步任務等待:1.x wait 預設無限等待、超時返回錯誤響應;2.0 jobs.wait 預設 24 小時總預算、指數退避輪詢、任務 FAILED 拋異常。
  • 響應結構:1.x 業務內容包裹在 output 欄位下(response.output.choices[...]);2.0 已扁平化(response.choices[...]),並新增 resp.output_text、job.succeeded 等便捷取值。
  • 簽名外參數:2.0 各資源方法為封閉具名簽名,1.x 透傳的模型專屬參數需改走 parameters={...}(圖像素材類走 extra_input=)。

相關文件