All Products
Search

This Product

    Elastic Compute Service:ModifyInstanceNetworkSpec

    Document Center

    Elastic Compute Service:ModifyInstanceNetworkSpec

    Last Updated:Sep 02, 2026

    Modifies the bandwidth configuration of an ECS instance, allocates a public IP address, converts the network billing method. Both upgrades and downgrades are supported.

    Operation description

    • When you modify the bandwidth configuration of a subscription (PrePaid) instance and the outbound public bandwidth (InternetMaxBandwidthOut) is upgraded from 0 Mbit/s to a non-zero value, a public IP address is automatically assigned.

    • When you modify the bandwidth configuration of a pay-as-you-go (PostPaid) instance and the outbound public bandwidth (InternetMaxBandwidthOut) is upgraded from 0 Mbit/s to a non-zero value, a public IP address is not automatically assigned. Set the AllocatePublicIp parameter to true to assign a public IP address.

    Note

    In a single region, the total peak pay-by-bandwidth public bandwidth for a single Alibaba Cloud account is limited. For more information, see Public bandwidth limits.

    • Fees:

      • After the bandwidth is upgraded, fees are automatically deducted by default. Make sure that your payment method has a sufficient balance. Otherwise, an abnormal order is generated, and you can only void the order. If your account balance is insufficient, set the AutoPay parameter to false. A normal unpaid order is generated, and you can log on to the ECS console to complete the payment.

      • After the bandwidth is downgraded, the price difference is refunded to the original payment method. Used vouchers are not refunded.

    Try it now

    Try this API in OpenAPI Explorer, no manual signing needed. Successful calls auto-generate SDK code matching your parameters. Download it with built-in credential security for local usage.

    Test

    RAM authorization

    The table below describes the authorization required to call this API. You can define it in a Resource Access Management (RAM) policy. The table's columns are detailed below:

    • Action: The actions can be used in the Action element of RAM permission policy statements to grant permissions to perform the operation.

    • API: The API that you can call to perform the action.

    • Access level: The predefined level of access granted for each API. Valid values: create, list, get, update, and delete.

    • Resource type: The type of the resource that supports authorization to perform the action. It indicates if the action supports resource-level permission. The specified resource must be compatible with the action. Otherwise, the policy will be ineffective.

      • For APIs with resource-level permissions, required resource types are marked with an asterisk (*). Specify the corresponding Alibaba Cloud Resource Name (ARN) in the Resource element of the policy.

      • For APIs without resource-level permissions, it is shown as All Resources. Use an asterisk (*) in the Resource element of the policy.

    • Condition key: The condition keys defined by the service. The key allows for granular control, applying to either actions alone or actions associated with specific resources. In addition to service-specific condition keys, Alibaba Cloud provides a set of common condition keys applicable across all RAM-supported services.

    • Dependent action: The dependent actions required to run the action. To complete the action, the RAM user or the RAM role must have the permissions to perform all dependent actions.

    Action

    Access level

    Resource type

    Condition key

    Dependent action

    ecs:ModifyInstanceNetworkSpec

    update

    *Instance

    acs:ecs:{#regionId}:{#accountId}:instance/{#instanceId}
    • ecs:AssociatePublicIpAddress
    		 None

    Request parameters

    Parameter

    Type

    Required

    Description

    Example
    InstanceId

    string

    Yes

    The instance ID of the instance for which you want to modify the network configuration.

    i-bp67acfmxazb4****
    InternetMaxBandwidthOut

    integer

    No

    The maximum outbound public bandwidth. Unit: Mbit/s (Megabit per second). Valid values:

    • Pay-by-traffic: 0 to 100.

    • Pay-by-bandwidth:

      • Subscription instances: 0 to 200.

      • Pay-as-you-go instances: 0 to 100.

    Note

    The maximum outbound bandwidth of a single instance is also limited by the Network bandwidth baseline/burst (Gbit/s) metric of the ECS instance type. For more information, see Instance families.

    10
    InternetMaxBandwidthIn

    integer

    No

    The maximum inbound public bandwidth. Unit: Mbit/s (Megabit per second). Valid values:

    • If the purchased outbound public bandwidth is less than or equal to 10 Mbit/s: 1 to 10. Default value: 10.

    • If the purchased outbound public bandwidth is greater than 10 Mbit/s: 1 to the value of InternetMaxBandwidthOut. Default value: the value of InternetMaxBandwidthOut.

    10
    ISP

    string

    No

    Note

    This parameter is in invitational preview and is not publicly available.

    null
    NetworkChargeType

    string

    No

    Converts the network billing method. Valid values:

    • PayByBandwidth: pay-by-bandwidth.

    • PayByTraffic: pay-by-traffic.

    Note

    In the pay-by-traffic mode, the inbound and outbound bandwidth peaks are both upper limits and are not guaranteed. When resource contention occurs, the bandwidth peaks may be throttled. If your workloads require guaranteed bandwidth, use the pay-by-bandwidth mode.

    PayByTraffic
    AllocatePublicIp

    boolean

    No

    Specifies whether to assign a public IP address. Valid values:

    • true: A public IP address is assigned.

    • false: No public IP address is assigned.

    Default value: false.

    false
    StartTime

    string

    No

    The start time of the temporary bandwidth upgrade. Specify the time in the ISO 8601 standard in the yyyy-MM-ddTHH:mmZ format. The time must be in UTC+0. The value is accurate to the minute (mm).

    2017-12-05T22:40Z
    EndTime

    string

    No

    The end time of the temporary bandwidth upgrade. Specify the time in the ISO 8601 standard in the yyyy-MM-ddTHHZ format. The time must be in UTC+0. The value is accurate to the hour (HH).

    Note

    The interval between the end time and the start time of the temporary bandwidth upgrade must be greater than or equal to 3 hours.

    2017-12-06T22Z
    AutoPay

    boolean

    No

    Specifies whether to automatically complete the payment. Valid values:

    • true: The payment is automatically completed after the bandwidth configuration is changed. Make sure that your account balance is sufficient. If the balance is insufficient, an abnormal order is generated. You cannot pay for this order in the ECS console. You can only void the order.

    • false: An order is generated but the payment is not completed after the bandwidth configuration is changed. If your payment method has an insufficient balance, set the Autopay parameter to false to cancel automatic payment. In this case, a normal unpaid order is generated. You can log on to the ECS console to complete the payment.

    Default value: true.

    true
    ClientToken

    string

    No

    The client token that is used to ensure the idempotence of the request. You can use the client to generate the token, but make sure that the token is unique among different requests. The ClientToken value can contain only ASCII characters and cannot exceed 64 characters in length. For more information, see How to ensure idempotence.

    123e4567-e89b-12d3-a456-426655440000

    Response elements

    Element

    Type

    Description

    Example

    object

    OrderId

    string

    The order ID. This parameter is returned only when you modify the bandwidth configuration of a subscription (PrePaid) instance.

    123457890
    RequestId

    string

    The request ID.

    473469C7-AA6F-4DC5-B3DB-A3DC0DE3C83E

    Examples

    Success response

    JSON format

    {
  "OrderId": "123457890",
  "RequestId": "473469C7-AA6F-4DC5-B3DB-A3DC0DE3C83E"
}

    Error codes

    HTTP status code

    Error code

    Error message

    Description
    400 InvalidInternetMaxBandwidthIn.ValueNotSupported The specified InternetMaxBandwidthIn is beyond the permitted range. The specified maximum inbound public bandwidth exceeds the maximum allowed value.
    400 InvalidInternetMaxBandwidthOut.ValueNotSupported The specified InternetMaxBandwidthOut is beyond the permitted range. The specified maximum outbound public bandwidth exceeds the maximum allowed value.
    400 OperationDenied Specified instance is in VPC. The instance resides in a VPC.
    400 InvalidParameter.Conflict %s The specified parameter is invalid. Check whether parameter conflicts exist. %s is a variable. An error message is dynamically returned based on call conditions.
    400 InvalidStartTime.ValueNotSupported The specified StartTime is out of the permitted range.
    400 InvalidEndTime.ValueNotSupported The specified EndTime is out of the permitted range.
    400 ChargeTypeViolation The operation is not permitted due to billing method of the instance. The billing method does not support this operation. Check whether the billing method of the instance conflicts with this operation.
    400 Account.Arrearage Your account has an outstanding payment. Your account has overdue payments.
    400 InvalidInternetChargeType.ValueNotSupported The specified InternetChargeType is invalid. The specified InternetChargeType parameter is invalid.
    400 DecreasedBandwidthNotAllowed %s The bandwidth downgrade operation is invalid.
    400 BandwidthUpgradeDenied.EipBoundInstance The specified VPC instance has bound EIP, temporary bandwidth upgrade is denied. The instance is associated with an EIP and cannot have its bandwidth temporarily upgraded.
    400 InvalidClientToken.ValueNotSupported The ClientToken provided is invalid. The specified ClientToken parameter is invalid.
    400 Throttling Request was denied due to request throttling, please try again after 5 minutes. The request is throttled.
    400 InvalidInstanceStatus.NotStopped The specified Instance status is not Stopped.
    400 InvalidAction Specified action is not valid. The operation is invalid.
    400 IpAllocationError Allocate public ip failed. A public IP address cannot be assigned.
    400 InvalidParam.AllocatePublicIp The specified param AllocatePublicIp is invalid. The specified AllocatePublicIp parameter is invalid.
    400 InstanceDowngrade.QuotaExceed Quota of instance downgrade is exceed. The maximum number of configuration downgrades allowed for the instance has been reached.
    400 InvalidBandwidth.ValueNotSupported Instance upgrade bandwidth of temporary not allow less then existed. The specified bandwidth value is not supported.
    400 InvalidInstanceStatus The specified instance status does not support this action. The instance is in a state that does not support the current operation.
    400 InvalidInstance.UnPaidOrder Unpaid order exists in your account, please complete or cancel the payment in the expense center. Your account has an unpaid order. Pay for the order and try again.
    400 LastOrderProcessing The previous order is still processing, please try again later. The order is being processed. Try again later.
    400 LastRequestProcessing The previous request is still processing, please try again later.
    400 InvalidStartTime.BeyondLifeCycle The specified start time exceeds the expiration time. The specified start time StartTime be greater than the expiration time of the resource
    400 InvalidEndTime.BeyondLifeCycle The specified end time exceeds the expiration time. The end time parameter (EndTime) is beyond the lifetime of the resource.
    400 InvalidPayMethod.SyncPaymentNotSupport Synchronous payment is not supported. Use another payment method.
    400 InvalidBandwidthOut.LessThanZero The bandwidth must be larger than 0 when specifying isp.
    400 InvalidParameter.BandwidthBiggerThanBaseBandwidth %s
    400 InvalidAction.WithActiveElasticUpgrade The instance has active Elastic Upgrade.
    400 InvalidParameter.CloudboxNotSupported %s
    400 InvalidParameter.Bandwidth %s The specified bandwidth value is invalid.
    400 NoPermission.Price The operation requires price permission. Please either apply for permission from your main account, or set the parameter AutoPay as true. This operation requires price permission. Please apply for permission to your master account, or set the parameter AutoPay to true for automatic payment.
    400 NoPermission.Refund The operation requires refund permission. Please apply for permission from your main account. This account does not have permission to operate refund, and the main account needs to authorize refund-related permissions.
    400 InvalidParameter.DedicatedRegionNotSupported The specified action is rejected because the specified ECS instance in the dedicated region does not support public IP. Parameter error codes not supported in the dedicated region
    400 InvalidOperation.InstanceStatusUnsupported The specified instance status is not supported for this operation, expect status is Running or Stopped. The status of the specified instance is not satisfied. The status of the instance should be Running or Stopped.
    400 QuotaExceeded.InternetBandwidth %s. Under your current account, the public network bandwidth of the Pay-As-You-Go ECS instance charged by fixed bandwidth exceeds the total bandwidth quota limit.
    400 UnsupportedIspNetworkChargeType The network charge type is not supported when specifying ISP. The network charge type is not supported when specifying ISP.
    400 IncorrectInstanceStatus Current instance status does not support this operation. The instance is in a state that does not support the current operation.
    400 TaskConflict The operation is too frequent, please wait a moment and try again. EIP operations are too frequent.
    400 InvalidOperation.InternetMaxBandwidthOutUnsupported The InternetMaxBandwidthOut is not allowed to modify. Your account is overdue and you are not allowed to modify the maximum outbound bandwidth of the public network.
    500 InternalError The request processing has failed due to some unknown error.
    500 Image.OrderFailed Create marketplace image order failed. Failed to create an Alibaba Cloud Marketplace order.
    403 IncorrectInstanceStatus The current status of the instance does not support this operation.
    403 InstanceLockedForSecurity The specified operation is denied as your instance is locked for security reasons. The instance to which the disk is attached is locked for security reasons.
    403 InstanceExpiredOrInArrears The specified operation is denied as your prepay instance is expired (prepay mode) or in arrears (afterpay mode).
    403 ChargeTypeViolation The operation is not permitted due to billing method of the instance.
    403 OperationDenied The operation is denied due to the instance is PrePaid. Subscription instances do not support this operation.
    403 InvalidAccountStatus.NotEnoughBalance Your account does not have enough balance.
    403 InvalidInstance.UnPaidOrder The specified Instance has unpaid order.
    403 Throttling Request was denied due to request throttling, please try again after 5 minutes.
    403 InvalidInstance.InstanceNotSupported The special vpc instance with eip not need bandwidth. The instance resides in a VPC and is associated with an EIP. You cannot specify a public bandwidth for the instance.
    403 InstanceDowngrade.QuotaExceed Quota of instance downgrade is exceed.
    403 InvalidInstanceStatus The current status of the instance does not support this operation. The instance is in a state that does not support the current operation.
    403 InvalidOperation.StarterPackage StarterPackage not support modification.
    403 NAT_PUBLIC_IP_BINDING_FAILED Binding nat public ip failed.
    403 InvalidInstance.EipNotSupport The specified instance with eip is not supported, please unassociate eip first. The operation is not supported while an EIP is associated with the instance. Disassociate the EIP first.
    403 InvalidInstance.NatPortMapNotSupport The special instance with nat port map not support operate, please remove nat port map first.
    403 OperationDenied.UnpaidOrder The specified instance has unpaid order. Your account has unpaid orders for the specified instance. You can log on to the ECS console to pay for the orders.
    403 Mayi.InternalError The request processing has failed due to some unknown error.
    403 InvalidNetworkType.ValueNotSupported The specified parameter NetworkType is not valid.
    403 OperationDenied.ImageNotValid The specified marketplace image is not authorized. Please verify the marketplace image authorization and try again.
    403 InvalidInstanceChargeType.ValueNotSupported The specified parameter ChargeType is not valid. The specified instance billing method does not exist.
    403 InvalidIspType.ValueNotSupported %s
    403 UnsupportedIspChargeType %s The billing type does not support the service provider (ISP) for this account.
    403 UnsupportedIspClassicNetwork %s
    403 InvalidIspBandwidthOut %s
    403 UnsupportedChangeIsp %s
    403 InvalidIspUID %s
    403 UnsupportedIspRegion %s
    403 BandIncreaseNotSupportIsp %s ISP instances do not support temporary bandwidth upgrades.
    403 SecurityRisk.3DVerification We have detected a security risk with your default credit or debit card. Please proceed with verification via the link in your email. A security risk has been detected on your default credit or debit card. Verify your identity by using the link in the email.
    403 InvalidOperation.PublicIpAddressNoStock The public IP address for the specified Region or ChargeType of the instance is out of stock. Please try another Region or ChargeType. Under the conditions of the specified region or payment type, the public IP address inventory of the instance is insufficient. Please try another region or payment type.
    403 InvalidOperation.NetworkTypeUnsupported The specified network type is not supported in this region. The specified network type is not supported in this region.
    404 InvalidInstanceId.NotFound The specified InstanceId does not exist. The specified instanceId is invalid.
    409 OperationConflict Request was denied due to conflict with a previous request,please try again later. A request conflict occurred. Wait a moment and try again, or submit a ticket.

    See Error Codes for a complete list.

    Release notes

    See Release Notes for a complete list.