Alibaba Cloud Model Studio：吞吐量預留 API 參考

吞吐量預留（原 TPM 預留）API 用於建立、查詢及管理吞吐量預留容量。每個吞吐量預留透過 ModelCode 識別，可包含多個容量執行個體；每個執行個體對應一次容量購買，可分別擴縮容、續訂或釋放。

認證與呼叫準備

使用呼叫地域的百煉 API Key，在請求標頭中傳入 Authorization: Bearer <api-key>。API Key 與地域綁定，不可跨地域使用。請求主體為 JSON 時傳入 Content-Type: application/json。

工作空間專屬網域格式為 https://{workspaceId}.{region}.maas.aliyuncs.com，使用目標工作空間及地域的 Endpoint。如需指定子業務空間，請求標頭攜帶 X-DashScope-WorkSpace: <workspace-id>。

DashScope API 網域為 https://dashscope-intl.aliyuncs.com。維吉尼亞地域使用 https://{workspaceId}.us-east-1.maas.aliyuncs.com。

非同步容量操作的結果透過 查詢容量操作 獲取。

控制台入口參見吞吐預留，部署概念參見模型部署，通用部署 API 參見使用 API 進行模型部署。

公共約定

介面基礎路徑為 /api/v1/deployments，沿用呼叫地域的 DashScope OpenAPI 網域和驗證方式。請求主體使用 Content-Type: application/json。使用目標地域的帳號、模型和部署。

• deployed_model：吞吐預留的呼叫識別碼（ModelCode）；實例/操作回應中的 model_service_id 表示同一物件。
• instance_id：容量執行個體 ID。使用介面返回值，不根據字串格式推斷付費方式。
• operation_id：操作 ID，使用介面返回的字串值。
• 下文範例 ID、模型名稱、容量值均為佔位範例。真實模型、最小值、步長、上限及購買時長以目標地域的模型和購買限制為準。
• JSON 範例省略部分可選回應欄位；範例中的階段狀態不是每次請求的固定返回。

成功回應統一包裝為：

{
  "request_id": "example-request",
  "output": {}
}

請求錯誤範例：

{
  "request_id": "example-request",
  "code": "CAPACITY_INSTANCE_REQUIRED",
  "message": "需要指定容量实例"
}

建立吞吐預留

POST /api/v1/deployments

建立吞吐預留並購買首個容量實例，傳回用於呼叫模型的 ModelCode。如需為現有吞吐預留增加容量，請呼叫 疊加購買容量實例。

欄位	類型	必填	說明
model_name	String	是	基礎模型名稱
plan	String	是	ptu
service_tier	String	否	效能等級：ptu_fast 為高速（預設），ptu_default 為標準速度
charge_type	String	是	pre_paid（預付費）/ post_paid（後付費）
name	String	否	顯示名稱；未傳時自動產生。
suffix	String	否	ModelCode 後綴；未傳時自動產生。
ptu_capacity	Object	是	容量設定，見 容量參數
pre_paid_info	Object	條件必填	預付費必填，見 預付費參數；後付費不傳

ptu_default 支援預付費；ptu_fast 支援預付費和後付費。新增容量實例沿用 ModelCode 的效能等級。

ptu_default 標準速度支援按天與 8 小時時段兩種付費週期：按天對應 pricing_cycle=Day，8 小時時段對應 pricing_cycle=Hour 且 duration=8。8 小時時段僅 ptu_default 標準速度支援，ptu_fast 高速不支援。

按天預付費範例：

{
  "model_name": "<base_model>",
  "plan": "ptu",
  "service_tier": "ptu_fast",
  "charge_type": "pre_paid",
  "name": "吞吐预留示例",
  "ptu_capacity": {
    "input_tpm": 10000,
    "output_tpm": 1000
  },
  "pre_paid_info": {
    "duration": 30,
    "auto_renewal": false
  }
}

8 小時時段預付費範例（僅 ptu_default 標速）：

{
  "model_name": "<base_model>",
  "plan": "ptu",
  "service_tier": "ptu_default",
  "charge_type": "pre_paid",
  "ptu_capacity": {
    "input_tpm": 10000,
    "output_tpm": 1000
  },
  "pre_paid_info": {
    "pricing_cycle": "Hour",
    "duration": 8,
    "auto_renewal": false
  }
}

ptu_capacity

容量單位為 kTPM（1 kTPM = 1000 Tokens/分鐘）。目前支援的模型不支援單獨配置思考輸出配額。

欄位	類型	說明
input_tpm	Long	輸入容量，單位 kTPM，按模型要求提供並滿足步長及範圍
output_tpm	Long	輸出容量，單位 kTPM，按模型要求提供並滿足步長及範圍

擴縮容時表示所選實例變更後的絕對容量，不是增加量，也不是 ModelCode 的目標總容量。

pre_paid_info

欄位	類型	說明
pricing_cycle	String	付費週期：Day 為按天（預設），Hour 為 8 小時時段；Hour 僅 ptu_default 標準速度支援，大小寫敏感
duration	Integer	購買 / 續訂時長，單位隨 pricing_cycle：Day 為天，Hour 為小時且固定 8，必須大於 0
auto_renewal	Boolean	明確指定是否自動續費；Hour 場景必須為 false
auto_renewal_duration	Integer	自動續費開啟時必填且大於 0，單位天；Hour 場景不傳
auto_renewal_cycle	String	可選續費週期單位，按產品支援的值傳入，例如 Day 表示天；Hour 場景不傳

建立回應

output 為部署物件（查詢吞吐預留）。建立容量實例時可傳回 operation_id、instance_id；預付費實例的購買訂單尚未處理完成時，instance_id 可能暫缺，後續查詢取得。

{
  "request_id": "example-request",
  "output": {
    "deployed_model": "example-model-code",
    "model_name": "<base_model>",
    "plan": "ptu",
    "status": "WAIT_PRE_PAID_BILLING_TO_DEPLOYING",
    "operation_id": "100001"
  }
}

有 operation_id 時按 查詢容量操作 查詢；建立請求逾時應先確認是否已經建立，避免重複建立 ModelCode。

擴縮容

PUT /api/v1/deployments/{deployed_model}/scale

調整指定吞吐預留下某個容量實例的輸入和輸出容量。存在多個未刪除實例時，必須透過 instance_id 指定目標實例。

欄位	必填	說明
instance_id	條件必填	多個未刪除執行個體時必須傳；僅一個未刪除執行個體時可省略
ptu_capacity	是	該執行個體變更後的絕對容量
pre_paid_info	否	預付費未傳時複用已儲存的資訊；後付費不傳
order_type	否	UPGRADE 為升配，DOWNGRADE 為降配；省略時由伺服器端判定，傳入值須與容量變化方向一致

{
  "instance_id": "example-capacity-instance",
  "ptu_capacity": {
    "input_tpm": 20000,
    "output_tpm": 2000
  },
  "order_type": "UPGRADE"
}

output 傳回吞吐預留資訊，相應容量操作的 ID 透過 operation_id 傳回。多實例未指定 ID 傳回 CAPACITY_INSTANCE_REQUIRED。新接入推薦 擴縮容指定容量實例。

預付費變更涉及訂單，後付費不走預付費變配訂單。變更確認前繼續保留原生效容量，失敗時不能把目標容量展示為已生效。全零擴縮容不等價於刪除實例。

查詢吞吐預留

GET /api/v1/deployments/{deployed_model}

查詢指定吞吐預留的設定、狀態，以及所有容量執行個體已生效的彙總容量。

{
  "request_id": "example-request",
  "output": {
    "deployed_model": "example-model-code",
    "model_name": "<base_model>",
    "plan": "ptu",
    "ptu_service_tier": "ptu_fast",
    "status": "RUNNING",
    "charge_type": "pre_paid",
    "ptu_capacity": {
      "input_tpm": 10000,
      "output_tpm": 1000
    },
    "overflow_strategy": "disable"
  }
}

欄位	說明
deployed_model	吞吐預留的呼叫識別碼（ModelCode）。
model_name	基礎模型名稱。
plan	類型識別碼，吞吐預留為 ptu。
status	ModelCode 狀態，不代表每個容量執行個體的狀態
ptu_service_tier	效能等級：ptu_fast 為高速，ptu_default 為標準速度
ptu_capacity	該 ModelCode 下所有容量執行個體已生效的輸入、輸出彙總容量
charge_type	取值：pre_paid（預付費）/ post_paid（後付費）
pre_paid_info	預付費購買及續訂配置，含 pricing_cycle（Day 按天 / Hour 為 8 小時時段）、duration 等。存在多個容量實例時，請透過實例詳情查詢目標實例的 pre_paid_info。
pre_paid_instance_id	預付費實例識別碼。存在多個容量實例時，請透過容量實例清單取得各實例的 instance_id，並指定要操作的實例。
pre_paid_gmt_expired	預付費到期時間。存在多個容量實例時，請透過目標實例詳情的 gmt_expired 取得其到期時間。到期時刻計算規則見吞吐預留計費。
overflow_strategy	溢位策略，enable 表示允許溢位按量計費，disable 表示超出容量時限流。溢位計費口徑詳見吞吐預留計費。
fail_reason	失敗原因。
gmt_create	建立時間。
gmt_modified	最後修改時間。
operation_id	容量操作 ID，用於查詢操作結果；相應寫入操作回應中可能返回。
instance_id	容量執行個體 ID。購買訂單尚未處理完成時可能暫不返回；請透過後續查詢獲取。

混合付費應透過容量實例清單中各實例的 charge_type 判斷。部署狀態和計費類型不能代替每個實例的狀態和計費類型。

查詢吞吐預留清單

GET /api/v1/deployments?page_no=1&page_size=10&plan=ptu

分頁查詢吞吐預留清單。

Query 參數	說明
page_no	頁碼，預設 1
page_size	每頁數量，預設 10，範圍 [1,100]
plan	可選類型篩選。查詢吞吐預留時傳 ptu；效能等級由 service_tier 表示，不作為 plan 的取值

{
  "request_id": "example-request",
  "output": {
    "deployments": [
      {
        "deployed_model": "example-model-code",
        "plan": "ptu",
        "status": "RUNNING",
        "ptu_capacity": {
          "input_tpm": 10000,
          "output_tpm": 1000
        }
      }
    ],
    "total": 1,
    "page_no": 1,
    "page_size": 10
  }
}

部署清單不支援透過 status 參數篩選狀態。容量實例篩選請使用 查詢容量實例清單（含已刪除實例） 的 statuses。

續訂

PUT /api/v1/deployments/{deployed_model}/renew

為指定的預付費容量實例續訂，可同時調整容量。存在多個未刪除實例時，必須透過 instance_id 指定目標實例。

欄位	必填	說明
instance_id	條件必填	多個未刪除執行個體時必須指定；單執行個體相容省略
pre_paid_info	是	續約資訊，見 預付費參數
is_change	否	預設 false；是否同時調整容量
ptu_capacity	否	省略則保留配置容量；傳入不同容量時必須 is_change=true

續約並開啟自動續費：

{
  "instance_id": "example-capacity-instance",
  "pre_paid_info": {
    "duration": 30,
    "auto_renewal": true,
    "auto_renewal_duration": 30
  }
}

續約但不開啟自動續費：

{
  "instance_id": "example-capacity-instance",
  "pre_paid_info": {
    "duration": 30,
    "auto_renewal": false
  }
}

僅支援預付費；續訂請求不能傳 order_type。output 傳回吞吐預留資訊，並可能包含容量操作 ID；推薦使用 續訂指定容量實例 的實例級介面並輪詢結果。

修改溢位策略

PUT /api/v1/deployments/{deployed_model}/update-overflowstrategy

{
  "overflow_strategy": "disable"
}

overflow_strategy 必填，僅支援小寫 enable / disable。enable 表示超出 PTU 容量的流量允許溢位公共池按量計費；disable 表示超出後限流。配置作用於整個 ModelCode，容量包不單獨配置溢位策略。溢位計費口徑詳見吞吐預留計費。

回應包含 request_id 和 output。修改後可透過 查詢吞吐預留 取得 overflow_strategy，確認配置已更新。

{
  "request_id": "example-request",
  "output": {
    "deployed_model": "example-model-code",
    "model_name": "<base_model>",
    "plan": "ptu_v2",
    "ptu_service_tier": "ptu_fast",
    "status": "RUNNING",
    "charge_type": "post_paid",
    "overflow_strategy": "disable",
    "ptu_capacity": {
      "input_tpm_quota": 10000,
      "output_tpm_quota": 10000
    }
  }
}

容量執行個體介面

以下介面均以 /api/v1/deployments/{deployed_model} 為前綴。實例寫入操作傳回 容量操作 的操作物件，與舊 /scale、/renew 的部署物件不同。

疊加購買容量實例

POST /api/v1/deployments/{deployed_model}/capacity-instances

欄位	必填	說明
billing_method	是	付費方式：PRE_PAY 為預付費，POST_PAY 為後付費。取值區分大小寫
ptu_capacity	是	新執行個體容量
pre_paid_info	條件必填	預付費必填，後付費不傳

預付費範例：

{
  "billing_method": "PRE_PAY",
  "ptu_capacity": {
    "input_tpm": 10000,
    "output_tpm": 1000
  },
  "pre_paid_info": {
    "duration": 30,
    "auto_renewal": false
  }
}

8 小時時段增購範例（僅 ptu_default 標準速度，billing_method 固定 PRE_PAY，pre_paid_info 傳 pricing_cycle=Hour / duration=8 / auto_renewal=false）：

{
  "billing_method": "PRE_PAY",
  "ptu_capacity": {
    "input_tpm": 10000,
    "output_tpm": 1000
  },
  "pre_paid_info": {
    "pricing_cycle": "Hour",
    "duration": 8,
    "auto_renewal": false
  }
}

8 小時時段實例建立成功後，透過 查詢容量實例詳情 可取得以下欄位：pricing_cycle 為 Hour；gmt_effective 為北京時間整點生效時間；gmt_expired 與 gmt_effective 相差 8 小時；can_scale、can_renew、can_enable_auto_renew、can_disable_auto_renew、can_delete 均為 false。

後付費範例：

{
  "billing_method": "POST_PAY",
  "ptu_capacity": {
    "input_tpm": 10000,
    "output_tpm": 1000
  }
}

傳回操作物件，初次回應可能已成功、失敗或仍在處理中。沿用現有 ModelCode、模型和效能等級；同一 ModelCode 只允許一個未刪除的後付費實例。購買條件或實例數量不滿足要求時，請根據介面傳回的錯誤處理。

查詢容量實例清單（含已刪除實例）

GET /api/v1/deployments/{deployed_model}/capacity-instances?page_no=1&page_size=20&include_deleted=true

Query 參數	類型	說明
page_no	Integer	預設 1
page_size	Integer	預設 20，範圍 [1,100]
include_deleted	Boolean	預設 true；只顯示未刪除執行個體時顯式傳 false
statuses	String 清單	可選，多值逗號分隔，例如 RUNNING,STOPPED
charge_types	String 清單	可選，pre_paid,post_paid

{
  "request_id": "example-request",
  "output": {
    "records": [
      {
        "model_service_id": "example-model-code",
        "instance_id": "example-capacity-instance",
        "charge_type": "post_paid",
        "status": "STOPPED",
        "deleted": true,
        "effective_capacity": {
          "input_tpm": 0,
          "output_tpm": 0
        },
        "configured_capacity": {
          "input_tpm": 0,
          "output_tpm": 0
        },
        "can_scale": false,
        "can_renew": false,
        "can_delete": false
      }
    ],
    "items": 1,
    "page": 1,
    "itemsPerPage": 20,
    "pageCount": 1
  }
}

分頁結構與部署清單不同：records 是目前頁，items 是總數，page 是頁碼，itemsPerPage / pageCount 保留目前傳回的駝峰拼寫。優先排列有生效容量的實例，再按建立時間倒序。清單僅支援本節列出的查詢參數。

查詢容量實例詳情

GET /api/v1/deployments/{deployed_model}/capacity-instances/{instance_id}

傳回 容量實例 的實例物件，已刪除實例也可查詢。ModelCode 與實例須匹配，不能跨 ModelCode 操作實例。

擴縮容指定容量實例

PUT /api/v1/deployments/{deployed_model}/capacity-instances/{instance_id}/scale

{
  "ptu_capacity": {
    "input_tpm": 20000,
    "output_tpm": 2000
  },
  "order_type": "UPGRADE"
}

參數語義同 擴縮容，實例 ID 由路徑確定，請求主體無需重複。傳回操作物件。呼叫前讀取 can_scale；預付費到期暫停的實例不能直接擴縮容，應先續訂。8 小時時段實例不支援擴縮容，呼叫傳回 CAPACITY_INSTANCE_OPERATION_UNSUPPORTED。

續訂指定容量實例

PUT /api/v1/deployments/{deployed_model}/capacity-instances/{instance_id}/renew

一般續約：

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

續約並調整容量：

{
  "pre_paid_info": {
    "duration": 30,
    "auto_renewal": false
  },
  "is_change": true,
  "ptu_capacity": {
    "input_tpm": 20000,
    "output_tpm": 2000
  }
}

參數約束同 續訂，不傳 order_type。僅預付費可續訂，先檢查 can_renew；傳回操作物件。8 小時時段實例不支援續訂和自動續費，呼叫傳回 CAPACITY_INSTANCE_OPERATION_UNSUPPORTED。

刪除 / 釋放容量實例

DELETE /api/v1/deployments/{deployed_model}/capacity-instances/{instance_id}

可選 Query 參數 reason 為刪除原因，按 URL 編碼；無需 JSON 請求主體。傳回操作物件。

• 後付費：按刪除流程釋放，完成後 deleted=true、status=STOPPED，生效容量為零。
• 已生效的預付費：不能用本介面代替退訂，直接呼叫傳回 PREPAID_UNSUBSCRIBE_REQUIRED。完成退訂並釋放容量後，最終同樣傳回 deleted=true、status=STOPPED。
• 8 小時時段實例不支援直接刪除，呼叫傳回 PREPAID_UNSUBSCRIBE_REQUIRED，需走商業化退訂流程。
• can_delete=true 表示目前狀態允許進入刪除 / 退訂流程，不表示預付費可跳過退訂直接 DELETE。對於尚無關聯訂單的失敗執行個體，請根據介面返回結果處理。

退訂釋放為非同步操作。同一 ModelCode 正在處理其他操作時，已受理的釋放操作會排隊等待，完成前查詢可能仍返回原狀態和生效容量。退訂已受理不代表容量已釋放，請透過操作結果及執行個體 deleted 欄位确认完成。退訂退費公式詳見吞吐預留計費。

查詢容量操作

GET /api/v1/deployments/{deployed_model}/capacity-operations/{operation_id}

{
  "request_id": "example-poll-request",
  "output": {
    "operation_id": "100001",
    "request_id": "example-original-request",
    "operation_type": "SCALE",
    "operation_status": "SUCCEEDED",
    "model_service_id": "example-model-code",
    "instance_id": "example-capacity-instance",
    "from_status": "RUNNING",
    "current_status": "RUNNING"
  }
}

外層 request_id 是本次查詢請求識別碼，操作物件內的 request_id 是原始操作識別碼，兩者可能不同。查詢路徑必須屬於建立該操作的 ModelCode。

使用寫入操作實際傳回的 operation_id，不要自行建構。查詢不存在的數字 ID 或其他 ModelCode 的操作時，傳回 HTTP 404、CAPACITY_OPERATION_NOT_FOUND；傳入包含字母等非數字字元的無效 ID 時，可能傳回 HTTP 500、InternalError。遇到此錯誤先核對 ID，不要直接重複發起容量寫入操作。

刪除吞吐預留

DELETE /api/v1/deployments/{deployed_model}

需先釋放全部容量實例，且 ModelCode 為 STOPPED、不存在正在執行或排隊的容量操作，再刪除整個部署。傳回部署物件。

最後一個實例釋放後，ModelCode 變為 STOPPED，不會因此自動刪除 ModelCode。刪除容量實例與刪除 ModelCode 是兩個不同操作。

回應物件及狀態

容量實例（CapacityInstance）

欄位	類型	說明
model_service_id	String	容量執行個體或操作所屬的 ModelCode。
instance_id	String	容量執行個體 ID。
charge_type	String	pre_paid（預付費）/ post_paid（後付費）
status	String	執行個體生命週期狀態，見下表
deleted	Boolean	是否已刪除 / 釋放，用於識別已釋放的執行個體
effective_capacity	Object	目前已確認提供服務的容量
configured_capacity	Object	執行個體設定 / 合約容量；停止、暫停時仍可保留
target_capacity	Object	正在變更的目標容量，穩定狀態可能不返回或為空
pre_paid_info	Object	該實例的預付費購買及續訂配置，含 pricing_cycle（Day 按天 / Hour 為 8 小時時段），見 預付費參數。
gmt_effective	String	預付費實例生效時間；8 小時時段實例按北京時間整點生效。按時區偏移解析，不要把 +00:00 的小時數字直接當作北京時間。
gmt_expired	String	預付費實例到期時間；8 小時時段實例與 gmt_effective 相差 8 小時。到期時刻計算規則見吞吐預留計費。
can_scale	Boolean	目前是否允許對實例擴縮容；8 小時時段實例固定 false。
can_renew	Boolean	目前是否允許續約執行個體；8 小時時段執行個體固定 false。
can_enable_auto_renew	Boolean	目前是否允許開啟自動續費；8 小時時段實例固定 false。
can_disable_auto_renew	Boolean	目前是否允許關閉自動續費；8 小時時段實例固定 false。
can_delete	Boolean	目前是否允許刪除或退訂實例；預付費實例仍需完成退訂流程，8 小時時段實例固定 false。
fail_reason	String	失敗原因
gmt_created	時間	建立時間。
gmt_modified	時間	最後修改時間。
gmt_deleted	時間	刪除時間。

狀態	含義及顯示建議
WAIT_PRE_PAID_BILLING_TO_DEPLOYING / WAIT_TO_DEPLOY	等待購買處理 / 等待生效
RUNNING	執行中
WAIT_PRE_PAID_BILLING_TO_SCALING / SCALING	等待變配訂單 / 變配中
STOPPING / STOPPED	停止中 / 已停止；結合 deleted 區分已釋放
SUSPENDING / SUSPENDED	暫停中 / 已暫停
STARTING / RECOVERING	啟動中 / 恢復中
DELETING	刪除中
FAILED	失敗，結合失敗原因處理

後付費刪除與預付費退訂可統一展示為「已釋放」：條件為 deleted=true，而不是僅 status=STOPPED。STOPPED + deleted=false 仍是保留的實例。deleted=true 的實例不允許擴縮容、續訂、刪除。

RUNNING 狀態不代表所有操作均可用。同一 ModelCode 有進行中操作或存在計費限制時，相應操作可能不可用。預付費 SUSPENDED 實例不可擴縮容，符合續訂條件時可續訂；後付費實例不可續訂。呼叫前重新查詢實例詳情，透過 can_scale、can_renew、can_delete 檢查操作是否可用，並處理介面傳回的錯誤。

容量操作（CapacityOperation）

欄位	說明
operation_id	容量操作 ID，用於查詢操作結果；相應寫入操作回應中可能返回。
request_id	發起該容量操作的請求識別碼。
operation_type	常見 CREATE、SCALE、RENEW、DELETE；生命週期處理也可能出現 STOP、REFUND，不意味著存在同名公開寫入介面
operation_status	取值：PROCESSING、SUCCEEDED、FAILED
model_service_id	容量執行個體或操作所屬的 ModelCode。
instance_id	容量執行個體 ID。購買訂單尚未處理完成時可能暫不返回；請透過後續查詢獲取。
from_status	操作前的執行個體狀態。
current_status	執行個體目前狀態。
error_code	操作失敗時的錯誤碼。
error_message	操作失敗時的錯誤說明。
gmt_created	建立時間。
gmt_finished	操作完成時間。

操作正在執行或排隊等待時，均傳回 PROCESSING。SUCCEEDED / FAILED 為終態，收到終態後停止輪詢，並重新整理實例和部署彙總。

非同步呼叫、冪等性與錯誤處理

推薦呼叫順序

1. 查詢執行個體詳細資訊，讀取能力開關及最新設定。
2. 發起一次購買 / 擴縮容 / 續訂 / 刪除請求，儲存 operation_id。
3. 若返回 PROCESSING，定期查詢操作並逐步退避；若已終態，直接處理結果。
4. SUCCEEDED 後重新整理實例及 ModelCode；FAILED 展示 error_code / error_message。網路逾時不等於操作失敗，先查已有操作。

同一 ModelCode 的容量變更按順序處理；有進行中操作時，新變更可能被拒絕。已受理的退訂釋放會排隊，在前序操作完成後繼續。變更生效前，查詢仍傳回原生效容量，不應將目標容量視為已生效。

疊加、擴縮容或釋放生效後，可透過部署查詢介面取得更新後的彙總生效容量，繼續使用原 ModelCode。呼叫模型還需完成對應模型部署，並使用正確的帳號驗證和呼叫參數；容量操作成功不代表模型呼叫的其他條件均已滿足。

重試與請求識別碼

對同一個容量寫入操作的網路重試，保持請求識別碼與參數不變。建議將 x-acs-req-uuid 與 X-DashScope-RequestId 設定為同一個 UUID，避免兩者不一致導致實際識別碼變化。目前讀取優先順序為 x-acs-req-uuid、X-DashScope-RequestId、X-Request-Id，均未提供時產生新識別碼。

相同 ModelCode、相同有效請求識別碼、相同操作參數的容量操作複用已有操作；同一識別碼換參數會傳回 IDEMPOTENCY_KEY_CONFLICT。新業務操作使用新識別碼。不要將這一實例操作冪等約定直接套用於首次建立 ModelCode。

錯誤碼

錯誤碼	HTTP	處理建議
CAPACITY_INSTANCE_REQUIRED	400	多執行個體時指定目標 instance_id
CAPACITY_INSTANCE_OPERATION_UNSUPPORTED	400	重新整理詳細資訊與能力開關，確認目前狀態及付費方式支援操作
PREPAID_UNSUBSCRIBE_REQUIRED	400	轉入已有退訂流程
POSTPAID_INSTANCE_ALREADY_EXISTS	400	複用現有後付費執行個體，或先釋放後再建立
CAPACITY_SLOT_LIMIT_EXCEEDED / TOTAL_CAPACITY_INSTANCE_LIMIT_EXCEEDED	400	已達到有效執行個體槽位 / 含歷史記錄的總數量限制
MODEL_CODE_DELETED	400	不再對已刪除吞吐預留發起寫入操作
MODEL_CODE_NOT_FOUND / CAPACITY_INSTANCE_NOT_FOUND	404	檢查地域、帳號、ModelCode 與實例歸屬；對已刪除實例執行擴縮容也可傳回 CAPACITY_INSTANCE_NOT_FOUND
CAPACITY_OPERATION_NOT_FOUND	404	操作不存在或不屬於指定 ModelCode，請核對寫入操作返回的 ID
InternalError	500	操作查詢傳入無效的非數字 ID 時可能傳回；先核對 ID，其他內部錯誤保留 request_id 聯絡技術支援
CAPACITY_INSTANCE_OPERATION_CONFLICT	409	先查詢現有操作，完成後再發起新操作
IDEMPOTENCY_KEY_CONFLICT	409	重試保持原參數；不同業務操作使用新識別碼
BILLING_ACCOUNT_NOT_READY	403	檢查帳號是否滿足購買條件
BILLING_SERVICE_UNAVAILABLE	503	查詢現有操作，按退避策略處理重試

表中 HTTP 對應請求階段拋出的錯誤；非同步操作失敗透過操作物件的錯誤欄位返回，不能只按 HTTP 狀態判斷。

其他通用錯誤：

HTTP 狀態碼	錯誤碼	處理建議
400	InvalidParameter	核對參數名稱、類型、容量變化方向與取值。
401	InvalidApiKey	檢查 API Key 的有效性和地域。
403	AccessDenied / Model.AccessDenied / App.AccessDenied	檢查帳號權限、工作空間和模型授權。
404	ModelNotFound	核對基礎模型名稱及支援範圍。
409	Conflict	部署名稱重複，請更換名稱或 suffix。
429	Throttling / Throttling.RateQuota / Throttling.AllocationQuota	吞吐預留超額對應 AllocationQuota，可擴容或調整溢位策略。
500	RequestTimeOut	先檢查現有操作，避免重複購買；保留 request_id 聯絡技術支援。
503	ModelUnavailable	稍後重試或切換可用模型。

限流處理參見限流應對最佳實務。