Templates (Compute API)

A template is a saved launch configuration: image, startup command, GPU shape, duration, the storage to create and, for some, the model weights to mount. With an API key you can list your own and the public catalogue, see what one would cost, and launch a GPU instance or cluster from it, exactly as the console's Launch button does.

Prerequisites and the shared rules (auth, rate limits, errors) are on the overview. Read-only Compute access is enough to list and quote; launching needs full Compute access.

Endpoints

Method	Path	What it does
GET	/compute-templates	Your account's templates
GET	/compute-templates/public	The public catalogue. ?target_kind=gpu_instance (or gpu_cluster, model_instance) filters it
GET	/compute-templates/{id}	One template, yours or public
POST	/compute-templates/quote	What launching it would hold, in which region, and whether there is room

Templates are created, edited and published in the console. There are no API calls for that.

Launching from a template

A template is a launch body. To launch one, read it, send its spec as the body of the ordinary create call, and add template_id:

1. GET /compute-templates/{id}. Check template.target_kind:
   • gpu_instance launches with POST /gpu-instances;
   • gpu_cluster launches with POST /gpu-clusters;
   • model_instance launches with POST /inference-instances (Model instances). It picks its own region, so send no region_id.
2. POST /compute-templates/quote with template_id. Note region_id, gpu_type, upfront_hold_usd and capacity_ok.
3. POST /gpu-instances (or /gpu-clusters) with:
   • the fields of spec;
   • region_id and gpu_type from the quote;
   • template_id;
   • anything you want to change, such as name, estimated_duration_hours or ssh_public_key.

template_id on its own does not launch anything. It records which template the launch came from, so a body with only template_id is refused for missing fields. Send the spec's fields with it.

Quick run

KEY="eco_YOUR_KEY"; API="https://api.ecohash.com"; TPL=51

curl -s $API/compute-templates/$TPL -H "Authorization: Bearer $KEY"        # note template.target_kind and spec
curl -s -X POST $API/compute-templates/quote -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" -d "{\"template_id\": $TPL}"

Python

import requests

API, KEY = "https://api.ecohash.com", "eco_YOUR_KEY"
H = {"Authorization": f"Bearer {KEY}"}
TPL = 51

got = requests.get(f"{API}/compute-templates/{TPL}", headers=H).json()
assert got["template"]["target_kind"] == "gpu_instance"
spec = got["spec"]

q = requests.post(f"{API}/compute-templates/quote", headers=H, json={"template_id": TPL}).json()
if not q["capacity_ok"]:
    raise SystemExit(q["warnings"])
print("hold now:", q["upfront_hold_usd"])

inst = requests.post(f"{API}/gpu-instances", headers=H, json={
    **spec,
    "region_id": q["region_id"],
    "gpu_type": q["gpu_type"],
    "template_id": TPL,
    "name": "from-template",
    "ssh_enabled": True,
    "ssh_public_key": open("/home/me/.ssh/id_ed25519.pub").read().strip(),
}).json()
print(inst["id"], inst["status"])  # poll GET /gpu-instances/{id} until running

GET /compute-templates/{id}

{
  "template": {
    "id": 51,
    "name": "deepseek-v4-flash-8gpu-instance",
    "target_kind": "gpu_instance",
    "visibility": "public",
    "readme_md": "…"
  },
  "spec": {
    "gpu_type": "NVIDIA-RTX-PRO-6000-Blackwell-Server-Edition",
    "gpu_count": 8,
    "container_image": "lmsysorg/sglang:dev-dsv4-flash-vision",
    "startup_command": "exec bash /mnt/deepseek/models/…/start-server.sh",
    "service_port": 8000,
    "user_model_id": 51,
    "interruptible": false,
    "ssh_enabled": false
  },
  "quote": { "region_id": "atl", "upfront_hold_usd": 15.12, "capacity_ok": true, "…": "…" },
  "owned": false
}

• spec is the launch body, ready to send. It is the copy you are allowed to see: for a template you don't own, it has no region, SSH keys, volume ids or tokens.
• quote is the same as POST /compute-templates/quote; add ?region=<id>&hours=<n> to price something else.
• owned says whether the template is your account's.
• The list endpoints return templates without the wrapper. Their launch body is spec_json, a JSON string; parse it, or call this endpoint for the parsed spec.
• Public templates carry no region: the quote picks one, or the region of the template's model weights (below).
• ssh_enabled is always false in a public template. Turn SSH on at launch with your own ssh_public_key.
• No estimated_duration_hours means you choose the duration: send 0 for no end time (billed hourly) or 1–72 for a fixed run.
• readme_md is the template's instructions: what it runs, which port, how to reach it.

Templates with model weights

A GPU-instance template can name model weights (user_model_id): a model registered on a shared filesystem, either your own or one another account has published.

• The weights are mounted when the instance starts, at the path the template's startup command uses. Another account's model is mounted read-only, and only that model's directory is visible.
• The weights exist in one region, so the instance launches there:
  • the quote returns that region;
  • a launch in any other region is refused with a message naming the right one.
• A model that is no longer published is refused at launch (400, "not found or not available to this account").
• You pay for the GPUs only. The storage belongs to the publisher.

POST /compute-templates/quote

{ "template_id": 52, "region_id": "atl", "hours": 4 }

region_id and hours are optional and override the spec.

{
  "region_id": "atl",
  "gpu_type": "NVIDIA-RTX-PRO-6000-Blackwell-Server-Edition",
  "lines": [
    { "kind": "gpu", "label": "8 × NVIDIA-RTX-PRO-6000-Blackwell-Server-Edition", "hourly": 15.12, "hold": 15.12 }
  ],
  "upfront_hold_usd": 15.12,
  "recurring_daily_usd": 0,
  "first_day_total_usd": 15.12,
  "capacity_ok": true,
  "warnings": []
}

• upfront_hold_usd is what the launch holds from your credit. recurring_daily_usd is the daily charge for storage the template creates.
• capacity_ok: false means there are not enough free GPUs there now; warnings says why.
• On a reservation, the quote uses your reservation's region. The GPU line reads "in your reservation" at 0, and nothing is held.

Related

• Templates: how templates work in the console
• GPU instances API · GPU clusters API
• Sharing a model
• GPU MCP server: list_templates, quote_template and launch_template do all of the above in one step