DashScope Python SDK

Warnings

• gotcha Missing or incorrect API Key configuration leads to `AuthenticationError`. The SDK requires an API key for authentication, which can be set via `dashscope.api_key`, the `DASHSCOPE_API_KEY` environment variable, or by specifying an API key file path.
  Fix: Ensure `DASHSCOPE_API_KEY` environment variable is set or `dashscope.api_key = 'YOUR_API_KEY'` is used before making calls. For file-based keys, use `DASHSCOPE_API_KEY_FILE_PATH` or `dashscope.api_key_file_path`.
• gotcha Incorrect `base_http_api_url` for your region can cause 'invalid API key' or 'url error' even if the key is correct. Alibaba Cloud DashScope has different endpoints for international (e.g., Singapore) and Mainland China regions.
  Fix: Explicitly set `dashscope.base_http_api_url` to the correct endpoint for your region. For international, often `https://dashscope-intl.aliyuncs.com/api/v1`. For Mainland China, `https://dashscope.aliyuncs.com/api/v1` or `https://dashscope.aliyuncs.com/compatible-mode/v1`.
• gotcha Using the wrong API endpoint/method for the model type (e.g., `Generation.call()` for multimodal models or `MultiModalConversation.call()` for plain text models) results in 'url error' or invalid parameter errors.
  Fix: Use `Generation.call()` for text-only models (like Qwen-Turbo, Qwen-Plus) and `MultiModalConversation.call()` for multimodal models (like Qwen-VL, Qwen-Omni) that accept image or video inputs.
• gotcha When `stream=True` is enabled for generation, the API returns a generator object, not a direct response. You must iterate over this generator to receive streaming chunks of results.
  Fix: If `stream=True`, iterate through the `responses` object (e.g., `for chunk in responses: print(chunk.output.choices[0].text)`).
• gotcha Multimodal models have strict limits on local file sizes (e.g., 10MB after Base64 encoding for images) and specific URL requirements. Exceeding these limits or providing corrupted/incorrect formats will lead to errors like 'Multimodal file size is too large' or 'read image error'.
  Fix: Adhere to the specified file size limits and ensure image/video formats are supported. For local files, ensure they are correctly Base64 encoded if required by the API specifications for direct content inclusion.

Install

• pip install dashscope Standard install
• pip install dashscope[tokenizer] Install with local tokenizer support

Imports

• Generation

  from dashscope import Generation

  Generation is a direct import from the dashscope package for text generation APIs.
• MultiModalConversation

  from dashscope import MultiModalConversation

  Used specifically for multimodal models that handle image and text inputs.
• save_api_key

  from dashscope import save_api_key

  A utility function to persist your API key to a file.
• dashscope

  import dashscope

  Needed for global configurations like 'dashscope.api_key' or 'dashscope.base_http_api_url'.

Quickstart

This quickstart demonstrates how to use the `dashscope.Generation` API to interact with an LLM, such as `qwen-turbo`. It emphasizes setting the API key via an environment variable for security and includes basic error handling. It also highlights the importance of potentially setting the `base_http_api_url` for different regions.

import os
from http import HTTPStatus
from dashscope import Generation

# Set your DashScope API key via environment variable for security
# export DASHSCOPE_API_KEY='YOUR_API_KEY'
dashscope_api_key = os.environ.get('DASHSCOPE_API_KEY', '')

if not dashscope_api_key:
    print("Error: DASHSCOPE_API_KEY environment variable not set.")
    print("Please set it using: export DASHSCOPE_API_KEY='YOUR_API_KEY'")
else:
    # Set the API key programmatically if not using environment variable or for testing
    # dashscope.api_key = dashscope_api_key 
    
    # For models in specific regions, you might need to set the base URL.
    # For Singapore region (international users):
    # dashscope.base_http_api_url = 'https://dashscope-intl.aliyuncs.com/api/v1'
    # For China (Beijing) region:
    # dashscope.base_http_api_url = 'https://dashscope.aliyuncs.com/api/v1'

    print("Calling DashScope LLM...")
    responses = Generation.call(
        model=Generation.Models.qwen_turbo, # or 'qwen-plus', 'qwen-max', etc.
        prompt='Tell me a short story about a brave knight.',
        api_key=dashscope_api_key # It's good practice to explicitly pass the key or ensure it's set globally
    )

    if responses.status_code == HTTPStatus.OK:
        print('Story generated:')
        print(responses.output.text)
    else:
        print(f'Failed request_id: {responses.request_id}, status_code: {responses.status_code}, ')
        print(f'code: {responses.code}, message: {responses.message}')