Skip to main content

Referência de uso legado do SDK Python do DashScope 1.x

Referência de uso legado e mapeamento de migração de 1.x para 2.0 do SDK Python do DashScope, para projetos existentes que ainda usam a versão 1.x.

Esta página destina-se a projetos existentes que ainda usam o SDK Python do DashScope 1.x. Ela reúne em um só lugar os usos típicos das interfaces 1.x e mostra o código 2.0 equivalente.
Para novos projetos, use o SDK 2.0 diretamente. A versão do SDK 1.x está em manutenção congelada (apenas correções de defeitos); 1.x e 2.0 coexistem no mesmo pacote dashscope (a partir da 2.0.1), de modo que o código existente pode migrar de forma incremental sem remover as dependências 1.x. A família de APIs Assistants / Threads / Runs foi desativada junto com a 1.x e não é mais compatível no servidor; não a use em código novo.

Mapeamento de migração de interfaces

CapacidadeInterface 1.xInterface 2.0
Geração de textoGeneration.call / AioGeneration.callclient.chat.completions.create
Chat multimodalMultiModalConversation.callclient.multimodal.chat.create
Geração de imagensImageSynthesis.call/async_call/fetch/waitclient.images.generate / client.images.jobs.*
Geração de vídeoVideoSynthesis.call/async_call/fetch/waitclient.videos.generate / client.videos.jobs.*
Transcrição de arquivos de áudioTranscription.async_call/fetch/waitclient.audio.asr.transcribe / client.audio.asr.jobs.*
Reconhecimento de fala em tempo realRecognition.start/send_audio_frame/stopclient.audio.asr.recognize(...) context manager
Síntese de falaSpeechSynthesizer (tts_v2 callback style)client.audio.tts.synthesize/stream/connect
Embeddings de textoTextEmbedding.call / BatchTextEmbeddingclient.embeddings.create / client.embeddings.jobs.*
RerankTextReRank.callclient.rerank.create
Aplicação de agenteApplication.callclient.apps.completions.create
Gerenciamento de arquivosFiles.upload/list/get/deleteclient.files.upload/list/get/delete
Lista de modelosModels.list/getclient.models.list/get

Construção do cliente e autenticação

A versão 1.x é configurada por variáveis globais no nível do módulo; a 2.0 é configurada pelos argumentos do construtor Client (prioridade: construtor > dashscope.settings > variáveis de ambiente > ~/.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",
)

Geração 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)

Geração de imagens

# 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)
Tarefas passo a passo (1.x async_call/fetch/wait) correspondem a client.images.jobs.create/fetch/wait; a verificação do status da tarefa muda de rsp.output.task_status == 'SUCCEEDED' para job.succeeded.

Geração de vídeo

# 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)
Na versão 1.x, extend_prompt de VideoSynthesis tem padrão True; na 2.0 ele se chama prompt_extend e o padrão é decidido pelo servidor. Chamadas que dependiam do padrão antigo devem passar prompt_extend=True explicitamente.

Transcrição de arquivos de áudio

# 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))
O controle passo a passo (antigo async_call + laço fetch) corresponde a client.audio.asr.jobs.create + um laço jobs.fetch.

Reconhecimento de fala em tempo real

A versão 1.x usa classes de callback (Recognition + RecognitionCallback); a 2.0 usa um gerenciador de contexto + iteração 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()
O reconhecimento pontual de arquivo local (1.x Recognition.call(file)) corresponde a for event in client.audio.asr.recognize_file(path, model=...):.

Síntese de fala

Na 1.x, tts_v2 recebe o áudio via callbacks; na 2.0 usa-se o estilo de iteração/sessão.
# 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)
A síntese pontual usa client.audio.tts.synthesize(text, model=..., voice=...); o streaming puro itera client.audio.tts.stream(text, ...).

Embeddings e 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))
Embeddings em lote (1.x BatchTextEmbedding) correspondem a client.embeddings.jobs.create/fetch/wait. O TextReRank.call corresponde a client.rerank.create, e os resultados passam de resp.output.results[i] para resp.results[i].

Chamadas de aplicações 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}')
As chamadas de aplicação em streaming mantêm o parâmetro incremental_output (ele determina o formato dos frames); a saída por frame passa de response.output.text para partial.text.

Diferenças de comportamento

Além dos nomes das interfaces, observe estas diferenças de comportamento ao migrar:
  • Tratamento de erros: a 1.x verifica status_code/code na resposta; a 2.0 lança por padrão a família de exceções DashScopeError (com e.code/e.status_code/e.request_id/e.message). Para um comportamento no estilo envelope, construa Client(raise_on_error=False).
  • Saída em streaming: na 1.x, Generation.call(stream=True) reproduz por padrão o texto completo em cada frame (incremental_output=True para deltas); na 2.0 os streams são sempre incrementais. As aplicações do Model Studio (apps.completions) mantêm a opção incremental_output.
  • Espera de tarefas assíncronas: o wait da 1.x espera indefinidamente por padrão e retorna uma resposta de erro no tempo limite; o jobs.wait da 2.0 tem um orçamento total padrão de 24 horas, sondagem com backoff exponencial e lança exceção em tarefas FAILED.
  • Estrutura da resposta: a 1.x envolve o conteúdo útil sob output (response.output.choices[...]); a 2.0 é plana (response.choices[...]), com atalhos como resp.output_text e job.succeeded.
  • Parâmetros fora da assinatura: os métodos de recursos da 2.0 têm assinaturas nomeadas fechadas; parâmetros específicos do modelo repassados na 1.x devem ir via parameters={...} (materiais de imagem via extra_input=).

Documentação relacionada