API reference
Every endpoint under https://cloud.theyilabs.com/v1, how to call it, and what comes back.
Basics
- Base URL:
https://cloud.theyilabs.com/v1. The Anthropic SDKs takehttps://cloud.theyilabs.comand add/v1themselves. - Authentication:
Authorization: Bearer <key>. On/v1/messages,x-api-key: <key>works too. Keys look likepwc_live_…. See API keys and limits. - Bodies: JSON with
Content-Type: application/json, except file uploads, which areapplication/octet-stream. - Request IDs: every request gets an ID that starts with
req_. Successful model answers carry it in thex-request-idheader, and every error body includes it asrequest_id.
Idempotency-Key
Creating, deleting and every VM action (start, stop, reboot, reinstall, renew) need an Idempotency-Key header: 8 to 120 characters of letters, digits, ., _, : and -. A UUID works.
- If a request fails on the network, send it again with the same key and the same body. You get the result of the first request instead of a second resource or a second charge.
- The same key with different parameters gets
409 conflict. - Keys belong to your workspace. Use a new key for each new operation.
Commands (exec) are never repeated for you and take no key. If an exec call fails on the network, check the sandbox before running the command again.
Money
Amounts are whole numbers of micro-dollars: 1 USD = 1,000,000 micro-dollars. Balances and charges commonly use the _micro suffix; rate fields also specify a time or token unit.
In GET /v1/catalog, price.input, price.output and price.cachedInput are base prices in micro-dollars per million tokens, without the _micro suffix. price.markup is a unitless multiplier; price.effectiveAt is when the price takes effect. A null cachedInput uses the input base price. price.imageOutput is the image output price of an image model, and null for other models.
For total input tokens I, cached input tokens C within that total, output tokens O (text and thinking) and image output tokens G, calculate the charge in micro-dollars and round up:
ceil(((I - C) * input + C * (cachedInput ?? input) + O * output + G * (imageOutput ?? output)) * markup / 1,000,000)Read current prices from the catalog. Usage records and receipts show the amount charged.
Limits
| Limit | Value |
|---|---|
| Body of a model request | 4 MiB |
| Body of any other request | 1 MiB |
| File piece, upload or download | 64 KiB |
| Command output without streaming | 1 MiB |
| Commands running at once in one sandbox | 4 |
| Items in a list | 200 most recent |
| Requests per minute | As set on the key |
Model request limits are in Models API. Compute quotas are in Quotas and network.
Errors
Every error has the same shape:
{
"error": {
"code": "insufficient_funds",
"message": "Not enough available balance",
"request_id": "req_…"
}
}| Status | code | Meaning |
|---|---|---|
| 400 | invalid_request | A field is missing or not accepted. The message says which. |
| 400 | upstream_invalid_request, content_filter | The model rejected the input, or refused the content. |
| 401 | invalid_key | No key, a malformed key, an unknown key, or a revoked or expired one. |
| 402 | insufficient_funds | The available balance can't cover the hold. |
| 402 | key_limit_reached | The key's spend limit can't cover the hold. |
| 403 | forbidden | The key may not be used here, your workspace is suspended, or the resource is closed off for review. |
| 404 | not_found | No such model, resource, file or path in your workspace. |
| 409 | conflict | The resource isn't in a state for this, or an Idempotency-Key was reused with other parameters. |
| 409 | quota_exceeded | Your quota for resources, vCPUs or lifetime. |
| 413 | payload_too_large | The body is over the limit. |
| 429 | rate_limited | The key's requests-per-minute limit. Wait the seconds in Retry-After. |
| 500 | internal | Something failed on our side. Try again later. |
| 502 | upstream_failed, provider_authentication, provider_configuration, response_too_large | No model deployment gave a usable answer. |
| 502 | no_image | The image model ended without an image. |
| 503 | upstream_unavailable | A service is paused or not answering (the Yi Labs account included), the architecture isn't available, or a command or file call couldn't be carried out. Try again shortly. |
| 503 | upstream_capacity | The model is busy. |
| 504 | upstream_timeout | No model deployment answered in time. |
What to do about each is in Troubleshooting.
Public endpoints
No key needed.
| Endpoint | Returns |
|---|---|
GET /v1/catalog | {"models": [...]}: each enabled model with id, name, kind, price, responses_api and max_output_tokens. |
GET /v1/compute/classes | classes: each size with id, vcpu, memory_gb, disk_gb, price_micro_per_hour and stopped_micro_per_hour. pools: the resource pools pool accepts (pool-1, pool-2, pool-3), each with its architectures. |
Moving from cloud to pool
The size endpoint remains GET /v1/compute/classes, with the same classes array. Its clouds field becomes pools; create requests and resource answers use pool. Omit the optional pool to let the service choose, or select an id from the current pools list. The old cloud field returns 400 invalid_request; it is neither ignored nor converted.
Models
Key with "Model API".
| Endpoint | |
|---|---|
GET /v1/models | OpenAI-style list of the models this key may use. |
POST /v1/chat/completions | OpenAI chat completions. |
POST /v1/responses | OpenAI Responses, for models with responses_api: true. |
POST /v1/embeddings | OpenAI embeddings. |
POST /v1/messages | Anthropic Messages. |
POST /v1/images/generations | OpenAI image generation, for image models. See Image generation. |
What each accepts is in Models API.
Sandboxes
Key with "Sandboxes".
| Endpoint | Idempotency-Key | |
|---|---|---|
POST /v1/sandboxes | Yes | Create. Body: class, and optionally arch, pool, timeout_s, idle_timeout_s, metadata. Answers 202 with the resource. |
GET /v1/sandboxes | {"resources": [...]}, the 200 most recent. | |
GET /v1/sandboxes/{id} | The resource. | |
DELETE /v1/sandboxes/{id} | Yes | Delete. Answers 202 with the resource. |
POST /v1/sandboxes/{id}/keepalive | Resets the idle time. Answers {"ok": true}. | |
POST /v1/sandboxes/{id}/exec | Run a command. Body: cmd, and optionally cwd, env, timeout_s, stream. | |
GET /v1/sandboxes/{id}/files?path=… | Read up to 64 KiB, chosen with a Range: bytes=start-end header. Answers 200 or 206 with Content-Range. | |
PUT /v1/sandboxes/{id}/files?path=…&offset=…&truncate=… | Write up to 64 KiB of application/octet-stream at offset. Answers 204. | |
GET /v1/sandboxes/{id}/receipt | The receipt. ?format=csv for CSV. |
exec, files and keepalive need the sandbox to be ready or busy. Otherwise they get 409 conflict. Details in Sandboxes.
VMs
Key with "VMs".
| Endpoint | Idempotency-Key | |
|---|---|---|
POST /v1/vms | Yes | Create. Body: class, ssh_public_keys, allowed_cidrs, and optionally arch, pool, hours, metadata. Answers 202 with the resource. |
GET /v1/vms | {"resources": [...]}, the 200 most recent. | |
GET /v1/vms/{id} | The resource. | |
DELETE /v1/vms/{id} | Yes | Delete, disk included. Answers 202. |
POST /v1/vms/{id}/start | Yes | Start a stopped VM. Needs prepaid time left. |
POST /v1/vms/{id}/stop | Yes | Stop. |
POST /v1/vms/{id}/reboot | Yes | Restart a running VM. |
POST /v1/vms/{id}/reinstall | Yes | Erase the system disk and reinstall. Body: {"confirm_destroy_disk": true}. |
POST /v1/vms/{id}/renew | Yes | Extend the lease. Body: {"hours": n}, 1 to 168. Charged at once. |
GET /v1/vms/{id}/serial | The last 64 KiB of boot serial output, as text. | |
GET /v1/vms/{id}/receipt | The receipt. ?format=csv for CSV. |
Actions answer 202 with the resource. Details in VMs.
The resource object
Sandboxes and VMs come back in the same shape.
| Field | |
|---|---|
id | sb_… or vm_…. |
kind | sandbox or vm. |
class, arch, pool | What it was created with. |
cpu, memory_gb, disk_gb | Its size. |
state | Where it is now. See Sandboxes and VMs. |
desired | Where it's heading: running, stopped or deleted. |
price_micro_per_hour, stopped_micro_per_hour | Its prices, fixed when it was created. |
public_ip | A VM's address once it runs. Sandboxes have none. |
ssh_user, allowed_cidrs | How to reach a VM over SSH. |
timeout_s, idle_timeout_s | A sandbox's lifetime and idle time. For a VM, timeout_s is the first lease in seconds. |
prepaid_until, stopped_at | A VM's lease end, and when it stopped. |
trust_tier | Your trust tier when the resource was created. |
metadata | What you sent. |
created_at, ready_at | When it was requested and when it first became ready or ran. |
error_code | Why it ended or stopped, if it wasn't you. See Troubleshooting. |
isolated | true if we closed it off for review. Only stop and delete work then. |
The receipt
GET /v1/{sandboxes|vms}/{id}/receipt answers:
| Field | |
|---|---|
resource_id, state | The resource and its state. |
currency | USD. |
price_micro_per_hour, stopped_micro_per_hour | Its prices. |
rows | Each charge: kind (sandbox_seconds, vm_hours or vm_disk_gb_hours), quantity, amount_micro and occurred_at. |
total_micro | The sum of rows. |
balance_micro, available_micro | Your workspace's balance and available balance now. |
as_of | When the receipt was made. |
final | true once the resource has ended and nothing more will be charged. |
With ?format=csv you get resource,kind,quantity,amount_micro,occurred_at.