All Products
Search

This Product

    Alibaba Cloud Model Studio:Access Model Studio APIs over a private network

    Document Center

    Alibaba Cloud Model Studio:Access Model Studio APIs over a private network

    Last Updated:Sep 28, 2026

    To call Model Studio APIs from a VPC without routing traffic over the public internet, add a PrivateLink connection in the Model Studio console and associate it with your workspace.

    How it works

    The Model Studio gateway supports the following two access methods:

    • Public network access: Call Model Studio APIs over the public MaaS domain name {WorkspaceId}.{RegionId}.maas.aliyuncs.com. Traffic is routed over the public internet.
    • PrivateLink private connection: Add a PrivateLink connection for your VPC in the Model Studio console, and then call Model Studio APIs over the private domain name. Traffic stays within the Alibaba Cloud network and does not traverse the public internet.

    After you add a PrivateLink connection in the Model Studio console, PrivateLink establishes a private connection (endpoint connection) between your VPC and Model Studio. The connection is unidirectional: resources in your VPC can access Model Studio, but Model Studio cannot access your VPC through this connection.

    When resources in your VPC access the private domain name, PrivateLink routes traffic to Model Studio without traversing the public internet.

    image

    Model Studio is available in the following regions:

    • Public cloud: China (Beijing) and China (Hong Kong).

      Private network access is not currently supported in other regions.

    1. Log on to the Model Studio console. In the left-side navigation pane, choose Settings > Network configuration.

    2. The first time you use this feature, complete the following preparations in the Add PrivateLink panel:

      • Authorize service-linked role for PrivateLink: Click Authorize Now, and then click Confirm Authorization to create the service-linked role AliyunServiceRoleForBackrouterAccessNet.
      • Activate PrivateLink: Click Enable Now to activate the PrivateLink service.

    3. In the VPC private network access section, click Add and configure the following parameters. Leave the other parameters at their default values.

      • Region: Select the region of your Model Studio service, for example, China (Hong Kong).
      • VPC: Select the VPC from which you want to access Model Studio. The PrivateLink connection is created in this VPC, and only resources such as ECS instances and containers in this VPC can reach Model Studio through the private domain name. If no VPC is available, click Create VPC to create one in the VPC console.
      • Zones and Switches: Select a zone that is supported by Model Studio and contains a vSwitch, and then select the vSwitch. The PrivateLink connection occupies one internal IP address of the selected vSwitch in each zone as the internal DNS resolution address of the private domain name. You can add up to two zone and vSwitch combinations. Add two for high availability so that traffic can fail over if one zone becomes unavailable. If no vSwitch is available, click Create Switch to create one in the VPC console.
      • Security Group: Select the security group to associate with the PrivateLink connection. The security group controls which resources can access the connection. Make sure that the security group allows inbound traffic on port 443 (HTTPS). If no security group is available, click Create Security Group to create one in the ECS console.

    4. Click Confirm and wait until the Status of the connection changes to Created. The connection takes effect in about 1 to 3 minutes. After it takes effect, any cloud server in the VPC can use the private domain name to access Model Studio.

    A workspace that needs to access Model Studio over the private network must be associated with a PrivateLink connection.

    1. In the left-side navigation pane of the Model Studio console, choose Workspaces, and then create a workspace or edit the target workspace.
    2. In Advanced Configuration, set PrivateLink to the target PrivateLink connection. Each option shows the endpoint ID with its region and VPC. If the target connection is not listed, click Create PrivateLink in the drop-down list to create one. After the association, the workspace can access Model Studio through the private connection of the corresponding VPC.
    3. To remove the association, edit the workspace, clear PrivateLink, and save the changes. Alternatively, on the Network configuration page, expand the row of the target PrivateLink connection and click Unbind in the Associated workspace column to go to the corresponding workspace. A PrivateLink connection that is associated with workspaces cannot be deleted until it is unbound.

    Step 3: Get the private domain name

    After you complete Step 2, a private domain name is generated for each associated workspace. On the Network configuration page, expand the row of the target PrivateLink connection in the VPC private network access list and copy the private domain name in the Endpoint column. The Associated workspace column shows the ID of the workspace to which the domain name belongs. The private domain name is in the format of {WorkspaceId}-{VpcId}.{region-id}.maas.aliyuncs.com, where WorkspaceId is the workspace ID and VpcId is the ID of the VPC to which the PrivateLink connection belongs.

    You can also find the private domain name in the API Host column of the target workspace on the Workspaces page. After the association, this column lists both the public and the private domain name.

    The private domain name can be resolved and accessed only within the selected VPC. Use HTTPS (port 443) to call Model Studio APIs. If no workspace is associated, the Endpoint column in the expanded row is empty.

    Step 4: Verify the connection

    Replace the domain name in the base_url of your API request with the private domain name from the previous step, and then make the call from within the VPC.

    For example, to call the Qwen text model in OpenAI-compatible mode:

    • Before replacement: https://{WorkspaceId}.{RegionId}.maas.aliyuncs.com/compatible-mode/v1/chat/completions
    • After replacement: https://{WorkspaceId}-{VpcId}.{RegionId}.maas.aliyuncs.com/compatible-mode/v1/chat/completions

    Example call:

    # Replace the original domain name with the private domain name from the previous step.
curl -X POST https://{WorkspaceId}-{VpcId}.{RegionId}.maas.aliyuncs.com/compatible-mode/v1/chat/completions \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
    "model": "qwen-flash",
    "messages": [
        {
            "role": "system",
            "content": "You are a helpful assistant."
        },
        {
            "role": "user",
            "content": "Who are you?"
        }
    ]
}'

    import os
from openai import OpenAI

client = OpenAI(
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    # Replace the original domain name with the private domain name from the previous step.
    base_url="https://{WorkspaceId}-{VpcId}.{RegionId}.maas.aliyuncs.com/compatible-mode/v1",
)
completion = client.chat.completions.create(
    model="qwen-flash",
    messages=[
        {'role': 'system', 'content': 'You are a helpful assistant.'},
        {'role': 'user', 'content': 'Who are you?'}],
)
print(completion.model_dump_json())

    import os
from http import HTTPStatus
# DashScope SDK version 1.14.0 or later is recommended.
import dashscope
from dashscope import Generation
# Replace the original domain name with the private domain name from the previous step.
dashscope.base_http_api_url = "https://{WorkspaceId}-{VpcId}.{RegionId}.maas.aliyuncs.com/api/v1"
dashscope.api_key = os.getenv("DASHSCOPE_API_KEY")
messages = [{
    'role': 'user', 'content': 'Who are you?'
}]
response = Generation.call(
    model="qwen-flash",
    messages=messages,
    result_format='message'
)
if response.status_code == HTTPStatus.OK:
    print(response)
else:
    print('Request id: %s, Status code: %s, error code: %s, error message: %s' % (
        response.request_id, response.status_code,
        response.code, response.message
    ))

    // DashScope SDK version 2.12.0 or later is recommended.
import java.util.Arrays;
import com.alibaba.dashscope.aigc.generation.Generation;
import com.alibaba.dashscope.aigc.generation.GenerationParam;
import com.alibaba.dashscope.aigc.generation.GenerationResult;
import com.alibaba.dashscope.common.Message;
import com.alibaba.dashscope.common.Role;
import com.alibaba.dashscope.exception.ApiException;
import com.alibaba.dashscope.exception.InputRequiredException;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.protocol.Protocol;
import com.alibaba.dashscope.utils.JsonUtils;
public class Main {
    public static GenerationResult callWithMessage() throws ApiException, NoApiKeyException, InputRequiredException {
        // Replace the original domain name with the private domain name from the previous step.
        Generation gen = new Generation(Protocol.HTTP.getValue(), "https://{WorkspaceId}-{VpcId}.{RegionId}.maas.aliyuncs.com/api/v1");
        Message systemMsg = Message.builder()
                .role(Role.SYSTEM.getValue())
                .content("You are a helpful assistant.")
                .build();
        Message userMsg = Message.builder()
                .role(Role.USER.getValue())
                .content("Who are you?")
                .build();
        GenerationParam param = GenerationParam.builder()
                .apiKey(System.getenv("DASHSCOPE_API_KEY"))
                .model("qwen-flash")
                .messages(Arrays.asList(systemMsg, userMsg))
                .resultFormat(GenerationParam.ResultFormat.MESSAGE)
                .build();
        return gen.call(param);
    }
    public static void main(String[] args) {
        try {
            GenerationResult result = callWithMessage();
            System.out.println(JsonUtils.toJson(result));
        } catch (ApiException | NoApiKeyException | InputRequiredException e) {
            // Print the error message.
            System.err.println("An error occurred while calling the generation service: " + e.getMessage());
        }
    }
}

    Before you make the call, make sure that you have obtained and configured an API key. To pass the API key directly, replace $DASHSCOPE_API_KEY with your API key.

    Billing

    Using PrivateLink incurs additional fees. For more information, see PrivateLink billing.

    FAQ

    1. Why can't my ECS instance access Model Studio APIs over the PrivateLink connection?

      Troubleshoot as follows:

      1. Check whether the ECS instance is in the same VPC as the PrivateLink connection.

        If the ECS instance is in a different VPC, it cannot access Model Studio over the private network. You must first configure VPC interconnection.

      2. Check the security group associated with the PrivateLink connection and make sure that an inbound rule allows traffic from the CIDR block of the ECS instance on port 443 (HTTPS).

      3. Check the status of the PrivateLink connection.

        The private domain name can be used only after the connection status is Created and the connection has taken effect (about 1 to 3 minutes after creation).

      4. Check whether the workspace is associated.

        A private domain name is generated only after a workspace is associated with the PrivateLink connection. If the Endpoint column in the expanded row is empty, associate the workspace as described in Step 2.

    2. Can an endpoint be accessed from the public internet?

      No. PrivateLink establishes private connections only within the Alibaba Cloud network. Endpoints cannot be accessed from the public internet, and endpoint ENIs cannot be associated with elastic IP addresses (EIPs).

    3. Do I need to associate a workspace with a legacy PrivateLink connection?

      No. A legacy PrivateLink connection, which was created as an interface endpoint in the PrivateLink (VPC) console, is associated with all workspaces by default. You can use it to access Model Studio APIs over the private network without performing Step 2.

      When you expand a legacy connection on the Network configuration page, the Endpoint column shows vpc-{region-id}.dashscope.aliyuncs.com (for example, vpc-ap-southeast-1.dashscope.aliyuncs.com), and the Associated workspace column indicates that the connection is associated with all workspaces. This differs from the current flow, which lists {WorkspaceId}-{VpcId}.{region-id}.maas.aliyuncs.com for each associated workspace.

      You can no longer create a PrivateLink connection in this way. To add one, follow Step 1 to create it in the Model Studio console, and then follow Step 2 to associate the workspaces that need private network access.