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 数。费用(微美元)按下式计算并向上取整:
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 上的设置 |
错误
所有错误的格式都一样:
{
"error": {
"code": "insufficient_funds",
"message": "Not enough available balance",
"request_id": "req_…"
}
}| 状态码 | code | 含义 |
|---|---|---|
| 400 | invalid_request | 缺了某个字段,或者某个字段不被接受,消息里会写是哪个。 |
| 400 | upstream_invalid_request、content_filter | 模型拒绝了输入,或者拒绝了这段内容。 |
| 401 | invalid_key | 没带 key、key 格式不对、key 不存在,或者已吊销、已过期。 |
| 402 | insufficient_funds | 可用余额不够预扣。 |
| 402 | key_limit_reached | key 的花费上限不够预扣。 |
| 403 | forbidden | key 不能用在这里,你的工作区被暂停了,或者资源被隔离待审核。 |
| 404 | not_found | 你的工作区里没有这个模型、资源、文件或路径。 |
| 409 | conflict | 资源当前的状态不能做这件事,或者 Idempotency-Key 配上了不同的参数。 |
| 409 | quota_exceeded | 超出了你在资源数、vCPU 或运行时长上的配额。 |
| 413 | payload_too_large | 请求体超过上限。 |
| 429 | rate_limited | 超过了 key 的每分钟请求数。按 Retry-After 里的秒数等一下。 |
| 500 | internal | 我们这边出了问题,稍后再试。 |
| 502 | upstream_failed、provider_authentication、provider_configuration、response_too_large | 没有模型部署给出可用的回答。 |
| 502 | no_image | 图片模型结束时没有出图。 |
| 503 | upstream_unavailable | 某项服务暂停了或没有响应(包括 Yi Labs 账号),这个架构不可用,或者命令、文件操作没能执行。稍后再试。 |
| 503 | upstream_capacity | 模型忙。 |
| 504 | upstream_timeout | 没有模型部署按时回答。 |
每种错误怎么处理,见常见问题。
公开接口
不需要 key。
| 接口 | 返回 |
|---|---|
GET /v1/catalog | {"models": [...]}:每个已开放的模型,带 id、name、kind、price、responses_api 和 max_output_tokens。 |
GET /v1/compute/classes | classes:每种规格,带 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/models | OpenAI 格式的列表,只列这个 key 能用的模型。 |
POST /v1/chat/completions | OpenAI chat completions。 |
POST /v1/responses | OpenAI Responses,只用于 responses_api: true 的模型。 |
POST /v1/embeddings | OpenAI embeddings。 |
POST /v1/messages | Anthropic Messages。 |
POST /v1/images/generations | OpenAI 图片生成,用于图片模型。见图片生成。 |
各接口接受什么,见模型 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 和资源对象。详见云主机。
资源对象
沙盒和云主机返回同样的结构。
| 字段 | |
|---|---|
id | sb_… 或 vm_…。 |
kind | sandbox 或 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 | 资源和它的状态。 |
currency | USD。 |
price_micro_per_hour、stopped_micro_per_hour | 它的价格。 |
rows | 每一笔扣费:kind(sandbox_seconds、vm_hours 或 vm_disk_gb_hours)、quantity、amount_micro 和 occurred_at。 |
total_micro | rows 的合计。 |
balance_micro、available_micro | 工作区当前的余额和可用余额。 |
as_of | 回执生成的时间。 |
final | 资源已经结束、不会再有扣费时为 true。 |
加 ?format=csv 时,列为 resource,kind,quantity,amount_micro,occurred_at。