Skip to content

API 参考 ​

https://cloud.theyilabs.com/v1 下的每个接口:怎么调用,返回什么。

基本约定 ​

  • Base URL:https://cloud.theyilabs.com/v1。Anthropic SDK 填 https://cloud.theyilabs.com,它会自己加上 /v1。
  • 鉴权:Authorization: Bearer <key>。/v1/messages 也接受 x-api-key: <key>。key 的格式是 pwc_live_…,见 API Key 与限额。
  • 请求体:JSON,带 Content-Type: application/json。上传文件例外,用 application/octet-stream。
  • 请求 ID:每个请求都有一个以 req_ 开头的 ID。模型接口成功返回时,响应头 x-request-id 里有它。每个错误体里的 request_id 也是它。

Idempotency-Key ​

创建、删除,以及云主机的每个操作(start、stop、reboot、reinstall、renew)都要带 Idempotency-Key 请求头:8 到 120 个字符,可以是字母、数字和 .、_、:、-。用 UUID 就行。

  • 请求在网络上失败时,用同一个 key 和同样的请求体再发一次。拿到的是第一次请求的结果,不会多建一个资源,也不会多扣一次钱。
  • 同一个 key 配上不同的参数,返回 409 conflict。
  • key 的作用范围是你的工作区。每个新操作用一个新 key。

执行命令(exec)不会被自动重复,也不需要这个 key。如果 exec 调用在网络上失败了,先查一下沙盒,再决定要不要重新执行。

金额 ​

金额以整数微美元表示:1 USD = 1,000,000 微美元。余额和费用常使用 _micro 后缀;计价字段还会注明时间或 token 单位。

GET /v1/catalog 的 price.input、price.output 和 price.cachedInput 是每百万 token 的微美元基价,没有 _micro 后缀。price.markup 是无单位的倍率;price.effectiveAt 是价格生效时间。cachedInput 为 null 时,缓存输入按 input 基价计算。price.imageOutput 是图片模型的图片输出价,其他模型为 null。

设 I 为输入 token 总数,C 为其中的缓存输入 token 数,O 为输出 token 数(文字和思考),G 为图片输出 token 数。费用(微美元)按下式计算并向上取整:

text
ceil(((I - C) * input + C * (cachedInput ?? input) + O * output + G * (imageOutput ?? output)) * markup / 1,000,000)

价格请读取当前目录,实付金额以用量记录和回执为准。

限制 ​

项目上限
模型请求的请求体4 MiB
其他请求的请求体1 MiB
文件的一块,上传或下载64 KiB
不用流式时的命令输出1 MiB
一个沙盒同时运行的命令4 条
列表里的条目最近的 200 个
每分钟请求数按 key 上的设置

模型请求的限制见模型 API,算力配额见配额与网络。

错误 ​

所有错误的格式都一样:

json
{
  "error": {
    "code": "insufficient_funds",
    "message": "Not enough available balance",
    "request_id": "req_…"
  }
}
状态码code含义
400invalid_request缺了某个字段,或者某个字段不被接受,消息里会写是哪个。
400upstream_invalid_request、content_filter模型拒绝了输入,或者拒绝了这段内容。
401invalid_key没带 key、key 格式不对、key 不存在,或者已吊销、已过期。
402insufficient_funds可用余额不够预扣。
402key_limit_reachedkey 的花费上限不够预扣。
403forbiddenkey 不能用在这里,你的工作区被暂停了,或者资源被隔离待审核。
404not_found你的工作区里没有这个模型、资源、文件或路径。
409conflict资源当前的状态不能做这件事,或者 Idempotency-Key 配上了不同的参数。
409quota_exceeded超出了你在资源数、vCPU 或运行时长上的配额。
413payload_too_large请求体超过上限。
429rate_limited超过了 key 的每分钟请求数。按 Retry-After 里的秒数等一下。
500internal我们这边出了问题,稍后再试。
502upstream_failed、provider_authentication、provider_configuration、response_too_large没有模型部署给出可用的回答。
502no_image图片模型结束时没有出图。
503upstream_unavailable某项服务暂停了或没有响应(包括 Yi Labs 账号),这个架构不可用,或者命令、文件操作没能执行。稍后再试。
503upstream_capacity模型忙。
504upstream_timeout没有模型部署按时回答。

每种错误怎么处理,见常见问题。

公开接口 ​

不需要 key。

接口返回
GET /v1/catalog{"models": [...]}:每个已开放的模型,带 id、name、kind、price、responses_api 和 max_output_tokens。
GET /v1/compute/classesclasses:每种规格,带 id、vcpu、memory_gb、disk_gb、price_micro_per_hour 和 stopped_micro_per_hour。pools:pool 能填的资源池(pool-1、pool-2、pool-3),各带 architectures。

从 cloud 迁移到 pool ​

规格接口仍是 GET /v1/compute/classes,classes 数组保持不变。该响应中的 clouds 改为 pools;创建请求和资源响应使用 pool。省略可选的 pool 时由服务选择;指定时,从当前 pools 列表中选择 id。旧 cloud 字段会返回 400 invalid_request,不会被忽略或自动转换。

模型 ​

key 的用途要有「模型 API」。

接口
GET /v1/modelsOpenAI 格式的列表,只列这个 key 能用的模型。
POST /v1/chat/completionsOpenAI chat completions。
POST /v1/responsesOpenAI Responses,只用于 responses_api: true 的模型。
POST /v1/embeddingsOpenAI embeddings。
POST /v1/messagesAnthropic Messages。
POST /v1/images/generationsOpenAI 图片生成,用于图片模型。见图片生成。

各接口接受什么,见模型 API。

沙盒 ​

key 的用途要有「沙盒」。

接口Idempotency-Key
POST /v1/sandboxes要创建。请求体:class,可选 arch、pool、timeout_s、idle_timeout_s、metadata。返回 202 和资源对象。
GET /v1/sandboxes{"resources": [...]},最近的 200 个。
GET /v1/sandboxes/{id}资源对象。
DELETE /v1/sandboxes/{id}要删除。返回 202 和资源对象。
POST /v1/sandboxes/{id}/keepalive重新计算空闲时间。返回 {"ok": true}。
POST /v1/sandboxes/{id}/exec执行命令。请求体:cmd,可选 cwd、env、timeout_s、stream。
GET /v1/sandboxes/{id}/files?path=…读取最多 64 KiB,用 Range: bytes=start-end 请求头指定范围。返回 200 或 206,带 Content-Range。
PUT /v1/sandboxes/{id}/files?path=…&offset=…&truncate=…在 offset 处写入最多 64 KiB 的 application/octet-stream。返回 204。
GET /v1/sandboxes/{id}/receipt回执。加 ?format=csv 返回 CSV。

exec、files 和 keepalive 要求沙盒处于 ready 或 busy,否则返回 409 conflict。详见沙盒。

云主机 ​

key 的用途要有「云主机」。

接口Idempotency-Key
POST /v1/vms要创建。请求体:class、ssh_public_keys、allowed_cidrs,可选 arch、pool、hours、metadata。返回 202 和资源对象。
GET /v1/vms{"resources": [...]},最近的 200 个。
GET /v1/vms/{id}资源对象。
DELETE /v1/vms/{id}要删除,连同磁盘。返回 202。
POST /v1/vms/{id}/start要启动停机的云主机。需要还有预付的时间。
POST /v1/vms/{id}/stop要停止。
POST /v1/vms/{id}/reboot要重启正在运行的云主机。
POST /v1/vms/{id}/reinstall要清空系统盘并重装。请求体:{"confirm_destroy_disk": true}。
POST /v1/vms/{id}/renew要延长租期。请求体:{"hours": n},1 到 168。当场扣费。
GET /v1/vms/{id}/serial启动串口输出的最后 64 KiB,文本。
GET /v1/vms/{id}/receipt回执。加 ?format=csv 返回 CSV。

操作都返回 202 和资源对象。详见云主机。

资源对象 ​

沙盒和云主机返回同样的结构。

字段
idsb_… 或 vm_…。
kindsandbox 或 vm。
class、arch、pool创建时的设置。
cpu、memory_gb、disk_gb资源大小。
state当前状态。见沙盒和云主机。
desired要去的状态:running、stopped 或 deleted。
price_micro_per_hour、stopped_micro_per_hour价格,创建时固定。
public_ip云主机运行后的地址。沙盒没有。
ssh_user、allowed_cidrs怎么 SSH 到云主机。
timeout_s、idle_timeout_s沙盒的运行时长和空闲回收时间。对云主机来说,timeout_s 是首次租期的秒数。
prepaid_until、stopped_at云主机的租期截止时间和停机时间。
trust_tier创建时你的信任档位。
metadata你传入的内容。
created_at、ready_at请求时间,以及第一次可用或运行起来的时间。
error_code如果不是你结束或停止的,这里写原因。见常见问题。
isolated为 true 表示被我们隔离待审核,这时只能 stop 和 delete。

回执 ​

GET /v1/{sandboxes|vms}/{id}/receipt 返回:

字段
resource_id、state资源和它的状态。
currencyUSD。
price_micro_per_hour、stopped_micro_per_hour它的价格。
rows每一笔扣费:kind(sandbox_seconds、vm_hours 或 vm_disk_gb_hours)、quantity、amount_micro 和 occurred_at。
total_microrows 的合计。
balance_micro、available_micro工作区当前的余额和可用余额。
as_of回执生成的时间。
final资源已经结束、不会再有扣费时为 true。

加 ?format=csv 时,列为 resource,kind,quantity,amount_micro,occurred_at。