Alibaba Cloud Model Studio API setup

Identify the region, workspace and model

This guide uses the OpenAI-compatible text chat API in Alibaba Cloud International Model Studio. Start with an authorised account, enabled service, accessible workspace and model permissions. Record the access region, workspace, service deployment scope, actual model ID, billing plan and limits. A name in a general model catalogue is not proof that the same ID is callable from your workspace.

Check access and storage location separately from the service deployment scope that determines inference location. “OpenAI-compatible” does not establish availability of a model, global inference or a subscription plan. This guide does not create a workspace, request quota or enable paid services on your behalf.

Match the endpoint and key

Copy the API Host from Workspace Management and combine it with the selected protocol’s path. OpenAI compatibility uses /compatible-mode/v1; native DashScope /api/v1 is a different interface. The example below shows the shape of a Singapore workspace-specific hostname. Replace the workspace placeholder and use the actual console Host for other regions rather than guessing a domain.

The key must match region, target workspace and billing plan. Do not mix a pay-as-you-go key with a dedicated Coding Plan or Token Plan endpoint. Those plans currently target interactive coding tools rather than backend model services. If an older tutorial differs, consult the current Base URL page and workspace console. Do not assume International and China site accounts, quotas or prices are interchangeable.

Install and configure placeholders

python3 -m venv .venv
. .venv/bin/activate
python -m pip install --upgrade openai

Have the authorised server environment supply DASHSCOPE_API_KEY securely. These public placeholder values cannot produce a successful call unchanged. Replace MODEL_STUDIO_MODEL only after checking text chat, streaming and max_tokens support. Some models require streaming, so a failed non-streaming test alone does not establish that the model is unavailable.

export MODEL_STUDIO_BASE_URL='https://YOUR-WORKSPACE.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1'
export MODEL_STUDIO_MODEL='YOUR-ACTUAL-TEXT-MODEL-ID'

Make a minimal stream and read usage

Save the code as model_studio_chat.py. Run python model_studio_chat.py only after approving charges and testing access. The output cap of 128 and client timeout of 30 seconds are local example controls; automatic SDK retries start at zero. These values are not service quotas, maximum processing times or support commitments.

import os
from openai import OpenAI

client = OpenAI(
    base_url=os.environ["MODEL_STUDIO_BASE_URL"],
    api_key=os.environ["DASHSCOPE_API_KEY"],
    timeout=30.0,
    max_retries=0,
)
usage = None
finish_reason = None
with client.chat.completions.create(
    model=os.environ["MODEL_STUDIO_MODEL"],
    messages=[{"role": "user", "content": "Reply with one short greeting."}],
    max_tokens=128,
    stream=True,
    stream_options={"include_usage": True},
) as events:
    for part in events:
        if part.usage is not None:
            usage = part.usage
        if not part.choices:
            continue
        choice = part.choices[0]
        if choice.delta.content:
            print(choice.delta.content, end="", flush=True)
        if choice.finish_reason is not None:
            finish_reason = choice.finish_reason
print()
print("finish_reason:", finish_reason)
print(usage.model_dump() if usage else "usage unavailable")

The include_usage option requests metering information. A final usage chunk can have empty choices, so read usage before checking the list. Text comes from delta.content, not the non-streaming message.content field. Do not stop at the first finish reason and miss a later usage chunk. If a stream breaks before usage arrives, record it as unavailable rather than zero or free.

This parser handles ordinary text. Tool calls, reasoning content, images and audio need separate handling of their documented structures. Treat a partially displayed answer as an incomplete task unless your workflow explicitly accepts partial results.

Investigate failures by type

401/403: check the key’s region, workspace, plan and permissions. Never paste complete authentication data into a ticket.
404 or unknown model: check Host, compatibility path, exact ID and workspace availability. Avoid obsolete suffixes from another region.
400: check the model’s input, output cap and optional parameters. Isolate the issue using a short ordinary text prompt.
429: examine request, token and concurrency limits together. Apply bounded backoff according to the returned error and rate-limit guidance.
Timeout/5xx: retain sanitised request identifiers and timestamps, limit retries and do not report partial output as full success.

Check cost, safety and acceptance

Reconcile the actual model, region and deployment scope against console usage and invoices. Streaming does not remove generation charges; a disconnected client does not prove immediate server cancellation. Set separate controls for output, concurrency, overall task duration and tool loops. A budget alert is not a hard calling limit. No price, discount or plan guarantee is provided here.

Current retention policy allows default inference input/output retention of up to 30 days with legal or security exceptions. ZDR requires approval and has model and path limits; metering, safety records and stateful features have separate boundaries. Review the actual workspace and contract before sensitive use, and control application logs independently.

Acceptance should cover ordinary completion, truncation, empty-choice usage chunks, disconnection, throttling and permission failures. Record model ID, route, finish reason and metering. The example only received offline syntax checks: no key was read, no model was called and no account-specific availability was verified.

Official references

Checked on 17 October 2026. Use the current workspace configuration and documentation.