All Products
Search

This Product

    Elastic Compute Service:ModifyInstanceNetworkSpec

    Document Center

    Elastic Compute Service:ModifyInstanceNetworkSpec

    Last Updated:Jun 24, 2026

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

    Operation description

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

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

    Note

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

    • Fees:

      • After the bandwidth is upgraded, the payment is automatically deducted by default. Make sure that your payment method has sufficient balance. Otherwise, an abnormal order is generated, and you can only cancel the order. If your account balance is insufficient, you can set the AutoPay parameter to false. In this case, a normal unpaid order is generated. You can log on to the ECS console to pay for the order.

      • After the bandwidth is downgraded, the price difference is refunded to the original payment method. Vouchers that have been used are not refundable.

    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 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 instance: 0 to 200.

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

    Note

    The maximum outbound bandwidth per instance is also limited by the Network Bandwidth Baseline/Burstable (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 maximum outbound public bandwidth is less than or equal to 10 Mbit/s: 1 to 10. Default value: 10.

    • If the purchased maximum 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 yet available for use.

    null
    NetworkChargeType

    string

    No

    The conversion target for the network billing method. Valid values:

    • PayByBandwidth: pay-by-bandwidth.

    • PayByTraffic: pay-by-traffic.

    Note

    In pay-by-traffic mode, the inbound and outbound bandwidth peaks are both bandwidth upper limits and are not guaranteed as committed service metrics. When resource contention occurs, the bandwidth peaks may be throttled. If your business requires guaranteed bandwidth, use the pay-by-bandwidth mode.

    PayByTraffic
    AllocatePublicIp

    boolean

    No

    Specifies whether to allocate a public IP address.

    • true: allocates a public IP address.

    • false: does not allocate a public IP address.

    Default value: false.

    false
    StartTime

    string

    No

    The start time of the temporary bandwidth upgrade. Specify the time in the ISO 8601 standard in UTC+0 time in the yyyy-MM-ddTHH:mmZ format. The time must be 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 UTC+0 time in the yyyy-MM-ddTHHZ format. The time must be 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 enable automatic payment. Valid values:

    • true: After the bandwidth configuration is modified, the payment is automatically deducted. When you set the AutoPay parameter to true, make sure that your account has sufficient balance. If your account balance is insufficient, an abnormal order is generated. You cannot pay for the order on the ECS console. You can only cancel the order.

    • false: After the bandwidth configuration is modified, only an order is generated and no payment is made. If your payment method has insufficient balance, you can set the AutoPay parameter to false to disable automatic payment. In this case, the API generates a normal unpaid order. You can log on to the ECS console to pay for the order.

    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 you must 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.
    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.
    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.
    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.
    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.
    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.
    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 image is not authorized.
    403 InvalidInstanceChargeType.ValueNotSupported The specified parameter ChargeType is not valid.
    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
    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.
    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.

    See Error Codes for a complete list.

    Release notes

    See Release Notes for a complete list.