Skip to main content

Référence d'utilisation héritée du SDK Python DashScope 1.x

Référence d'utilisation héritée et correspondances de migration de la version 1.x vers la 2.0 du SDK Python DashScope, destinée aux projets existants encore en 1.x.

Cette page s'adresse aux projets existants encore sur le SDK Python DashScope 1.x. Elle rassemble en un seul endroit les usages typiques des interfaces 1.x et présente le code 2.0 équivalent.
Pour les nouveaux projets, utilisez directement le SDK 2.0. La version 1.x du SDK est en maintenance gelée (corrections de défauts uniquement) ; 1.x et 2.0 coexistent dans le même paquet dashscope (à partir de la version 2.0.1), de sorte que le code existant peut migrer progressivement sans supprimer les dépendances 1.x. La famille d'API Assistants / Threads / Runs a été retirée avec la 1.x et n'est plus prise en charge côté serveur ; ne l'utilisez pas dans le nouveau code.

Correspondances de migration des interfaces

CapacitéInterface 1.xInterface 2.0
Génération de texteGeneration.call / AioGeneration.callclient.chat.completions.create
Chat multimodalMultiModalConversation.callclient.multimodal.chat.create
Génération d'imagesImageSynthesis.call/async_call/fetch/waitclient.images.generate / client.images.jobs.*
Génération de vidéoVideoSynthesis.call/async_call/fetch/waitclient.videos.generate / client.videos.jobs.*
Transcription de fichiers audioTranscription.async_call/fetch/waitclient.audio.asr.transcribe / client.audio.asr.jobs.*
Reconnaissance vocale en temps réelRecognition.start/send_audio_frame/stopclient.audio.asr.recognize(...) context manager
Synthèse vocaleSpeechSynthesizer (tts_v2 callback style)client.audio.tts.synthesize/stream/connect
Embeddings de texteTextEmbedding.call / BatchTextEmbeddingclient.embeddings.create / client.embeddings.jobs.*
RerankTextReRank.callclient.rerank.create
Application agentApplication.callclient.apps.completions.create
Gestion des fichiersFiles.upload/list/get/deleteclient.files.upload/list/get/delete
Liste des modèlesModels.list/getclient.models.list/get

Construction du client et authentification

La version 1.x du SDK se configure via des variables globales au niveau du module ; la 2.0 se configure via les arguments du constructeur Client (priorité : constructeur > dashscope.settings > variables d'environnement > ~/.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",
)

Génération de texte

# 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)

Génération d'images

# 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)
Les tâches pas à pas (1.x async_call/fetch/wait) correspondent à client.images.jobs.create/fetch/wait ; le contrôle du statut de la tâche passe de rsp.output.task_status == 'SUCCEEDED' à job.succeeded.

Génération de vidéo

# 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)
En 1.x, extend_prompt de VideoSynthesis vaut True par défaut ; en 2.0, il s'agit de prompt_extend et la valeur par défaut est décidée par le serveur. Les appels qui reposaient sur l'ancienne valeur par défaut doivent passer prompt_extend=True explicitement.

Transcription de fichiers 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))
Le contrôle pas à pas (ancienne boucle async_call + fetch) correspond à client.audio.asr.jobs.create + une boucle jobs.fetch.

Reconnaissance vocale en temps réel

La 1.x utilise des classes de callback (Recognition + RecognitionCallback) ; la 2.0 utilise un gestionnaire de contexte + une itération d'événements.
# 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()
La reconnaissance ponctuelle d'un fichier local (1.x Recognition.call(file)) correspond à for event in client.audio.asr.recognize_file(path, model=...):.

Synthèse vocale

En 1.x, tts_v2 reçoit l'audio via des callbacks ; en 2.0, on utilise le style itération/session.
# 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)
La synthèse ponctuelle utilise client.audio.tts.synthesize(text, model=..., voice=...) ; le streaming pur itère client.audio.tts.stream(text, ...).

Embeddings et 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))
Les embeddings par lot (1.x BatchTextEmbedding) correspondent à client.embeddings.jobs.create/fetch/wait. TextReRank.call correspond à client.rerank.create, les résultats passant de resp.output.results[i] à resp.results[i].

Appels d'application agent

# 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}')
Les appels d'application en streaming conservent le paramètre incremental_output (il détermine la forme des trames) ; la sortie par trame passe de response.output.text à partial.text.

Différences de comportement

Au-delà des noms d'interfaces, notez ces différences de comportement lors de la migration :
  • Gestion des erreurs : la 1.x vérifie status_code/code sur la réponse ; la 2.0 lève par défaut la famille d'exceptions DashScopeError (avec e.code/e.status_code/e.request_id/e.message). Pour un comportement de type enveloppe, construisez Client(raise_on_error=False).
  • Sortie en streaming : en 1.x, Generation.call(stream=True) renvoie par défaut le texte complet à chaque trame (incremental_output=True pour les deltas) ; en 2.0, les flux sont toujours incrémentaux. Les applications Model Studio (apps.completions) conservent le commutateur incremental_output.
  • Attente de tâches asynchrones : en 1.x, wait attend indéfiniment par défaut et renvoie une réponse d'erreur en cas de délai dépassé ; en 2.0, jobs.wait a un budget total par défaut de 24 heures, un sondage à intervalles exponentiels et lève une exception pour les tâches FAILED.
  • Structure de la réponse : la 1.x encapsule le contenu utile sous output (response.output.choices[...]) ; la 2.0 est plate (response.choices[...]), avec des raccourcis comme resp.output_text et job.succeeded.
  • Paramètres hors signature : les méthodes de ressources de la 2.0 ont des signatures nommées fermées ; les paramètres propres au modèle transmis en 1.x doivent passer par parameters={...} (les éléments d'image via extra_input=).

Documentation connexe