草根云 API / v1

在用户中心创建 API 密钥，使用 Bearer 认证。密钥仅展示一次，可撤销、设定有效期和只读权限。每个密钥每分钟限 60 次请求，超限返回 429 和 Retry-After。网页与 API 共用余额、会员门槛、指定资源池和实例时长限制。

读取账户与配置

curl "$BASE/api/v1/config" \
  -H "Authorization: Bearer $API_KEY"

curl "$BASE/api/v1/account" \
  -H "Authorization: Bearer $API_KEY"

BASE 为本站地址，例如 https://caogenyun.com。配置响应包含套餐、镜像、资源费率、GPU 售价、会员门槛和当前账户权限。API 不提供管理员接口或上游凭据。

创建服务器

# 先 POST /api/v1/quote 获取 billing_version、预扣金额和资源可用状态
# 下方 billing_version 填写报价中返回的原始版本值
curl -X POST "$BASE/api/v1/quote" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"cpu":2,"mem_mb":2048,"minutes":10,"ports":[22,8080],"image_id":"debian13","data_disk":false,"network_budget_gib":1}'

# 确认报价后使用完全相同的资源配置创建
curl -X POST "$BASE/api/v1/servers" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: example-order-20261010-001" \
  -d '{"cpu":2,"mem_mb":2048,"minutes":10,"ports":[22,8080],"image_id":"debian13","data_disk":false,"network_budget_gib":1,"billing_ack":true,"billing_version":"报价返回的版本"}'

需要 read + write 权限。CPU 为物理核，内存以 MiB 计，端口须含 22。GPU 增加 gpu_type 与 gpu_count，例如 T4、1，并选择对应 CUDA 镜像。B300 需 CUDA 13.1+。可选数据盘使用 data_disk:true 和 storage_budget_gib（1–1000）；预算是预扣估算，按实际写入用量结算。

{"order_id":123,"price":0.04,"status":"queued"}

提交时预扣余额，异步创建。用 GET /servers/123 查看结果；创建失败自动退款。重试同一创建请求必须使用原 Idempotency-Key 和相同配置，返回原订单；修改配置须换新编号。请求编号必须为 16–100 个字母、数字、下划线或连字符。

服务器与账务

方法	/api/v1 路径	用途
GET	/servers	自己的服务器和订单
GET	/servers/{id}	订单状态、SSH、端口及系统密码
GET	/servers/{id}/logs	实例日志
GET	/servers/{id}/stats	Linux 资源状态
POST	/servers/{id}/manage	action: reset_password 或 reload_ssh
POST	/servers/{id}/destroy	销毁运行中实例
POST	/servers/{id}/close	关闭实例并清理数据盘、结算
GET	/membership	当前等级与 GPU 门槛
GET	/transactions	余额流水
GET	/recharge	充值配置及自己的充值订单
POST	/recharge	创建充值订单，同样要求 Idempotency-Key
POST	/quote	创建配置报价：计算费、用量预扣、资源额度与规则版本
GET	/billing-rules	完整计费规则
POST	/servers/{id}/cancel	取消尚未提交上游的排队订单并退款
GET	/servers/{id}/events	订单生命周期事件
POST	/servers/{id}/snapshot	保存文件系统快照，保留七天
GET	/assets	自己的保留数据卷和快照
GET	/notifications	费用和实例通知

USDT 充值

curl -X POST "$BASE/api/v1/recharge" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: example-recharge-20261009-001" \
  -d '{"amount":"1.000000","trade_type":"usdt.trc20"}'

最低充值 0.1 USDT，金额最多六位小数。返回 order.payment_url 和 order.expected_usdt，按应付完整金额付款。实际支付确认后才入账，网页返回地址不会触发加款。review 表示上游创建结果不确定，需要人工核查，原请求编号不会自动重复提交。

错误

错误返回 JSON {"error":"原因"}。401 为认证失效，403 为权限不足，400 为配置、余额或会员门槛不满足，404 为对象不存在，429 为限速，502 为上游操作失败。只可访问自己的实例和订单。

用量、网络与恢复

计算费为固定时长售价，主动提前关闭不退计算费；提前退出按尚未使用时长退回。数据盘预扣至少 60 分钟，流量预算停止后按采样结算。本站采样不是上游精确账单。用量占用汇总到可用余额，余额接近不足时自动回收。

可选 retain_volume:true 在停止后保留 /data 并持续计费；source_volume_id 挂载自己保存的卷，snapshot_id 从快照重建，均只匹配同工作区且有权限的凭据。快照不含数据卷与 GPU 内存。ssh_public_key 用于公钥登录；tls_ports 是 ports 的子集，不含 22；inbound_cidrs 是 IP/CIDR 数组。指定 region 会增加计算费。

manage 支持 stats、reload_ssh、reset_password、command（最多 15 秒）、file_list、file_read、file_write（最多 64 KiB）和 restart_service；文件内容使用 Base64，覆盖须 overwrite:true。快照恢复与数据卷挂载会创建另一个收费订单。