Skip to main content

Referensi penggunaan lama DashScope Python SDK 1.x

Referensi penggunaan lama dan pemetaan migrasi 1.x ke 2.0 untuk DashScope Python SDK, untuk proyek yang masih menggunakan versi 1.x.

Halaman ini ditujukan untuk proyek yang masih menggunakan DashScope Python SDK 1.x. Halaman ini menghimpun penggunaan tipikal antarmuka 1.x dalam satu tempat dan menunjukkan kode 2.0 yang setara.
Untuk proyek baru, gunakan SDK 2.0 secara langsung. Versi SDK 1.x berada dalam masa pemeliharaan beku (hanya perbaikan cacat); 1.x dan 2.0 berdampingan dalam paket dashscope yang sama (mulai 2.0.1), sehingga kode yang ada dapat dimigrasikan bertahap tanpa menghapus dependensi 1.x. Keluarga API Assistants / Threads / Runs telah dihentikan bersamaan dengan 1.x dan tidak lagi didukung di sisi server; jangan gunakan dalam kode baru.

Pemetaan migrasi antarmuka

KemampuanAntarmuka 1.xAntarmuka 2.0
Generasi teksGeneration.call / AioGeneration.callclient.chat.completions.create
Chat multimodalMultiModalConversation.callclient.multimodal.chat.create
Generasi gambarImageSynthesis.call/async_call/fetch/waitclient.images.generate / client.images.jobs.*
Generasi videoVideoSynthesis.call/async_call/fetch/waitclient.videos.generate / client.videos.jobs.*
Transkripsi file audioTranscription.async_call/fetch/waitclient.audio.asr.transcribe / client.audio.asr.jobs.*
Pengenalan ucapan real-timeRecognition.start/send_audio_frame/stopclient.audio.asr.recognize(...) context manager
Sintesis suaraSpeechSynthesizer (tts_v2 callback style)client.audio.tts.synthesize/stream/connect
Embedding teksTextEmbedding.call / BatchTextEmbeddingclient.embeddings.create / client.embeddings.jobs.*
RerankTextReRank.callclient.rerank.create
Aplikasi agenApplication.callclient.apps.completions.create
Manajemen fileFiles.upload/list/get/deleteclient.files.upload/list/get/delete
Daftar modelModels.list/getclient.models.list/get

Konstruksi klien dan autentikasi

Versi 1.x dikonfigurasi melalui variabel global tingkat modul; versi 2.0 dikonfigurasi melalui argumen konstruktor Client (prioritas: konstruktor > dashscope.settings > variabel lingkungan > ~/.dashscope/config.toml).
# 1.x: globals
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: client construction
import dashscope
client = dashscope.Client(
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    workspace="{WorkspaceId}",
    region="cn-beijing",
)

Generasi teks

# 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 status: {response.status_code}")
    print(f"Error code: {response.code}")
    print(f"Error message: {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 status: {e.status_code}")
    print(f"Error code: {e.code}")
    print(f"Error message: {e.message}")

Chat multimodal

# 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": "What is in this picture?"},
        ],
    }])
print(response.output.choices[0].message.content[0]['text'])
# 2.0: content parts shape kept, flat access
response = client.multimodal.chat.create(
    model='qwen3-vl-plus',
    messages=[{
        "role": "user",
        "content": [
            {"image": "https://example.com/image.png"},
            {"text": "What is in this picture?"},
        ],
    }])
print(response.output_text)

Generasi gambar

# 1.x: synchronous call (blocks until done)
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 one-shot (submit and wait); enum classes become strings
job = client.images.generate(
    model="wanx2.1-t2i-turbo",
    prompt=prompt,
    n=1,
    size='1024*1024',
)
for url in job.image_urls:
    print(url)
Tugas bertahap (1.x async_call/fetch/wait) dipetakan ke client.images.jobs.create/fetch/wait; penentuan status tugas berubah dari rsp.output.task_status == 'SUCCEEDED' menjadi job.succeeded.

Generasi video

# 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)
Pada 1.x, extend_prompt dari VideoSynthesis bernilai default True; pada 2.0 namanya menjadi prompt_extend dan nilai defaultnya ditentukan oleh server. Pemanggilan yang bergantung pada nilai default lama harus meneruskan prompt_extend=True secara eksplisit.

Transkripsi file audio

# 1.x: async_call submit + 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 one-shot; non-signature parameters go via 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))
Kontrol bertahap (async_call + loop fetch pada versi lama) dipetakan ke client.audio.asr.jobs.create + loop jobs.fetch.

Pengenalan ucapan real-time

Versi 1.x menggunakan kelas callback (Recognition + RecognitionCallback); versi 2.0 menggunakan context manager + iterasi event.
# 1.x (callback style, excerpt)
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 (event iteration, send and receive concurrently)
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():  # real-time PCM frames provided by the application
            recognition.send_audio_frame(chunk)
        recognition.stop()
        receiver.result()
Pengenalan file lokal sekali jalan (1.x Recognition.call(file)) dipetakan ke for event in client.audio.asr.recognize_file(path, model=...):.

Sintesis suara

Pada 1.x, tts_v2 menerima audio melalui callback; pada 2.0 menggunakan gaya iterasi/sesi.
# 1.x (callback style, excerpt)
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 session (segmented input + segmented audio)
with client.audio.tts.connect(
        model="cosyvoice-v3-flash",
        voice="longanyang",
        format="mp3",
) as session:
    session.send_text(text)
    session.flush()
    session.stop()  # End the task and wait for remaining audio
    for chunk in session.audio_chunks():
        audio.write(chunk)
Sintesis sekali jalan menggunakan client.audio.tts.synthesize(text, model=..., voice=...); streaming murni mengiterasi client.audio.tts.stream(text, ...).

Embedding dan rerank

# 1.x
resp = dashscope.TextEmbedding.call(
    model="qwen3.7-text-embedding",
    input="The quality of this clothing is excellent.",
)
if resp.status_code == HTTPStatus.OK:
    print(resp)
# 2.0
resp = client.embeddings.create(
    model="qwen3.7-text-embedding",
    input="The quality of this clothing is excellent.",
)
for item in resp.embeddings:
    print(item.index, len(item.embedding))
Embedding batch (1.x BatchTextEmbedding) dipetakan ke client.embeddings.jobs.create/fetch/wait. TextReRank.call dipetakan ke client.rerank.create, dengan hasil berpindah dari resp.output.results[i] ke resp.results[i].

Pemanggilan aplikasi agen

# 1.x
from dashscope import Application
response = Application.call(
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    app_id='APP_ID',
    prompt='Who are you?')
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='Who are you?')
    print(response.text)
except DashScopeError as e:
    print(f'code={e.code}, message={e.message}')
Pemanggilan aplikasi streaming tetap mempertahankan parameter incremental_output (menentukan bentuk frame); keluaran per frame berpindah dari response.output.text ke partial.text.

Perbedaan perilaku

Selain nama antarmuka, perhatikan perbedaan perilaku berikut saat migrasi:
  • Penanganan kesalahan: 1.x memeriksa status_code/code pada respons; 2.0 secara default melempar keluarga pengecualian DashScopeError (dengan e.code/e.status_code/e.request_id/e.message). Untuk perilaku bergaya envelope, konstruksikan Client(raise_on_error=False).
  • Keluaran streaming: Generation.call(stream=True) pada 1.x secara default memutar ulang seluruh teks pada setiap frame (incremental_output=True untuk delta); streaming pada 2.0 selalu inkremental. Aplikasi Model Studio (apps.completions) tetap mempertahankan sakelar incremental_output.
  • Penantian tugas asinkron: wait pada 1.x menunggu tanpa batas secara default dan mengembalikan respons kesalahan saat waktu habis; jobs.wait pada 2.0 memiliki total anggaran default 24 jam, polling dengan backoff eksponensial, dan melempar pengecualian untuk tugas FAILED.
  • Struktur respons: 1.x membungkus konten bisnis di bawah field output (response.output.choices[...]); 2.0 sudah diratakan (response.choices[...]) dengan akses praktis seperti resp.output_text dan job.succeeded.
  • Parameter di luar signature: metode resource 2.0 memiliki signature bernama tertutup; parameter khusus model yang diteruskan pada 1.x harus melalui parameters={...} (material gambar melalui extra_input=).

Dokumentasi terkait