TPM 预留 DashScope OpenAPI 接口文档

接口概述

TPM 预留 DashScope OpenAPI 提供六个 REST 接口，覆盖 TPM 预留部署的创建、查询、扩缩容、续订与溢出策略全生命周期管理。通过 plan=ptu 标识 TPM 预留场景，结合 service_tier 区分部署类型。

• POST /api/v1/deployments — 创建 TPM 预留部署
• GET /api/v1/deployments/{deployed_model} — 查询单个部署状态与配置
• GET /api/v1/deployments — 分页列表查询
• PUT /api/v1/deployments/{deployed_model}/scale — 扩缩容
• PUT /api/v1/deployments/{deployed_model}/renew — 续订预付费部署
• PUT /api/v1/deployments/{deployed_model}/updateOverflowStrategy — 修改溢出策略

service_tier 取值：ptu_default 对应 TPM 预留（容量保障）场景，ptu_fast 对应 PTU v2 通用部署场景。创建 TPM 预留部署时传 service_tier=ptu_default。

deployed_model 为部署服务 ID，格式为 {model_name}-ptu-{随机后缀}，由后端自动生成，用作路径参数。

ptu_capacity 容量单位为 kTPM（1 kTPM = 1000 Tokens/分钟），包含 input_tpm、output_tpm、thinking_output_tpm 三个独立维度。起跑和步长因模型而异，以控制台创建页展示为准。

• 华北2（北京）支持的模型：千问3.8-Max、千问3.7-Max-2026-05-20、千问3.7-Plus-2026-05-26、千问3.6-Flash-2026-04-16、GLM-5.2、GLM-5.1、DeepSeek-v4-Flash、DeepSeek-v4-Pro、Kimi-K2.6
• 新加坡区域无 Kimi-K2.6，其余模型一致
• 上述 9 款模型均支持思考输出配额（thinking_output_tpm），思考模型家族与启用方式详见深度思考模型

认证方式、请求头与 endpoint 域名配置详见认证与调用准备。控制台操作入口与 TPM 预留概念详见TPM 预留，通用部署创建 API 详见使用 API 进行模型部署。

认证与调用准备

调用 TPM 预留 OpenAPI 使用百炼 API Key 认证，请求头携带 Authorization: Bearer <api-key>。API Key 与区域绑定，不可跨区调用。

• DashScope 原生 SDK：当前支持 Python 与 Java
• OpenAI 兼容 SDK：当前支持 Python、Node.js、Java、Go，调用路径前缀为 /compatible-mode/v1

如需指定子业务空间，请求头携带 X-DashScope-WorkSpace: <workspace-id>。workspace-dedicated 域名格式为 [workspaceId].[region].maas.aliyuncs.com，区域包括 cn-beijing、ap-southeast-1、ap-northeast-1、eu-central-1。模型部署简介与三种计费方式对比详见模型部署。

创建 TPM 预留部署

调用 POST /api/v1/deployments 创建 TPM 预留部署。请求体须指定基础模型、计费类型与 TPM 容量配置，创建后状态为 DEPLOYING，部署完成后变为 RUNNING。

TPM 预留创建不传 suffix，后端自动生成部署服务 ID（deployed_model）。

创建后状态流转：DEPLOYING → RUNNING。

{
  "model_name": "qwen-max",
  "plan": "ptu",
  "service_tier": "ptu_default",
  "charge_type": "pre_paid",
  "name": "通义千问-Max TPM预留",
  "ptu_capacity": {
    "input_tpm": 100000,
    "output_tpm": 50000,
    "thinking_output_tpm": 20000
  },
  "pre_paid_info": {
    "auto_renewal": true,
    "duration": 30,
    "auto_renewal_duration": 30
  }
}

{
  "request_id": "xxx",
  "output": {
    "deployed_model": "qwen-max-ptu-a1b2c3d4",
    "model_name": "qwen-max",
    "plan": "ptu",
    "status": "DEPLOYING",
    "ptu_capacity": {
      "input_tpm": 100000,
      "output_tpm": 50000,
      "thinking_output_tpm": 20000
    }
  }
}

查询部署

TPM 预留 OpenAPI 提供单个查询与列表查询两种方式，分别用于查看指定部署详情和分页浏览全部部署。

{
  "request_id": "xxx",
  "output": {
    "deployed_model": "qwen-max-ptu-a1b2c3d4",
    "model_name": "qwen-max",
    "plan": "ptu",
    "service_tier": "ptu_default",
    "status": "RUNNING",
    "charge_type": "pre_paid",
    "ptu_capacity": {
      "input_tpm": 100000,
      "output_tpm": 50000
    },
    "gmt_created": "2024-01-01T00:00:00Z",
    "gmt_modified": "2024-01-01T12:00:00Z"
  }
}

{
  "request_id": "xxx",
  "output": {
    "deployments": [
      {
        "deployed_model": "qwen-max-ptu-a1b2c3d4",
        "model_name": "qwen-max",
        "plan": "ptu",
        "status": "RUNNING",
        "ptu_capacity": { "input_tpm": 100000, "output_tpm": 50000 }
      }
    ],
    "total": 1,
    "page_no": 1,
    "page_size": 10
  }
}

扩缩容

调用 PUT /api/v1/deployments/{deployed_model}/scale 对 TPM 预留部署执行扩缩容，请求体传入新的 ptu_capacity 配置。

{
  "ptu_capacity": {
    "input_tpm": 200000,
    "output_tpm": 100000
  }
}

{
  "request_id": "xxx",
  "output": {
    "deployed_model": "qwen-max-ptu-a1b2c3d4",
    "model_name": "qwen-max",
    "plan": "ptu",
    "status": "SCALING",
    "ptu_capacity": {
      "input_tpm": 200000,
      "output_tpm": 100000
    }
  }
}

预付费扩缩容触发商业化下单（UPGRADE/DOWNGRADE），异步完成后状态变为 RUNNING。后付费扩缩容直接生效，不触发下单。

扩缩容方向约束：input_tpm、output_tpm、thinking_output_tpm 须同增或同减，混合方向会报错。

仅 plan=ptu（内部 ptu_v2）的部署支持扩缩容操作。

续订

调用 PUT /api/v1/deployments/{deployed_model}/renew 续订预付费 TPM 预留部署，请求体传入 pre_paid_info 续费信息。

{
  "pre_paid_info": {
    "auto_renewal": true,
    "duration": 30,
    "auto_renewal_duration": 30
  }
}

{
  "pre_paid_info": {
    "auto_renewal": false,
    "duration": 1
  }
}

{
  "request_id": "xxx",
  "output": {
    "deployed_model": "qwen-max-ptu-a1b2c3d4",
    "model_name": "qwen-max",
    "plan": "ptu",
    "status": "WAIT_PRE_PAID_BILLING_TO_SCALING",
    "charge_type": "pre_paid",
    "ptu_capacity": { "input_tpm": 100000, "output_tpm": 50000 }
  }
}

duration 取值范围为 1~30、60、90、120、365 天，TPM 预留付费周期固定按天计费。

续费生效时间：22 点后提交的续订请求，到期时间顺延至 N+2 天 00:00。

续订后状态为 WAIT_PRE_PAID_BILLING_TO_SCALING，表示等待预付费账单处理完成。

修改溢出策略

调用 PUT /api/v1/deployments/{deployed_model}/updateOverflowStrategy 修改 TPM 预留部署的溢出策略。请求体传入 overflow_strategy 字段。

{
  "overflow_strategy": "disable"
}

{
  "request_id": "xxx",
  "output": {
    "deployed_model": "qwen-max-ptu-a1b2c3d4",
    "model_name": "qwen-max",
    "plan": "ptu",
    "status": "RUNNING",
    "overflow_strategy": "disable",
    "ptu_capacity": { "input_tpm": 100000, "output_tpm": 50000 }
  }
}

该接口为后端独立 API，前端控制台无封装。开发者通过 OpenAPI 直接调用，溢出策略可随时切换无需重建部署。溢出策略概念详见预置吞吐长输入与缓存。

错误码

调用 TPM 预留 OpenAPI 时如遇错误，响应体返回 request_id、code、message 三个字段，可根据错误码定位问题。

{
  "request_id": "xxx",
  "code": "Throttling.AllocationQuota",
  "message": "..."
}

429 限流错误中，TPM 容量超额走 AllocationQuota 错误码。限流应对最佳实践详见限流应对最佳实践。

常见问题