DashScope Python SDK

English | 中文

The DashScope Python SDK provides a comprehensive interface to Alibaba Cloud Model Studio (Bailian) APIs, covering text generation, multi-modal understanding, embeddings, reranking, image/video generation, speech synthesis & recognition, and more.

What is New

v1.27.0 ships an interactive AI assistant — DashScope SDK Expert. Run dashscope with no arguments (or ask directly with dashscope expert "how do I stream Generation output") to get SDK/API answers, runnable examples, CLI usage, and error diagnosis right in your terminal. Guidance is drawn from per-domain quick-reference skills (text, multimodal, speech, retrieval, fine-tuning, agent, cli) built on the SDK's public interfaces — parameters, outputs, and error codes — so you can ask instead of reading the docs. Type /help inside the assistant to view available commands.

Installation

To install the DashScope Python SDK, simply run:

pip install dashscope

The base install covers SDK API calls and the dashscope CLI command. Optional feature groups are available as extras:

If you clone the code from github, you can install from source by running:

pip install -e .

Quick Start

from http import HTTPStatus
from dashscope import Generation

responses = Generation.call(
    model="qwen-plus",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "Who are you?"},
    ],
    result_format="message",
)

if responses.status_code == HTTPStatus.OK:
    print(responses.output.choices[0].message.content)
else:
    print(f"Error: {responses.code} - {responses.message}")

API Key Authentication

The SDK uses API key for authentication. To obtain an API Key, see How to get an API Key. Please refer to official documentation for alibabacloud china and official documentation for alibabacloud international regarding how to obtain your api-key.

Using the API Key

1. Set the API key via code

import dashscope

dashscope.api_key = 'YOUR-DASHSCOPE-API-KEY'
# Or specify the API key file path via code
# dashscope.api_key_file_path='~/.dashscope/api_key'

2. Set the API key via environment variables

a. Set the API key directly using the environment variable below

export DASHSCOPE_API_KEY='YOUR-DASHSCOPE-API-KEY'

b. Specify the API key file path via an environment variable

export DASHSCOPE_API_KEY_FILE_PATH='~/.dashscope/api_key'

3. Save the API key to a file

from dashscope import save_api_key

save_api_key(api_key='YOUR-DASHSCOPE-API-KEY',
             api_key_file_path='api_key_file_location or (None, will save to default location "~/.dashscope/api_key"')

Region and Endpoint Configuration

By default the SDK sends requests to the China (Beijing) public endpoint dashscope.aliyuncs.com. If your Model Studio (Bailian) workspace lives in another region, switch the endpoint before making calls.

Using set_region

dashscope.set_region(region, workspace_id) points the HTTP, WebSocket and OpenAI-compatible base URLs at the given region in a single call. workspace_id is required and is used as the endpoint subdomain.

import dashscope

# Switch to the Singapore region for workspace "ws-xxx123"
dashscope.set_region(region="ap-southeast-1", workspace_id="ws-xxx123")

# All subsequent calls use:
#   https://ws-xxx123.ap-southeast-1.maas.aliyuncs.com/api/v1
print(dashscope.base_http_api_url)

Supported regions:

API keys are region-specific. Each region issues its own API keys (sk- prefix) in its Model Studio console, and keys cannot be mixed across regions — using a key from another region fails with 401. Switch api_key together with the region.

Region-specific notes:

• WebSocket endpoints (wss://.../api-ws/v1/inference) are only served in cn-beijing and ap-southeast-1. set_region still sets base_websocket_api_url for every region, but WebSocket-based realtime APIs (realtime speech recognition/synthesis, multimodal dialog, etc.) are not available in the other regions.
• eu-central-1 / ap-northeast-1: the deployment scope (Global, or EU / Japan) is chosen when the workspace is created in the console, not per API call.
• us-east-1: model names with the -us suffix (e.g. qwen-plus-us) restrict inference to the US; names without the suffix default to global inference.
• Batch inference, model fine-tuning and application development are currently only available in cn-beijing and ap-southeast-1.

set_region updates process-wide globals, so it is not concurrency-safe when a single process talks to multiple regions at the same time. Call it once at startup, or re-call it before each switch.

Using environment variables

You can also select the region without code:

export DASHSCOPE_API_REGION='ap-southeast-1'   # default: cn-beijing
export DASHSCOPE_WORKSPACE_ID='ws-xxx123'      # used to resolve the endpoint subdomain

When a MaaS region is set via DASHSCOPE_API_REGION, the SDK builds the regional endpoints and substitutes DASHSCOPE_WORKSPACE_ID into them. You can also override each base URL directly:

set_region always builds workspace-exclusive endpoints. Some regions also offer shared domains without a workspace subdomain — dashscope.aliyuncs.com (Beijing), dashscope-intl.aliyuncs.com (Singapore) and dashscope-us.aliyuncs.com (US Virginia); use the override variables above to point at them.

OpenAI-compatible chat completions

The SDK exposes an OpenAI-compatible chat completions entry that talks to dashscope.base_compatible_api_url (request path chat/completions) — no extra openai package required. It follows the region configured above.

import dashscope
from dashscope.aigc.chat_completion import Completions

dashscope.set_region(region="cn-hongkong", workspace_id="ws-hk-789")

response = Completions.create(
    model="qwen-max",
    messages=[{"role": "user", "content": "Hello"}],
    api_key="YOUR-DASHSCOPE-API-KEY",
    stream=False,  # set True to get a generator of ChatCompletionChunk
)
print(response)

A complete runnable example is available in samples/set_region_example.py.

AI Assistant: DashScope SDK Expert

The SDK ships with an interactive AI assistant, DashScope SDK Expert, built on the bundled Agentic CLI (dashscope/acli) framework. For DashScope SDK/CLI users it is the recommended way to get development consultation and AI coding help — answering SDK/API questions, generating runnable examples, showing CLI usage, and diagnosing errors, right in your terminal.

• Run dashscope with no arguments to start the assistant. On first run it offers to install the SDK Expert knowledge pack (per-domain quick-reference skills: text, multimodal, speech, retrieval, fine-tuning, agent, cli), so guidance comes from the SDK's public interfaces — parameters, outputs, error codes — without reading the source
• Ask it instead of reading docs — e.g. dashscope expert "how do I stream Generation output" or dashscope expert "CLI command to cancel a fine-tuning job", each of which asks once and exits. Type /help inside the assistant to list available commands (/setup, /skill, /stats, ...); classic SDK subcommands still work, plain dashscope expert enters the assistant interactively, and dashscope expert --help shows all the forms
• Full walkthrough: DashScope SDK Expert guide

Supported Models

For the latest model list, visit Bailian Model Plaza.

Shell Completion

Run the appropriate command once, then restart your shell (or re-source your config file):

To preview the completion script without installing:

dashscope --show-completion bash

Logging

To output Dashscope logs, you need to configure the logger.

export DASHSCOPE_LOGGING_LEVEL='info'

Output

The output contains the following fields:

     request_id (str): The request id.
     status_code (int): HTTP status code, 200 indicates that the
         request was successful, others indicate an error.
     code (str): Error code if error occurs, otherwise empty str.
     message (str): Set to error message on error.
     output (Any): The request output.
     usage (Any): The request usage information.

License

This project is licensed under the Apache License (Version 2.0).