Skip to main content

Referencia del uso heredado del SDK de Python de DashScope 1.x

Referencia del uso heredado y correspondencia de migración de 1.x a 2.0 para el SDK de Python de DashScope, orientada a proyectos existentes que aún usan la versión 1.x.

Esta página está dirigida a proyectos existentes que todavía usan DashScope Python SDK 1.x. Reúne en un solo lugar el uso típico de las interfaces 1.x y muestra el código equivalente en 2.0.
Para proyectos nuevos, use el SDK 2.0 directamente. La versión 1.x está en mantenimiento congelado (solo correcciones de defectos); 1.x y 2.0 coexisten en el mismo paquete dashscope (a partir de la versión 2.0.1), por lo que el código existente puede migrarse de forma incremental sin eliminar las dependencias de 1.x. La familia de API Assistants / Threads / Runs se ha retirado junto con 1.x y el servidor ya no la admite; no la utilice en código nuevo.

Asignación de migración de interfaces

CapacidadInterfaz 1.xInterfaz 2.0
Generación de textoGeneration.call / AioGeneration.callclient.chat.completions.create
Chat multimodalMultiModalConversation.callclient.multimodal.chat.create
Generación de imágenesImageSynthesis.call/async_call/fetch/waitclient.images.generate / client.images.jobs.*
Generación de videoVideoSynthesis.call/async_call/fetch/waitclient.videos.generate / client.videos.jobs.*
Transcripción de archivos de audioTranscription.async_call/fetch/waitclient.audio.asr.transcribe / client.audio.asr.jobs.*
Reconocimiento de voz en tiempo realRecognition.start/send_audio_frame/stopclient.audio.asr.recognize(...) context manager
Síntesis de vozSpeechSynthesizer (tts_v2 callback style)client.audio.tts.synthesize/stream/connect
Embeddings de textoTextEmbedding.call / BatchTextEmbeddingclient.embeddings.create / client.embeddings.jobs.*
RerankTextReRank.callclient.rerank.create
Aplicación de agenteApplication.callclient.apps.completions.create
Gestión de archivosFiles.upload/list/get/deleteclient.files.upload/list/get/delete
Lista de modelosModels.list/getclient.models.list/get

Construcción del cliente y autenticación

La versión 1.x se configura mediante variables globales a nivel de módulo; la 2.0 se configura mediante argumentos del constructor Client (prioridad: constructor > dashscope.settings > variables de entorno > ~/.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",
)

Generación de texto 

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

Generación de imágenes 

# 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)
Las tareas por pasos (en 1.x async_call/fetch/wait) se corresponden con client.images.jobs.create/fetch/wait; la comprobación del estado de la tarea cambia de rsp.output.task_status == 'SUCCEEDED' a job.succeeded.

Generación de 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)
En 1.x, extend_prompt de VideoSynthesis tiene el valor predeterminado True; en 2.0 se llama prompt_extend y el valor predeterminado lo decide el servidor. Las llamadas que dependían del valor predeterminado anterior deben pasar prompt_extend=True de forma explícita.

Transcripción de archivos de 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))
El control por pasos (el antiguo async_call + bucle fetch) se corresponde con client.audio.asr.jobs.create + un bucle jobs.fetch.

Reconocimiento de voz en tiempo real

La versión 1.x usa clases de callback (Recognition + RecognitionCallback); la 2.0 usa un gestor de contexto + iteración de eventos. 
# 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()
El reconocimiento puntual de archivos locales (en 1.x Recognition.call(file)) se corresponde con for event in client.audio.asr.recognize_file(path, model=...):.

Síntesis de voz

En 1.x, tts_v2 recibe el audio mediante callbacks; en 2.0 se usa el estilo de iteración/sesión. 
# 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 síntesis puntual usa client.audio.tts.synthesize(text, model=..., voice=...); el streaming puro itera client.audio.tts.stream(text, ...).

Embeddings y 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))
Los embeddings por lotes (en 1.x BatchTextEmbedding) se corresponden con client.embeddings.jobs.create/fetch/wait. TextReRank.call se corresponde con client.rerank.create, y los resultados pasan de resp.output.results[i] a resp.results[i].

Llamadas a aplicaciones de agente 

# 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}')
Las llamadas en streaming a aplicaciones conservan el parámetro incremental_output (determina la forma de las tramas); la salida por trama pasa de response.output.text a partial.text.

Diferencias de comportamiento

Además de los nombres de las interfaces, tenga en cuenta las siguientes diferencias de comportamiento al migrar:
  • Manejo de errores: en 1.x se comprueban status_code/code en la respuesta; 2.0 lanza por defecto la familia de excepciones DashScopeError (con e.code/e.status_code/e.request_id/e.message). Para un comportamiento de tipo envolvente, construya Client(raise_on_error=False).
  • Salida en streaming: en 1.x, Generation.call(stream=True) reenvía por defecto el texto completo en cada trama (incremental_output=True para obtener solo los incrementos); en 2.0 el streaming es siempre incremental. Las aplicaciones de Model Studio (apps.completions) conservan el interruptor incremental_output.
  • Espera de tareas asíncronas: en 1.x, wait espera indefinidamente por defecto y devuelve una respuesta de error al agotar el tiempo de espera; en 2.0, jobs.wait tiene un presupuesto total predeterminado de 24 horas, realiza sondeo con retroceso exponencial y lanza una excepción si la tarea termina en estado FAILED.
  • Estructura de la respuesta: en 1.x el contenido útil va envuelto bajo output (response.output.choices[...]); en 2.0 es plano (response.choices[...]), con accesos directos como resp.output_text y job.succeeded.
  • Parámetros fuera de la firma: los métodos de recursos de 2.0 tienen firmas nombradas cerradas; los parámetros específicos del modelo que en 1.x se pasaban directamente deben enviarse vía parameters={...} (los materiales de imagen vía extra_input=).

Documentación relacionada