创建一个 ArkClaw 实例。更多操作介绍请参见申请 ArkClaw 实例。

请求参数

下方仅列出该接口特有的请求参数和部分公共参数。更多信息请见公共参数。

Action string 必选示例值：CreateClawInstance

要执行的操作，取值：CreateClawInstance。

Version string 必选示例值：2026-05-01

API的版本，取值：2026-05-01。

TemplateId string 可选示例值：ctpl-yejkl6vzlsj0sv1xy****

Claw 模板的 ID。可在 ArkClaw 控制台“模板中心”页面的“Claw 模板”页签下获取。

不填则不使用模板创建实例。

填写时须为当前账号或空间内可见的Claw模板ID。

EnableHeadless boolean 可选示例值：false

是否启用 Headless 模式。取值：

true：启用。实例将归属调用该接口的系统账号，不支持传入UserId，否则接口将报错。

false（默认）：不启用。可传入UserId指定实例的归属用户。

说明

EnableHeadless 取值为 false 时，若不传入 UserId，依赖用户身份认证的功能无法正常使用。如需补充归属用户，可调用 UpdateClawInstance 接口更新。

ImageId string 可选示例值：cimg-yesp6tps74dqk9ay****

镜像 ID，使用此镜像创建 Claw 实例。

不填则不使用镜像创建实例。

填写时须为当前账号或空间内有权限的 Claw 镜像 ID。可使用ListClawImages接口查询 ArkClaw 镜像详情。

Description string 可选示例值：Claw for the HR department.

Claw 实例的描述。

取值：

长度限制为 1000 以内的 Unicode 字符。

不填默认为空。

InstanceName string 必选示例值：instance-001

Claw 实例名称。

取值：

支持大小写英文字母、数字、中划线（-）、下划线(_)。

长度限制为4 ~ 64个字符。

ModelApiKey string 可选示例值：8c78xxx-xxx-6d4d14xxx-0a053

模型的 APIKey。

空间选择“自定义模型配置”且选择 APIKey 为“员工自行配置”时需要填写。

不填默认为空间模型配置时生成的 APIKey。

SeatType string 必选示例值：Starter

Claw 实例席位类型。

取值：

Starter：轻量版。

Standard：标准版。

Premium：高级版。

Ultimate：旗舰版。

SpaceId string 必选示例值：csi-yei8347ta8xmf5qd****

Claw 实例所属空间 ID，可以在 ArkClaw 控制台“空间概览”页面的“基本信息”获取。

UserId string 可选示例值：22e122d8-f804-4a86-999f-ddd1aada****

用户 ID。可以在 ArkClaw 控制台“用户管理”页面获取。

说明

仅EnableHeadless选false时支持传入UserId，若不传入UserId，依赖用户身份认证的功能无法正常使用。如需补充归属用户，可调用 UpdateClawInstance 接口更新。

BillingType string 可选示例值：InstancePrePaid

计费方式。取值：

SeatPrePaid（默认）：席位预付费。

InstancePrePaid：实例预付费。

Period integer 可选示例值：1

购买时长，单位：月。

取值范围： 1，2，3，4，5，6，7，8，9，10，11，12。超过此范围不合法。不填默认为0。

说明

当BillingType为InstancePrePaid时必填。

AutoRenew boolean 可选示例值：false

表示是否自动续费。取值：

true：自动续费。

false（默认）：不自动续费。

说明

当BillingType为InstancePrePaid时必填。

DryRun boolean 可选示例值：false

预检模式。取值：

true：开启预检模式，仅校验参数并计算预估价格，不实际下单或创建实例。

false（默认）：关闭预检模式，按正常流程下单并创建实例。

ClientToken string 可选示例值：23fa21A8823nfasd7f****

用于保证幂等性的客户端 Token。取值：

长度1~64个字符。

仅支持大小写字母、数字和中划线（-），匹配正则^[a-zA-Z0-9-]+$。

在 Account+Action 粒度内24小时有效。

不填则不进行幂等保证。

返回参数

下方仅列出本接口特有的返回参数。更多信息请参见返回结构。

InstanceId string 示例值：ci-yenpivj6rkcfs2i8****

新创建的 Claw 实例 ID。

请求示例

返回示例

错误码

下表为您列举了该接口与业务逻辑相关的错误码。公共错误码请参见公共错误码文档。

状态码	错误码	错误信息	说明
400	MissingParameter.InstanceName	The required parameter InstanceName is not supplied.	参数 InstanceName 不能为空。
400	MissingParameter.SeatType	The required parameter SeatType is not supplied.	参数 SeatType 不能为空。
400	MissingParameter.SpaceId	The required parameter SpaceId is not supplied.	参数 SpaceId 不能为空。
400	Insufficient.Balance	The request is denied due to the lack of balance.	账户余额不足。
400	MissingParameter.UserId	The required parameter UserId is not supplied.	参数 UserId 不能为空。
400	InvalidAccount.PartnerDedicated	Your account is a partner dedicated account and does not allow orders to be placed.	当前账号为伙伴专用账号，无法下单。
400	OperationDenied.PurchaseLimited	You are not authorized to purchase.	无权限购买 Claw。
400	OperationDenied.AccountWeakVerified	The specified action is denied because the account failed to pass the weak real-name authentication.	指定的操作被拒绝，因为该账号弱实名认证失败。
400	InvalidInstanceName.Malformed	The specified InstanceName is malformed.	参数 InstanceName 不合法。
400	InvalidSeatType.Malformed	The specified SeatType is malformed.	参数 SeatType 不合法。
400	InvalidUserId.Malformed	The specified UserId is malformed.	参数 UserId 不合法。
400	InvalidDescription.Malformed	The specified Description is malformed.	参数 Description 不合法。
404	InvalidSpace.NotFound	The specified Space does not exist.	指定 ArkClaw 空间不存在。
404	InvalidTemplate.NotFound	The specified Template does not exist.	指定的 Claw 模版不存在。
412	PendingVerification	Your account has not passed the real-name authentication yet.	账户未实名认证。
412	NotPaymentQualified	Your account has not passed the payment qualified yet.	账户未支付认证。
412	OperationDenied.NotOpeningQualified	The specified action is denied because the account has not completed account authentication.	指定的操作被拒绝，因为该账号没有进行开户认证。
412	OperationDenied.RiskInterception	The specified action is denied. Due to risk interception, this feature is temporarily unavailable.	指定的操作被拒绝，风控拦截暂无法使用该功能。
412	OperationDenied.AccountTaxNoInvalid	To purchase BytePlus products, you need to provide a Goods and Services Tax (GST) number.	购买的产品需要提供商品及服务税(GST)号码。
412	OperationDenied.AccountCountryAreaInvalid	This product is temporarily not available for sale in the country or region where you registered your account.	当前该产品暂不支持在您注册账户所在的国家/地区销售。
412	OperationDenied.NotSupportPaypal	You are requested to provide an alternative payment method other than Paypal before enabling the pay-as-you-go products in BytePlus.	本次下单的后付费商品不支持Paypal支付，请补充其他支付方式。
412	OperationDenied.MainAccountNotSupportPaypal	You are requested to contact the main account to provide an alternative payment method other than Paypal before enabling the pay-as-you-go products in BytePlus.	本次下单的后付费商品不支持Paypal支付，请联系主账号补充其他支付方式。
412	OperationDenied.AccountDeleted	The specified action is denied because the account has been deleted.	指定的操作被拒绝，因为该账号已注销。
412	InvalidSeatType.TemplateMismatch	The specified SeatType is not supported by the Template.	指定的 SeatType 不在该模板支持的席位类型范围内。
429	FlowLimitExceeded	The request was rejected due to flow control.	请求触发限流。
500	InternalError	An internal error has occurred.	内部错误，请重试。如果多次尝试失败，请提交工单。
500	InternalError	An internal error has occurred.	内部错误，请重试。如果多次尝试失败，请提交工单。

ArkClaw 企业版