Migrating from 1.x¶
The 2.0 client replaces the 1.x module-level static classes, but the complete 1.x surface keeps working from its historical import paths. Migrate at your own pace — this page maps old habits to new ones.
Side-by-side comparison¶
| 1.x | 2.0 | |
|---|---|---|
| Entry point | Module-level static classes: Generation.call(...) |
A resource-style client: client.chat.completions.create(...) |
| One-liner | — | dashscope.chat("qwen-plus", "Tell me a joke") |
| Response | Raw dict-like; check status_code == HTTPStatus.OK |
Typed object; read resp.output_text, resp.usage.total_tokens |
| Errors | Inspect resp.code / resp.message by hand |
Typed DashScopeError exceptions raised by default |
| Streaming | Generator of raw frames | ChatStream with .text_stream, .reasoning_stream, .get_final_message() |
| Protocols | DashScope native + a separate compatible-mode entry | One client speaks native, openai, or anthropic via protocol= |
| Async | Separate Aio* classes |
dashscope.AsyncClient() mirrors the sync surface |
| Connections | A fresh session per call | One keep-alive pool per client, shared across resources |
| Config | Module globals (dashscope.api_key, set_region) |
Layered: args → dashscope.settings → env → ~/.dashscope/config.toml |
Call mapping¶
| 1.x class | 2.0 resource |
|---|---|
Generation / AioGeneration |
client.chat.completions |
MultiModalConversation |
client.multimodal |
ImageSynthesis / ImageGeneration |
client.images |
VideoSynthesis |
client.videos |
TextEmbedding / BatchTextEmbedding |
client.embeddings |
MultiModalEmbedding |
client.multimodal (embeddings) |
TextReRank |
client.rerank |
SpeechSynthesizer (tts / tts_v2) |
client.audio.tts |
Recognition / Transcription |
client.audio.asr |
Files |
client.files |
Models |
client.models |
FineTunes |
client.fine_tunes |
Deployments |
client.deployments |
Application |
client.apps |
Every 1.x class remains documented under Legacy 1.x.
Before / after¶
1.x — call, then inspect the status by hand:
from http import HTTPStatus
from dashscope import Generation
resp = Generation.call(
model="qwen-plus",
messages=[{"role": "user", "content": "Hello!"}],
)
if resp.status_code != HTTPStatus.OK:
print(resp.code, resp.message)
else:
print(resp.output.text)
2.0 — typed response, exceptions on failure:
from dashscope import Client, DashScopeError
try:
with Client() as client:
resp = client.chat.completions.create(
model="qwen-plus",
messages=[{"role": "user", "content": "Hello!"}],
)
print(resp.output_text)
except DashScopeError as exc:
print(exc.code, exc.message)
What stays the same¶
- Import paths:
from dashscope import Generationstill works (frozen facade). - The
DASHSCOPE_API_KEYenvironment variable and the console-issued keys. - Model names and request payloads — the wire contract is unchanged for the native protocol.
Migrate incrementally
Both surfaces coexist in one process. Move call sites one by one; there is no flag day. See Release Notes for what each 2.x release changed.