Throughput Reservation API Reference - Alibaba Cloud Model Studio

Authentication and Call Preparation

Use the Bailian API Key of the calling region, and pass it in the request header Authorization: Bearer <api-key>. The API Key is bound to the region and cannot be used across regions. When the request body is JSON, pass Content-Type: application/json。 The workspace-specific domain format is https://{workspaceId}.{region}.maas.aliyuncs.com, use the Endpoint of the target workspace and region. To specify a sub-business space, carry it in the request header X-DashScope-WorkSpace: <workspace-id>。 The DashScope API domain is https://dashscope-intl.aliyuncs.com. The Virginia region uses https://{workspaceId}.us-east-1.maas.aliyuncs.com。 The results of asynchronous capacity operations are obtained through Query Capacity Operation . For console entry, see Throughput Reservation, for deployment concepts, see Deployments, for general deployment API, see Using API to Perform Model Deployment。

Common Conventions

The interface base path is /api/v1/deployments, inheriting the DashScope OpenAPI domain and authentication method of the calling region. The request body uses Content-Type: application/json. Use the account, model, and deployment of the target region.

deployed_model：the call identifier of the Throughput Reservation (ModelCode); in instance/operation responses model_service_id represents the same object.
instance_id：Capacity Instance ID. Use the interface return value, do not infer the Billing Method based on the string format.
operation_id：Operation ID, use the string value returned by the interface.
The example IDs, model names, and capacity values below are placeholder examples. The real models, minimum values, step size, upper limit, and purchase duration are subject to the model and purchase limits of the target region.
The JSON examples omit some optional response fields; the stage status in the examples is not a fixed return for each request.

Successful responses are uniformly wrapped as:

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

Request error example:

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

An HTTP request success does not equal a capacity operation success. Even if the instance write interface returns HTTP 200, output.operation_status may also be FAILED。必须检查操作状态和错误字段，确认成功后再使用更新的容量。

Create Reserved Throughput

POST /api/v1/deployments Create Reserved Throughput and purchase the first capacity instance, returning the ModelCode used to call the model. To add capacity to an existing Reserved Throughput, please call Stack Purchase Capacity Instance。

Field	Type	Required	Description
`model_name`	String	Yes	Base Model Name
`plan`	String	Yes	`ptu`
`service_tier`	String	No	Performance Tier: `ptu_fast` is high-speed (default), `ptu_default` is standard-speed
`charge_type`	String	Yes	`pre_paid`(Subscription) / `post_paid`(Pay-as-you-go)
`name`	String	No	Show name; automatically generated if not specified.
`suffix`	String	No	ModelCode Suffix; auto-generated when not passed.
`ptu_capacity`	Object	Yes	Capacity Configuration, see Capacity Parameter
`pre_paid_info`	Object	Conditionally Required	Subscription Required, see Subscription Parameter; not passed for Pay-as-you-go

ptu_default supports Subscription;ptu_fast Supports Subscription and Pay-as-you-go. New capacity instances inherit the ModelCode's Performance Tier. ptu_default Standard supports By Day and 8-hour time slot two Billing Cycles: By Day corresponds to pricing_cycle=Day, 8-hour time slot corresponds to pricing_cycle=Hour And duration=8. 8-hour time slot only ptu_default Standard supports,ptu_fast High Speed does not support. By Day Subscription example:

{
  "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-hour time slot Subscription example (only ptu_default Standard):

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

The capacity unit is kTPM (1 kTPM = 1000 Tokens/ Minutes). Currently supported models do not support separately configuring thinking output quota.

Field	Type	Description
`input_tpm`	Long	Input capacity, unit kTPM, provided according to model requirements and satisfying step and Range
`output_tpm`	Long	Output capacity, unit kTPM, provided according to model requirements and satisfying step and Range

When Scaling, it indicates the absolute capacity after the selected Instance changes, not the increment, and not the target total capacity of ModelCode.

pre_paid_info

Field	Type	Description
`pricing_cycle`	String	Billing Cycle:`Day` is By Day (default),`Hour` is 8 Hours slot;`Hour` only `ptu_default` Standard speed supported, case-sensitive
`duration`	Integer	Purchase / Renew duration, unit follows `pricing_cycle`：`Day` as days,`Hour` as hours and fixed at 8, must be greater than 0
`auto_renewal`	Boolean	explicitly specify whether to auto-renew;`Hour` scenario must be `false`
`auto_renewal_duration`	Integer	Required and greater than 0 when auto-renewal is enabled, unit: days;`Hour` not passed in this scenario
`auto_renewal_cycle`	String	Optional. Renewal cycle unit, pass in values supported by the product, for example `Day` indicates days;`Hour` not passed in this scenario

Create Response

output is the deployment object (Query Throughput Reservation). When creating a capacity instance, may return operation_id、instance_id; when the purchase order of a Subscription instance has not been processed yet, instance_id may be temporarily unavailable; obtain it later via query.

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

There are operation_id when, by Query Capacity Operation query; for a creation request timeout, first confirm whether it has already been created to avoid duplicate creation of ModelCode.

Scaling

PUT /api/v1/deployments/{deployed_model}/scale Adjust the input and output capacity of a capacity instance under the specified throughput reservation. When there are multiple undeleted instances, you must use instance_id to specify the target instance.

Field	Required	Description
`instance_id`	Conditional Required	Required when there are multiple undeleted Instance ; can be omitted when there is only one undeleted Instance
`ptu_capacity`	Yes	The absolute capacity after this Instance changes
`pre_paid_info`	No	When Subscription is not passed, reuse the saved information; Pay-as-you-go does not pass it
`order_type`	No	`UPGRADE` for upgrading, `DOWNGRADE` for downgrading; when omitted, the server determines it, and the passed value must be consistent with the direction of capacity change

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

output Returns Throughput Reservation information; the ID of the corresponding capacity operation via operation_id is returned. For multiple instances with no specified ID, returns CAPACITY_INSTANCE_REQUIRED. For new integrations, recommended Scaling Specified Capacity Instance。 Subscription changes involve orders; Pay-as-you-go does not go through Subscription change orders. Before the change is confirmed, the original effective capacity continues to be retained; on failure, the target capacity cannot be shown as effective. All-zero Scaling is not equivalent to deleting an Instance.

Query Throughput Reservation

GET /api/v1/deployments/{deployed_model} Query the configuration and Status of the specified Throughput Reservation, as well as the aggregate effective capacity of all Capacity Instances.

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

Field	Description
`deployed_model`	The call identifier of the Throughput Reservation (ModelCode).
`model_name`	Base model name.
`plan`	Type identifier, Throughput Reserved is `ptu`。
`status`	ModelCode Status, does not represent the Status of each CapacityInstance
`ptu_service_tier`	Performance Tier:`ptu_fast` is high-speed,`ptu_default` is standard-speed
`ptu_capacity`	The aggregate input and output capacity of all effective CapacityInstances under this ModelCode
`charge_type`	Value:`pre_paid`(Subscription)/ `post_paid`(Pay-as-you-go)
`pre_paid_info`	Subscription Purchase and Renew configuration, including `pricing_cycle`（`Day` By Day / `Hour` for 8 Hours period），`duration` etc. When multiple capacity Instances exist, please query the target Instance through Instance details `pre_paid_info`。
`pre_paid_instance_id`	Subscription Instance identifier. When multiple capacity Instances exist, please Obtain each Instance through the capacity Instance list `instance_id`, and specify the Instance to operate on.
`pre_paid_gmt_expired`	Subscription expiration time. When multiple capacity Instances exist, please through the target Instance details `gmt_expired` Obtain its expiration time. The expiration time calculation rules are inThroughput Reservation Billing。
`overflow_strategy`	Overflow strategy,`enable` indicates that overflow pay-as-you-go billing is allowed,`disable` indicates that throttling is applied when capacity is exceeded. For overflow billing rules, see Throughput Reserved Billing。
`fail_reason`	Failure reason.
`gmt_create`	Created At.
`gmt_modified`	Last modified time.
`operation_id`	CapacityOperation ID, used to query operation results; may be returned in the corresponding write operation response.
`instance_id`	CapacityInstance ID. May not be returned when the purchase order has not been fully processed; obtain it through subsequent queries.

Mixed billing should be determined by each instance's charge_type in the CapacityInstance list. Deployment status and billing type cannot replace each instance's status and billing type.

Query Throughput Reservation List

GET /api/v1/deployments?page_no=1&page_size=10&plan=ptu Query the throughput reservation list with pagination.

Query Parameter	Description
`page_no`	Page Number, default 1
`page_size`	Number of items per page, default 10, Range [1,100]
`plan`	Optional type filter. Pass `ptu`; Performance Tier is indicated by `service_tier` and is not a value of `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
  }
}

Deployments list does not support filtering status via status parameter. For capacity instance filtering, use Query Capacity Instance List (Including Deleted Instances) 's statuses。

Renew

PUT /api/v1/deployments/{deployed_model}/renew Renew the specified Subscription capacity instance; the capacity can be adjusted at the same time. When there are multiple undeleted instances, you must specify the target instance via instance_id.

Field	Required	Description
`instance_id`	Conditionally Required	Must be specified when there are multiple undeleted instances; single instance can be omitted
`pre_paid_info`	Yes	Renew info, see Subscription parameters
`is_change`	No	Default `false`; whether to adjust capacity at the same time
`ptu_capacity`	No	Omit to retain configured capacity; when passing a different capacity, must `is_change=true`

Renew and enable auto-renewal:

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

Renew but do not enable auto-renewal:

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

Only Subscription is supported; renewal requests cannot pass order_type。output Return Throughput Reservation information, and may include a Capacity Operation ID; it is recommended to use Renew Specified Capacity Instance instance-level interface and poll the results.

Modify Overflow Strategy

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

{
  "overflow_strategy": "disable"
}

overflow_strategy Required, only lowercase is supported enable / disable。enable indicates that traffic exceeding PTU capacity is allowed to overflow to the public pool for Pay-as-you-go billing;disable indicates throttling after the limit is exceeded. The configuration applies to the entire ModelCode; capacity packages do not have individual overflow strategies. For details on overflow billing, seeThroughput Reservation Billing。 Response contains request_id and output. After modification, you can Pass Query Throughput Reservation Obtain overflow_strategy, confirm that the configuration has been updated.

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

After enabling the overflow strategy, traffic exceeding the capacity is billed on a pay-as-you-go basis, incurring additional fees. After disabling it, requests exceeding the capacity will be throttled. For details on overflow billing, seeThroughput Reservation Billing; for more information, seeProvisioned Throughput Long Input and Cache。

Capacity Instance Interface

The following interfaces all use /api/v1/deployments/{deployed_model} as prefix. Instance write operations return Capacity Operation operation object, different from the old /scale、/renew Deployments object.

Stacking Purchase Capacity Instance

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

Field	Required	Description
`billing_method`	Yes	Billing Method:`PRE_PAY` is Subscription,`POST_PAY` is Pay-as-you-go. Values are case-sensitive
`ptu_capacity`	Yes	New Instance Capacity
`pre_paid_info`	Conditionally Required	Required for Subscription, not transmitted for Pay-as-you-go

Subscription example:

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

8 Hours time-period additional-purchase example (only ptu_default standard speed, billing_method fixed PRE_PAY，pre_paid_info pass 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 Hours time-period Instance created successfully, Pass Query Capacity Instance Details can Obtain the following Fields: pricing_cycle is Hour；gmt_effective is the Beijing time on-the-hour effective Time; gmt_expired and gmt_effectivea difference of 8 Hours;can_scale、can_renew、can_enable_auto_renew、can_disable_auto_renew、can_deleteare all false。 Pay-as-you-go example:

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

Returns the operation object; the initial response may indicate success, failure, or still in progress. Reuse the existing ModelCode, model, and Performance Tier; only one undeleted Pay-as-you-go Instance is allowed per ModelCode. When purchase conditions or Instance quantity do not meet requirements, handle according to the error returned by the interface.

Query Capacity Instance List (including deleted instances)

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

Query Parameter	Type	Description
`page_no`	Integer	Default 1
`page_size`	Integer	Default 20, Range [1,100]
`include_deleted`	Boolean	Default true; explicitly pass false when only showing undeleted instances
`statuses`	String List	Optional, multiple values comma-separated, for example `RUNNING,STOPPED`
`charge_types`	String List	Optional,`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
  }
}

Paging structure differs from the Deployments list:records is the current page,items is the total count,page is the Page Number,itemsPerPage / pageCount retains the camelCase spelling of the current Return. Instances with active capacity are prioritized first, then sorted by Created At in descending order. The List only supports the query Parameter listed in this section.

Query Capacity Instance Detail

GET /api/v1/deployments/{deployed_model}/capacity-instances/{instance_id} Return CapacityInstance instance object; deleted instances can also be queried. ModelCode and the instance must match; instances cannot be operated across ModelCode.

After a Pay-as-you-go Instance is released, re-purchasing Pay-as-you-go capacity under the same ModelCode will reuse the original instance ID. The List and detail are updated to the instance info after re-purchase, and no longer separately retain the original Delete record. After release configured_capacity may be zero; retaining the configured capacity before release is not guaranteed.

Scaling Specified CapacityInstance

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

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

Parameter semantics same as Scaling, instance ID is determined by the path; the request body need not be repeated. Return the operation object. Read before calling can_scale；Instances with pending Subscription expiry cannot be Scaling directly, Renew first. 8-hour timeslot instances do not support Scaling, the call returns CAPACITY_INSTANCE_OPERATION_UNSUPPORTED。

Renew Specified Capacity Instance

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

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

Renew and Adjust Capacity:

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

Parameter constraints same as Renew, do not pass order_type。Only Subscription can be Renewed, check first can_renew；Return operation object. 8-hour timeslot instances do not support Renew and auto-renew, the call returns CAPACITY_INSTANCE_OPERATION_UNSUPPORTED。

Delete / Release Capacity Instance

DELETE /api/v1/deployments/{deployed_model}/capacity-instances/{instance_id} Optional Query parameter reason is the deletion reason, URL-encoded; no JSON request body is required. Return an operation object.

Pay-as-you-go: Released via the deletion process, and upon completion, the deleted=true、status=STOPPED, with effective capacity of zero.
Effective Subscription: This interface cannot be used in place of unsubscription; calling it directly returns PREPAID_UNSUBSCRIBE_REQUIRED. After completing unsubscription and releasing capacity, it ultimately also returns deleted=true、status=STOPPED。
8-hour time-slot instances do not support direct deletion; calling it returns PREPAID_UNSUBSCRIBE_REQUIRED, and you must go through the commercial unsubscription process.
can_delete=true indicates that the current status permits entering the deletion/unsubscription process, but does not mean that Subscription can skip unsubscription and directly DELETE. For failed instances that do not yet have associated orders, please handle them based on the interface return results.

Unsubscription release is an asynchronous operation. When the same ModelCode is processing other operations, an accepted release operation will queue and wait; querying before completion may still return the original status and effective capacity. Unsubscription being accepted does not mean capacity has been released; please verify through the operation results and the instance deleted Field verification complete. For unsubscribe refund formula details, seeThroughput Reservation Billing。

Query Capacity Operation

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

Outer request_id is the identifier of this query request, and the one inside the operation object request_id is the original operation identifier; the two may differ. The query path must belong to the ModelCode that created this operation. Use the actual one returned by the write operation operation_id, do not construct it yourself. When querying a non-existent numeric ID or operations of other ModelCode, returns HTTP 404, CAPACITY_OPERATION_NOT_FOUND; when passing an invalid ID containing non-numeric characters such as letters, may return HTTP 500, InternalError. When encountering this error, first verify the ID; do not directly reissue the capacity write operation.

Delete Reserved Throughput

DELETE /api/v1/deployments/{deployed_model} Need to first release all Capacity Instances, and ModelCode is STOPPED、no CapacityOperation is executing or queued, then delete the entire deployment. Return the deployment object. After the last Instance is released, ModelCode becomes STOPPED, ModelCode will not be automatically deleted. Deleting a Capacity Instance and deleting a ModelCode are two different operations.

Response Object and Status

Capacity Instance (CapacityInstance)

Field	Type	Description
`model_service_id`	String	The ModelCode to which the Capacity Instance or Operation belongs.
`instance_id`	String	Capacity Instance ID.
`charge_type`	String	`pre_paid`（Subscription）/ `post_paid`（Pay-as-you-go）
`status`	String	Instance lifecycle status; see the table below
`deleted`	Boolean	Whether deleted/released, used to identify released Instances
`effective_capacity`	Object	Currently confirmed serving capacity
`configured_capacity`	Object	Instance configuration/contract capacity; retained even when stopped or suspended
`target_capacity`	Object	Target capacity being changed; may not be returned or empty in stable state
`pre_paid_info`	Object	Subscription purchase and renewal configuration of this Instance, including `pricing_cycle`（`Day` By Day / `Hour` for 8-hour time slots), see Subscription parameters。
`gmt_effective`	String	Subscription instance effective time; 8-hour time slot instances take effect on Beijing time whole hours. Parse by timezone offset, do not take `+00:00` 's hour number directly as Beijing time.
`gmt_expired`	String	Subscription instance expiration time; 8-hour time slot instances and `gmt_effective` differ by 8 hours. Expiration time calculation rules seeThroughput Reservation Billing。
`can_scale`	Boolean	Whether scaling is currently allowed for the instance; 8-hour time slot instances fixed `false`。
`can_renew`	Boolean	Whether instance renewal is currently allowed; 8-hour time slot instances fixed `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`	时间	删除时间。

Status	Meaning and Display Suggestions
`WAIT_PRE_PAID_BILLING_TO_DEPLOYING` / `WAIT_TO_DEPLOY`	Waiting for purchase processing / Waiting to take effect
`RUNNING`	Running
`WAIT_PRE_PAID_BILLING_TO_SCALING` / `SCALING`	Waiting for upgrade order / Updating
`STOPPING` / `STOPPED`	Stopping / Stopped; combined with `deleted` distinguish Released
`SUSPENDING` / `SUSPENDED`	Suspending / Suspended
`STARTING` / `RECOVERING`	Starting / Recovering
`DELETING`	Deleting
`FAILED`	Failed, handle based on the failure reason

Pay-as-you-go Delete and Subscription cancellation can be uniformly shown as "Released": condition is deleted=true, rather than only status=STOPPED。STOPPED + deleted=false are still Reserved instances.deleted=true instances are not allowed to scale, renew, or delete. RUNNING Status does not mean all Actions are available. When the same ModelCode has an in-progress operation or billing restrictions, the corresponding action may be unavailable. Subscription SUSPENDED instances cannot be scaled; can be renewed when meeting Renew conditions; Pay-as-you-go instances cannot be renewed. Before calling, re-query the instance details, via can_scale、can_renew、can_delete to check whether the action is available, and handle errors returned by the interface.

Capacity Operation (CapacityOperation)

Field	Description
`operation_id`	Capacity operation ID, used to query operation results; may be returned in the corresponding write operation response.
`request_id`	The request identifier that initiated this capacity operation.
`operation_type`	Common `CREATE`、`SCALE`、`RENEW`、`DELETE`; lifecycle processing may also appear `STOP`、`REFUND`, which does not mean there is a public write interface with the same name
`operation_status`	Values:`PROCESSING`、`SUCCEEDED`、`FAILED`
`model_service_id`	The ModelCode to which the capacity instance or operation belongs.
`instance_id`	Capacity instance ID. It may not be returned when the purchase order has not been processed yet; please obtain it through subsequent queries.
`from_status`	The instance status before the operation.
`current_status`	Instance current status.
`error_code`	Error Code when the operation fails.
`error_message`	Error description when the operation fails.
`gmt_created`	Created At.
`gmt_finished`	Operation completion time.

When the operation is being executed or queued for waiting, Return PROCESSING。SUCCEEDED / FAILED is the terminal state. Upon receiving the terminal state, stop polling and refresh the Instance and Deploy summary.

Asynchronous Call, Idempotency and Error Handling

Recommended call sequence

Query Instance details, read capability switches and the latest configuration.
Initiate a Purchase / Scaling / Renew / Delete request and Save operation_id。
If Return PROCESSING, periodically query the operation and gradually back off; if terminal state reached, process the result directly.
SUCCEEDED then refresh the Instance and ModelCode; FAILED Show error_code / error_message. Network timeout does not equal operation failure; first query existing operations.

Capacity changes for the same ModelCode are processed in order; when there is an in-progress operation, new changes may be rejected. Accepted unsubscribe releases are queued and continue after preceding operations complete. Before a change takes effect, queries still Return the original effective capacity; the target capacity should not be treated as already effective. After stacking, Scaling, or release takes effect, you can Obtain the updated aggregated effective capacity via the Deploy query interface and continue using the original ModelCode. Calling a model also requires completing the corresponding model Deployments and using the correct Account authentication and call parameters; a successful capacity operation does not mean all other conditions for model invocation are satisfied.

Retry and Request Identifier

For network retries of the same capacity write operation, keep the request identifier and parameters unchanged. It is recommended to x-acs-req-uuid and X-DashScope-RequestId set to the same UUID to avoid inconsistency between the two causing actual identifier changes. The current read priority is x-acs-req-uuid、X-DashScope-RequestId、X-Request-Id, a new identifier is generated when neither is provided. Capacity operations with the same ModelCode, the same valid request identifier, and the same operation parameters reuse existing operations; using the same identifier with different parameters will return IDEMPOTENCY_KEY_CONFLICT. New business operations use new identifiers. Do not directly apply this instance operation idempotency convention to the first creation of ModelCode.

Error Code

Error Code	HTTP	Handling Suggestion
`CAPACITY_INSTANCE_REQUIRED`	400	Specify the target for multiple instances `instance_id`
`CAPACITY_INSTANCE_OPERATION_UNSUPPORTED`	400	Refresh details and capability switches, confirm current status and billing method support the operation
`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	The operation does not exist or does not belong to the specified ModelCode. Verify the ID returned by the write operation
`InternalError`	500	May be returned when an invalid non-numeric ID is passed in the operation query; first verify the ID, for other internal errors retain request_id and contact technical support
`CAPACITY_INSTANCE_OPERATION_CONFLICT`	409	First query existing operations, and after completion initiate a new operation
`IDEMPOTENCY_KEY_CONFLICT`	409	Retry keeps the original parameters; different business operations use a new identifier
`BILLING_ACCOUNT_NOT_READY`	403	Check whether the account meets the purchase conditions
`BILLING_SERVICE_UNAVAILABLE`	503	Query existing operations and handle retries according to the backoff policy

The table lists errors thrown during the request phase corresponding to HTTP; failures of asynchronous operations are returned through the error field of the operation object, so you cannot judge solely by HTTP status. Other common errors:

HTTP Status Code	Error Code	Handling Suggestion
400	`InvalidParameter`	Verify parameter names, types, capacity change direction, and values.
401	`InvalidApiKey`	Check the validity and region of the API Key.
403	`AccessDenied` / `Model.AccessDenied` / `App.AccessDenied`	Check account permissions, workspace, and model authorization.
404	`ModelNotFound`	Verify the base model name and supported scope.
409	`Conflict`	Deploy name conflict, change the name or suffix.
429	`Throttling` / `Throttling.RateQuota` / `Throttling.AllocationQuota`	Throughput reservation over-quota corresponds to AllocationQuota, you can scale or adjust the overflow strategy.
500	`RequestTimeOut`	Check existing operations first to avoid duplicate purchases; keep the request_id to contact technical support.
503	`ModelUnavailable`	Retry later or switch to an available model.

For rate limit handling, seeRate Limit Best Practices。

​Authentication and Call Preparation

​Common Conventions

​Create Reserved Throughput

​ptu_capacity

​pre_paid_info

​Create Response

​Scaling

​Query Throughput Reservation

​Query Throughput Reservation List

​Renew

​Modify Overflow Strategy

​Capacity Instance Interface

​Stacking Purchase Capacity Instance

​Query Capacity Instance List (including deleted instances)

​Query Capacity Instance Detail

​Scaling Specified CapacityInstance

​Renew Specified Capacity Instance

​Delete / Release Capacity Instance

​Query Capacity Operation

​Delete Reserved Throughput

​Response Object and Status

​Capacity Instance (CapacityInstance)

​Capacity Operation (CapacityOperation)

​Asynchronous Call, Idempotency and Error Handling

​Recommended call sequence

​Retry and Request Identifier

​Error Code

Authentication and Call Preparation

Common Conventions

Create Reserved Throughput

ptu_capacity

pre_paid_info

Create Response

Scaling

Query Throughput Reservation

Query Throughput Reservation List

Renew

Modify Overflow Strategy

Capacity Instance Interface

Stacking Purchase Capacity Instance

Query Capacity Instance List (including deleted instances)

Query Capacity Instance Detail

Scaling Specified CapacityInstance

Renew Specified Capacity Instance

Delete / Release Capacity Instance

Query Capacity Operation

Delete Reserved Throughput

Response Object and Status

Capacity Instance (CapacityInstance)

Capacity Operation (CapacityOperation)

Asynchronous Call, Idempotency and Error Handling

Recommended call sequence

Retry and Request Identifier

Error Code