Skip to main content
模型生產

TPM 預留 DashScope OpenAPI 介面文檔

TPM 預留 DashScope OpenAPI 提供建立、擴縮容、查詢、續訂、溢出策略六個 REST 介面，支援通過 API Key 認證調用 TPM 預留部署全生命週期管理。

介面概述

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 與地區綁定，不可跨區調用。

要求標頭

必填

說明

類型

Authorization: Bearer <api-key>

必填

百鍊 API Key

Bearer Token

Content-Type: application/json

必填

請求體類型

固定值 application/json

X-DashScope-SSE: enable

流式必填

開啟流式輸出

枚舉值 enable

X-DashScope-Async: enable

非同步必填

非同步批處理

枚舉值 enable

X-DashScope-WorkSpace: <id>

可選

子業務空間 ID

工作空間 ID 字串

  • 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。模型部署簡介與三種計費方式對比詳見模型部署。

專案

網域名稱

DashScope API 網域名稱

https://dashscope-intl.aliyuncs.com

維吉尼亞地區

https://{WorkspaceId}.us-east-1.maas.aliyuncs.com

OpenAI 相容路徑首碼

/compatible-mode/v1

建立 TPM 預留部署

調用 POST /api/v1/deployments 建立 TPM 預留部署。請求體須指定基本模型、計費類型與 TPM 容量配置，建立後狀態為 DEPLOYING，部署完成後變為 RUNNING。

欄位

類型

必填

說明

model_name

String

必填

基本模型名，如 qwen-max

plan

String

必填

固定傳 ptu

service_tier

String

可選

ptu_default（TPM 預留）/ ptu_fast（PTU v2 通用，預設）

charge_type

String

必填

pre_paid（預付費）/ post_paid（後付費）

name

String

可選

部署展示名，不傳則自動產生

suffix

String

可選

TPM 預留建立不傳，後端自動產生

ptu_capacity

Object

必填

TPM 容量配置，詳見下表

pre_paid_info

Object

條件必填

charge_type=pre_paid 時必填

欄位

類型

必填

說明

input_tpm

Integer

必填

輸入 TPM 配額（每分鐘輸入 Token 數），須為模型 step 整數倍

output_tpm

Integer

必填

輸出 TPM 配額（每分鐘輸出 Token 數），須為模型 step 整數倍

thinking_output_tpm

Integer

可選

思考輸出 TPM 配額，僅思考模型，須為模型 step 整數倍

欄位

類型

必填

說明

duration

Integer

必填

購買時間長度（天），取值 1~30、60、90、120、365

auto_renewal

Boolean

必填

是否自動續約

auto_renewal_duration

Integer

條件必填

auto_renewal=true 時必填，續約時間長度（天）

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 提供單個查詢與列表查詢兩種方式，分別用於查看指定部署詳情和分頁瀏覽全部部署。
  • 查詢單個部署
  • 列表查詢
調用 GET /api/v1/deployments/{deployed_model} 查詢指定部署的狀態與配置。路徑參數 deployed_model 為部署服務 ID。

欄位

類型

說明

deployed_model

String

部署服務 ID

model_name

String

基本模型名

plan

String

部署計劃，TPM 預留為 ptu

service_tier

String

服務層級

status

String

部署狀態

charge_type

String

計費類型

ptu_capacity

Object

TPM 容量配置

gmt_created

String

建立時間

gmt_modified

String

修改時間

{
  "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"
  }
}

擴縮容

調用 PUT /api/v1/deployments/{deployed_model}/scale 對 TPM 預留部署執行擴縮容，請求體傳入新的 ptu_capacity 配置。

欄位

類型

必填

說明

ptu_capacity

Object

必填

新的 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。後付費擴縮容直接生效，不觸發下單。
預付費擴縮容為非同步作業，調用介面返回 SCALING 狀態後需等待商業化下單完成，狀態自動變為 RUNNING。請勿在 SCALING 狀態期間重複發起擴縮容。
擴縮容方向約束：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

Object

必填

續約資訊（結構同建立 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

String

必填

enable（超出 PTU 容量流量溢出公用池隨用隨付）/ disable（超出直接限流）

{
  "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 直接調用，溢出策略可隨時切換無需重建部署。溢出策略概念詳見預置吞吐長輸入與緩衝。
overflow_strategy=enable 時，超出 PTU 容量的流量會溢出到公用池隨用隨付，產生額外費用。disable 時超出直接限流，不產生額外費用但影響服務可用性。

錯誤碼

調用 TPM 預留 OpenAPI 時如遇錯誤，響應體返回 request_id、code、message 三個欄位，可根據錯誤碼定位問題。

HTTP 狀態代碼

錯誤名

說明

解決方案

400

InvalidParameter

參數非法

按本篇參數表核對參數名、類型與取值後重試

401

InvalidApiKey

API Key 無效

檢查 API Key 有效性與地區綁定，必要時重新擷取 Key

403

AccessDenied / Model.AccessDenied / App.AccessDenied

無許可權

確認帳號有 TPM 預留許可權，檢查工作空間與模型授權

404

ModelNotFound

模型不存在

確認 model_name 在支援清單內且拼字正確

409

Conflict

部署重名

更換部署名或 suffix 避免重名後重試

429

Throttling / Throttling.RateQuota / Throttling.AllocationQuota

限流（TPM 超額走 AllocationQuota）

擴容 ptu_capacity 或調整 overflow_strategy，詳見下方限流應對

500

InternalError / RequestTimeOut

內部錯誤

記錄 request_id 提工單，稍後重試

503

ModelUnavailable

模型不可用

稍後重試或切換可用模型

{
  "request_id": "xxx",
  "code": "Throttling.AllocationQuota",
  "message": "..."
}
429 限流錯誤中，TPM 容量超額走 AllocationQuota 錯誤碼。限流應對最佳實務詳見限流應對最佳實務。

常見問題

二者不是「預設/快速」版本關係，而是不同部署情境。ptu_default 對應 TPM 預留（容量保障），ptu_fast 對應 PTU v2 通用部署。
官方 API 無 auto_renewal_cycle 欄位。實際續約欄位為 duration（購買時間長度）、auto_renewal（是否自動續約）、auto_renewal_duration（auto_renewal=true 時必填的續約時間長度）。
thinking_output_tpm 僅適用于思考模型。TPM 預留支援的 9 款模型均支援思考輸出配額。
不是介面錯誤。建立請求 plan=ptu 與續約請求 plan=ptu_v2 的差異是前後端命名規範，後端均映射到 ptu_v2 內部處理。
TPM 預留建立不傳 suffix，由後端自動產生部署服務 ID，尾碼長度由後端決定，不固定為 8 位。
使用 API
文本產生
映像產生
視頻產生
音頻
即時多模態
Realtime API
  • 概述
向量與排序
更多模型
工具包/架構
模型生產
檔案管理
更多