v3 vs v4: Choosing a Computer Use Model on the API
If you have ever written a script that clicks a button only to break when the layout changes, you know the pain of brittle selectors and API-only tools. The Coasty Computer Use API lets an agent see the screen and move the mouse or press keys like a human. The v3 model gives you low-level, step-by-step control. The v4 model wraps that in an autonomous pass/fail verifier so the server can drive a run to completion for you. This guide shows the exact differences, the endpoints you use, and when to pick which.
How the models differ
- ●v3 is a prediction model you call over and over. You send a screenshot and instruction, and it returns actions. You loop capture, predict, act until a status of done.
- ●v4 is the same prediction model but configured as an autonomous run. You POST to POST /v1/runs with cua_version: "v4". The server steps the agent and runs a pass/fail verifier automatically.
- ●Both versions charge $0.05 per step. v3 lets you orchestrate the loop yourself; v4 lets the server orchestrate and reports a final status of succeeded or failed.
- ●You can still inspect the trajectory and events with GET /v1/runs/{id}/events, which streams Server-Sent Events. Reconnect with Last-Event-ID if needed.
Using v3: step-by-step control
- ●Start a session to store the trajectory. POST to /v1/sessions. It returns an id and an initial state.
- ●For each step, POST to /v1/sessions/{id}/predict. Include a base64 screenshot, an instruction, and cua_version: "v3".
- ●The response contains actions and a status. Keep capturing the screen, predicting, and acting until status is done.
- ●You can also call POST /v1/predict directly (base64 screenshot + instruction + cua_version) if you do not need stateful trajectory memory.
# Example: run a v3 computer use step on a session
# Create a session (stateful trajectory memory)
curl -X POST https://coasty.ai/v1/sessions \
-H "X-API-Key: $COASTY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"cua_version": "v3"
}'
# Assume SESSION_ID is returned from the session response
# Capture a screenshot and predict next actions
SCREENSHOT=$(base64 -i screen.png)
curl -X POST https://coasty.ai/v1/sessions/${SESSION_ID}/predict \
-H "X-API-Key: $COASTY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"screenshot": "'"$SCREENSHOT"'",
"instruction": "Click the login button",
"cua_version": "v3"
}'
# Loop: capture, predict, act until status is done
# For brevity, the loop is omitted here.Using v4: autonomous runs
- ●POST to /v1/runs with machine_id, task, and cua_version: "v4". The server provisions a cloud VM and runs the agent.
- ●You can provide optional instructions to append to the base prompt, system_prompt, max_steps, deadline_seconds, on_awaiting_human, and webhook_url.
- ●The run state transitions through queued, running, awaiting_human, succeeded, failed, cancelled, or timed_out.
- ●Billed $0.05 per agent step. The server handles the loop and gives you a final outcome instead of returning actions.
import os
import requests
API_KEY = os.getenv("COASTY_API_KEY")
BASE_URL = "https://coasty.ai/v1"
# Example: start an autonomous v4 run
def create_v4_run(machine_id: str, task: str, max_steps: int = 100):
resp = requests.post(
f"{BASE_URL}/runs",
headers={"X-API-Key": API_KEY},
json={
"machine_id": machine_id,
"task": task,
"cua_version": "v4",
"max_steps": max_steps,
"on_awaiting_human": "pause",
},
)
resp.raise_for_status()
return resp.json()
# Example: check run status
def get_run_status(run_id: str):
resp = requests.get(f"{BASE_URL}/runs/{run_id}", headers={"X-API-Key": API_KEY})
resp.raise_for_status()
return resp.json()
# Example: stream event updates
def stream_run_events(run_id: str):
url = f"{BASE_URL}/runs/{run_id}/events"
resp = requests.get(url, headers={"X-API-Key": API_KEY}, stream=True)
resp.raise_for_status()
for line in resp.iter_lines():
if line:
print(line.decode("utf-8"))Use v3 when you need fine-grained control over prediction steps. Use v4 for autonomous runs with an automatic pass/fail verifier.
Where this beats brittle automation
- ●Computer use agents see the screen and react to visual layout changes, so you do not need brittle selectors or fragile XPath.
- ●With v3 you can inspect each action and handle special cases. With v4 the server handles the loop and gives you a final status.
- ●Both versions are billed $0.05 per step, so you can switch between models without changing your pricing model.
- ●You can still use other endpoints like POST /v1/parse to turn pyautogui code into structured actions or POST /v1/ground to map screenshots to coordinates.
Pick v3 when you want to orchestrate each prediction step yourself. Pick v4 when you want an autonomous run with a pass/fail verifier. Both give you a real computer use model that can handle the visual world. Get a key at https://coasty.ai/developers and start building.