Skip to main content

Create, integrate, and manage

This topic describes, in order of actual use, how to create a throughput reservation in the console (form parameters and fee confirmation), integrate and call the API, view monitoring data, and perform daily management (scaling, renewal, unsubscription, capacity pack stacking, and overflow policy modification).

Before you begin

Before using throughput reservations, make sure the following three things are ready:
  • Model Studio model service: Activated in the Model Studio console.
  • Workspace: A workspace has been created; use the dedicated domain and API Key of that workspace when calling reserved capacity.
  • API Key: Created in the target workspace; see Obtain and configure an API Key for the steps.
This topic covers the complete workflow for using throughput reservations:
创建吞吐预留 → 接入调用 → 查看与监控 → 日常管理(叠加容量包/扩缩容/续订/退订)

Create a throughput reservation

Go to the creation page: Log on to the Model Studio console, choose Model Inference > Throughput Reservations in the left-side navigation pane, and click Create Throughput Reservation. Fill in the form fields one by one in the order they appear in the console:
Form fieldWhat to fill inWhen it is available
Reservation NameA custom name of no more than 50 charactersAlways displayed
Select ModelSelect the model to reserve capacity for from the drop-down listAlways displayed; once a model is selected, the billing cycle options appear dynamically based on the selected model
Reasoning ModeStandard mode / Turbo modeAlways displayed; for the differences between the two modes, see Throughput reservation overview
Billing CycleBy Day / By 8-hour slot / Pay-as-you-go by hourBy Day: available for both modes. By 8-hour slot: Standard mode only, and orders can be placed only between 22:00 and 00:00 the next day. Pay-as-you-go by hour: Turbo mode only; appears after Turbo mode is selected
Input Capacity / Output CapacityUnit: kTPM (1 kTPM = 1,000 tokens per minute); input starts at 200 in increments of 10, and output starts at 20 in increments of 1Always displayed; before purchasing, use the TPM capacity calculator to estimate, and see Long input and prefix caching for the long input and cache conversion rules
Duration1~30, 60, 90, 120, 365 daysDisplayed only for upfront/By Day billing; By 8-hour slot is fixed at 8 hours and requires no input; pay-as-you-go is billed by actual usage and has no duration
Auto-Renew on ExpirationOn / Off, On by default; when enabled, the fee is automatically deducted between 8:20 and 20:00 one day before expiration, with up to 4 attemptsDisplayed only for upfront/By Day billing; auto-renewal is not supported for By 8-hour slot
Renewal Duration1~30, 60, 90, 120, 365 daysDisplayed after Auto-Renew on Expiration is enabled (By Day only)
Overflow policyAuto overflow (default; the excess is automatically billed on a pay-as-you-go basis without interrupting your business) / Reserved capacity only (the excess directly returns a 429 rate limit error and incurs no additional fees)Always displayed
The full fee is charged as soon as creation succeeds. The capacity fee is a one-time payment based on the purchased amount, regardless of whether any calls are made: even if you never make a call, the full fee still applies and is not reduced by actual usage. Make sure you understand this before submitting the purchase.
While you fill in the form, Cost Details on the right side of the page displays the estimated fee and billing information in real time. After confirming the parameters, click Buy Now, verify the fee in the dialog box, and then click Confirm Payment. Where to find the dedicated model code after creation: Go back to the throughput reservation list page, expand the card of the corresponding model, find dedicated model code on the Overview tab of the details area, and click to copy it. Replace the model parameter with it in all subsequent calls.

Integration and invocation

Prerequisite: the reservation instance is in the Running state. There is only one rule for making calls: replace the model parameter in the request with the dedicated model code; everything else is the same as calling a regular model. The API Integration tab in the console details area provides examples for only some of the protocols (OpenAI compatible and DashScope); the complete calling methods for the three protocols are as follows.
  • OpenAI Chat compatible
  • Anthropic compatible
  • OpenAI Responses
Suitable for businesses already integrated with the OpenAI Chat Completions protocol. Both endpoints can be used: the DashScope domain https://dashscope.aliyuncs.com/compatible-mode/v1, or the Dedicated Workspace Host https://{workspaceId}.{region}.maas.aliyuncs.com/compatible-mode/v1 (replace {workspaceId} and {region} with actual values, such as cn-beijing).
  • cURL
  • Python
curl -X POST https://dashscope.aliyuncs.com/compatible-mode/v1/chat/completions \
  -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "your-dedicated-model-code",
    "messages": [
      {
        "role": "user",
        "content": "你好"
      }
    ]
  }'
To switch to the Dedicated Workspace Host, simply replace the domain in the examples above with https://{workspaceId}.{region}.maas.aliyuncs.com/compatible-mode/v1; the other parameters remain unchanged.
To confirm whether a call hits reserved capacity, check the service_tier field in the response: a value of ptu_default (Standard mode) or ptu_fast (Turbo mode) indicates that reserved capacity was hit; provisioned_tokens is the converted capacity consumed by this call. For the meaning of the fields, see View capacity consumption and cache hits.

View and monitor

View capacity, usage, and running status on the throughput reservation page of the Model Studio console. The page is organized into three layers along the usage flow:
  • Reservation list: one card per model, used to locate the target reservation.
  • Card details area: click View more on a card to expand it; it contains the Overview, Monitoring, and API Integration tabs, which are used respectively to determine whether capacity is sufficient, troubleshoot call issues, and obtain call examples. At the bottom of the Overview tab is the list of capacity instances under the model; the entries for scaling, renewal, and unsubscription are all in the Actions column of each instance row.

Reservation List

预留列表的模型卡片:容量趋势图与生效中的容量实例
The card displays the following information:
Card informationDescription
Mode label, statusThe inference mode of the reservation and the current status of the instance.
Active ReservationsThe number of active capacity instances; the statistics include historical expired, stopped, and released reservations, so this is not equal to the currently available quantity.
Reserved Input/Output TPMThe total capacity of all instances under the model.
The list can be filtered by foundation model, Time, Status, and Performance. The Buy capacity and Add-on capacity package entries on the card serve the same purpose: both add a capacity instance to the current dedicated model code.

Card Details Section

The details section contains three tabs:
  • Overview
  • Monitoring
  • API Integration
概览页签:部署配置、统计卡、使用率趋势、超额降级统计
Check whether capacity is sufficient from three places:
Check itemLocationCriterion
UtilizationStatistics card (average utilization) and the Utilization Trend curveA utilization rate that remains close to 100% indicates insufficient capacity.
PeakStatistics card Peak within 7 days (capacity usage peak over the last 7 days)A peak close to or exceeding the purchased capacity indicates insufficient capacity during peak hours.
Overage degradationOverage Degradation Statistics (the most recent degradation time and count, generated only under the auto overflow policy)Frequent degradation indicates frequent overage; we recommend scaling out (see Management operations).
The utilization trend provides three statistical methods:
Statistical methodDescription
By purchased capacityCalculates the utilization rate based on the purchased capacity.
By converted capacityBased on the capacity converted using the conversion coefficient (the conversion method for long input and caching).
Including overflow usageUsage additionally counts the portion that overflows to pay-as-you-go billing.
The Deployment Configuration card displays the Reservation Name, dedicated model code, foundation model, and input/output capacity. An Edit entry is provided next to the overflow policy (see Management operations).

Capacity Instance List

容量实例列表:容量实例 ID、输入/输出 TPM、状态、付费周期、生效/到期时间、自动续费与操作列
The capacity instance list is located at the bottom of the Overview tab, with the title "Capacity instance list for this model". Each capacity instance corresponds to one capacity purchase and is managed row by row:
ColumnDescription
Capacity instance IDThe unique identifier of the instance, used to specify the instance when calling the management OpenAPI.
Input/Output TPMThe input/output capacity of the instance.
StatusFor the meaning, see Instance status.
Billing CycleUpfront/by day, upfront/8-hour block, pay-as-you-go/by hour.
Effective/expiration timeThe effective and expiration times; the number of remaining days is displayed before expiration.
Auto-renewalOn/Off; the change takes effect immediately (upfront/by day only).
The Actions column provides Scaling, Renew, and Unsubscribe entries (displayed based on the instance status); the Add-on capacity package button is located next to the list title and is equivalent to the entry on the card.

Management Operations

Operations available and constraints for each billing method:
Billing methodScalingRenewUnsubscribe / deleteKey constraints
Upfront/by daySupportedSupported (including auto-renewal)Unsubscribe via User CenterUnsubscription is irreversible and refunds are settled based on the penalty coefficient; the API cannot directly release upfront instances (this must be handled in User Center)
Pay-as-you-go/by hourSupportedNot applicable (no expiration concept)Deleting the instance stops billingInstances scaled to zero can be deleted directly; all instances must be released before deleting the Model Code
8-hour blockNot supportedNot supportedNot supportedCapacity automatically becomes invalid after the block expires; auto-renewal is not supported
Add-on capacity packages can be added to upfront or pay-as-you-go reservations; at most one undeleted pay-as-you-go instance can exist under a dedicated model code. The overflow policy is modified on the Overview tab.
ActionProblem solvedEntryApplicable instancesFees and rules
Add-on capacity packageAdds a new capacity instanceCard Add-on capacity package/Buy capacity, or next to the capacity instance list titleBy-day and by-hour pay-as-you-go instancesAdd-on capacity package billing
ScalingScales the capacity of the original instance up or down (including to zero)Capacity instance list Actions columnBy-day and by-hour pay-as-you-go instancesScale out, Scale in
Renew / auto-renewalExtends the validity period and avoids interruption at expirationCapacity instance list Actions column / auto-renewal column switchBy-day instancesBilling rules
UnsubscribeCompletely stops and releases the instanceCapacity instance list Actions column (redirects to User Center for processing)By-day instancesUnsubscribe
Modify overflow policyDetermines whether the excess portion is converted to pay-as-you-go billing or returns 429Edit next to the overflow policy on the Overview tabAll instancesOverflow policy and billing
Each of the above operations has a corresponding OpenAPI interface; for the calling method, see Throughput reservation API reference.

Add-on Capacity Package

叠加容量包弹窗:确认专属模型 code 后选择付费周期与容量
Click Add-on capacity package (or Buy capacity) on the card and complete the following steps in order:
确认专属模型 code → 选择付费周期 → 填写购买时长与自动续费(仅按天)→ 填写输入/输出容量 → 核对费用并支付
Available billing cycles for add-on capacity packages:
Billing CycleApplicable conditions
Upfront/By DayApplies to both upfront and pay-as-you-go reservations
Upfront/By 8-hour time windowStandard mode (Basic) only, and only some models support it; for the supported list, see 8-hour time window reservation billing
Pay-as-you-go instances cannot be created through add-on capacity packs: at most one non-deleted pay-as-you-go instance can exist under a dedicated model code. Pay-as-you-go/By Hour is selectable only when creating a new throughput reservation (Turbo mode only). The values of the other parameters (Duration, auto-renewal, input/output capacity) are the same as those for creating a new reservation: the input starting value/step is 200/10 kTPM, and the output is 20/1 kTPM. After a successful purchase, the total capacity of the reservation increases accordingly; the dedicated model code remains unchanged, so no changes to API calls are required. Differences from scaling out on the original instance:
MethodObject changedBilling
Add-on capacity packAdds an independent instance that coexists with the original instancePurchased independently; you can choose the billing cycle and duration (for example, By 8-hour time window)
ScalingAdjusts the input/output TPM of the original instanceThe added portion is billed based on the remaining validity period

Scaling, renewal, and unsubscription

All three operations are available in the Actions column of the capacity instance list:
  • Scaling
  • Renew
  • Unsubscribe
扩缩容弹窗:原配置与新配置对照、需补交金额与费用明细
Click Scaling. The dialog box shows input and output TPM in an Original configuration / New configuration comparison (adjusted with sliders; if no changes are made, The configuration has not changed. is displayed). After adjustment, the Amount to be paid and cost details are displayed in real time, along with Used hours / Remaining hours—these two values are the billing basis for scale-out and scale-in settlement.
Both input and output TPM can be adjusted to 0 (zeroed out): after zeroing out, capacity fees stop accruing, the dedicated model code is retained, and calls can be restored by scaling out. Scale-in and zeroing out are refunded based on configuration-downgrade settlement, with a penalty factor of 1.2 for usage ≤30 days and 1.0 for >30 days. For more information, see Scale-in. The penalty factor applies only to upfront instances; pay-as-you-go instances stop being billed once deleted and no refunds are generated.

Modify the overflow policy

The overflow policy can be modified after creation: click Edit next to the overflow policy on the Overview tab. Whether the excess portion is converted to pay-as-you-go billing or a 429 error is returned is determined by the overflow policy. For the behavioral differences and billing impact of the two policies, see Overflow policy and billing.

Instance status

The five instance statuses and their meanings:
StatusMeaning and outcome
RunningNormal service; the dedicated model code can be called.
Pending activationCreated, waiting to take effect.
UpdatingScaling in progress.
StoppedThree causes: expiration, overdue payment, or capacity zeroed out. Instances stopped due to expiration or overdue payment recover after renewal; zeroed-out instances recover after scaling out again in the Scaling dialog box.
ReleasedResources have been reclaimed; irrecoverable.
Upfront instances are handled as follows upon expiration: they are shut down immediately after expiration (calls are not possible, but renewal is still available) and released 2 hours after shutdown.

FAQ

Troubleshoot in three steps:
  1. Check the overflow policy first: if it is Reserved capacity only, requests exceeding the reserved capacity will inevitably return 429; you can change the overflow policy to Automatic overflow on the Overview tab.
  2. Check Overage Degradation Statistics on the Overview tab to confirm how often overage occurs.
  3. Frequent overage indicates insufficient capacity: increase the capacity through Scaling or purchase an add-on capacity pack.
On the Monitoring tab, triage failures by type: 4xx errors are mostly issues with the request itself (parameters, authentication); 5xx errors are server errors and can be retried; for throttling errors, troubleshoot capacity as described in the previous question; for content moderation errors, check the input content.
After expiration, the reservation is immediately suspended (calls are not allowed, but renewal is still possible); it is released 2 hours after suspension and cannot be recovered. We recommend keeping Auto-Renew on Expiration enabled. For the rules, see Expiration and lifecycle.
On the Overview tab, watch for two signals: the utilization curve staying persistently close to 100%, or a frequent increase in the count in Overage Degradation Statistics. If either signal persists, we recommend scaling out the input/output capacity.