Skip to content

Quickstart ​

From signing in to your first model call and your first sandbox.

Before you start

You need a Yi Labs account. Your Yi Cloud workspace is set up the first time you sign in.

1. Sign in ​

  1. Open the console at https://cloud.theyilabs.com and click the sign-in button.
  2. Sign in with your Yi Labs account.

You land on the Overview page. It shows your available balance, what is held, and the usage this month. See Workspace and sign-in.

2. Get credit ​

Model calls and resources are paid from the paid credit in your Yi Labs account. Top up or choose a paid plan in your Yi Labs account at https://account.theyilabs.com/billing. Free credit doesn't work on Yi Cloud.

The Billing page shows what your Yi Labs wallet has for Yi Cloud. When you use Yi Cloud, money moves from there to your workspace in small blocks. See Billing and receipts.

3. Create an API key ​

  1. Click "Model API" in the sidebar, then "Manage API keys".
  2. Under "Projects", type a project name and click "New project".
  3. Under "New key", pick the project. Under "Use for", tick "Model API" and "Sandboxes". The limits are optional. Click "Create".
  4. Copy the key. It is shown only this once.

Keep it in an environment variable rather than in your code:

sh
export YI_CLOUD_API_KEY='pwc_live_…'

More in API keys and limits.

4. Call a model ​

The catalog lists the models you can call. It needs no key:

sh
curl https://cloud.theyilabs.com/v1/catalog

Call a chat model with curl:

sh
curl https://cloud.theyilabs.com/v1/chat/completions \
  -H "Authorization: Bearer $YI_CLOUD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"gemini-4-argon","messages":[{"role":"user","content":"Hello"}],"max_tokens":128}'

Or with the OpenAI SDK for Python. Only the base URL and the key change:

python
import os
from openai import OpenAI

client = OpenAI(api_key=os.environ["YI_CLOUD_API_KEY"], base_url="https://cloud.theyilabs.com/v1")
response = client.chat.completions.create(
    model="gemini-4-argon",
    messages=[{"role": "user", "content": "Hello"}],
    max_completion_tokens=128,
)
print(response.choices[0].message.content)

The call shows under "Recent requests" on the Model API page with its cost. Setting a maximum output keeps the call's hold small. See Models API.

5. Start a sandbox ​

First request GET https://cloud.theyilabs.com/v1/compute/classes and choose an available size from classes. If the list is empty, compute cannot be created; use the Models API while no size is available. The create examples below require an available size and enough available credit.

The key needs "Sandboxes" under "Use for". Sizes and their hourly prices are listed at GET https://cloud.theyilabs.com/v1/compute/classes.

Create a sandbox that lives at most 10 minutes. Use a class id from that list. This example uses small. Creating needs an Idempotency-Key. Keep it in a variable so a retry sends the same one:

sh
RETRY_KEY=$(uuidgen)
curl https://cloud.theyilabs.com/v1/sandboxes \
  -H "Authorization: Bearer $YI_CLOUD_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $RETRY_KEY" \
  -d '{"class":"small","timeout_s":600}'

The answer is the new sandbox, with an id that starts with sb_ and "state": "requested". Ask for it until state is ready:

sh
SANDBOX=sb_…   # the id from the answer
curl https://cloud.theyilabs.com/v1/sandboxes/$SANDBOX -H "Authorization: Bearer $YI_CLOUD_API_KEY"

Run a command:

sh
curl https://cloud.theyilabs.com/v1/sandboxes/$SANDBOX/exec \
  -H "Authorization: Bearer $YI_CLOUD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"cmd":"uname -a && pwd","timeout_s":30}'

The answer has stdout, stderr and exit_code. Delete the sandbox when you're done:

sh
curl -X DELETE https://cloud.theyilabs.com/v1/sandboxes/$SANDBOX \
  -H "Authorization: Bearer $YI_CLOUD_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

The sandbox is billed per second from when it became ready until it is deleted, with a 60-second minimum. If you forget to delete it, it is deleted when its 10 minutes are up, or after 5 minutes without a command or file call.

Next ​

  • Models API: streaming, embeddings, Anthropic Messages, failover and limits.
  • Codex and Claude Code: run coding agents on Yi Cloud's models.
  • Sandboxes: files, streaming command output, lifetime and idle time.
  • VMs: SSH access, leases and stopped machines.
  • Troubleshooting: what each error code means.