# GPU machines

`GET | POST /v1/gpu/machines` — Rent a cloud computer with a GPU and Blender, billed by the second, driven task by task.

- Base URL: https://eroq.ai/v1
- Auth: `Authorization: Bearer eroq_sk_…` (create keys at https://eroq.ai/dashboard/keys)
- Credits: RTX 5090 292, L40S 460, RTX PRO 6000 1136, H100 1853, B300 3794 credits per hour, billed by the second

A **GPU machine** is a cloud computer prepared with Blender 5.2 (Cycles on the GPU through OptiX). You never get a shell: you send it **tasks** and get files back. `GET /v1/gpu/types` lists the GPUs with their price per hour, `POST /v1/gpu/machines` launches one (1–3 minutes to come up; tasks sent meanwhile wait for it).

**Tasks.** `script` runs your Blender Python (bpy) on the machine's scene, which persists from one task to the next, then renders a preview (only bpy, bmesh, mathutils, math and a few pure modules import; no file, network or OS access). `render` renders a .blend (or a .zip holding one) given by `file` — a frame (`"12"`) or a range (`"1-120"`, back as an MP4). `turntable` puts a 3D model (`model`: glb, gltf, fbx, obj, stl, ply, usd) on a studio backdrop and turns the camera around it. `export` sends the scene back as .blend, .glb, .fbx, .obj or .usd (in a .zip). Files are signed links, kept 7 days after the machine stops. To send your own file, `POST /v1/gpu/machines/{id}/files` returns a presigned `put` URL and the `url` to pass as `file` or `model`.

**Billing.** By the second, from launch until the machine stops: five minutes are taken at launch and topped up while it runs, the unused part comes back at the stop. It stops by itself after `idle_minutes` without a task (5–60, default 15), at `max_hours` (0.25–24, default 4) or when the balance runs out. Paid plans only (Hobby and up); two machines per workspace.

## Operations

| Method | Path | What it does |
| --- | --- | --- |
| `GET` | `/v1/gpu/types` | The GPUs, their price per hour, the task kinds and the one-click recipes. No key needed. |
| `POST` | `/v1/gpu/machines` | Launch a machine: takes its first five minutes, returns it `starting`. |
| `GET` | `/v1/gpu/machines` | Your machines, newest first (`?open=1`: the running ones). |
| `GET` | `/v1/gpu/machines/{id}` | One machine, its meter and its tasks. |
| `POST` | `/v1/gpu/machines/{id}/runs` | Send a task (202): it runs as soon as the machine is free. |
| `GET` | `/v1/gpu/machines/{id}/runs/{run}` | A task, its log, what Blender saw and its files. |
| `POST` | `/v1/gpu/machines/{id}/runs/{run}/cancel` | Cancel a waiting or running task. |
| `POST` | `/v1/gpu/machines/{id}/files` | A presigned upload for a file the machine will use (.blend, .zip, 3D model, up to 5 GB). |
| `POST` | `/v1/gpu/machines/{id}/stop` | Stop the machine: billed to the second, the rest goes back. |

## GET /v1/gpu/types

The GPUs, their price per hour, the task kinds and the one-click recipes. No key needed.

### Example request

```bash
curl https://eroq.ai/v1/gpu/types \
  -H "Authorization: Bearer $EROQ_API_KEY"
```

```javascript
const res = await fetch('https://eroq.ai/v1/gpu/types', {
  headers: { Authorization: `Bearer ${process.env.EROQ_API_KEY}` },
})
console.log(await res.json())
```

```python
import os, requests

res = requests.get("https://eroq.ai/v1/gpu/types", headers={"Authorization": f"Bearer {os.environ['EROQ_API_KEY']}"})
print(res.json())
```

```go
package main

import (
	"fmt"
	"io"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("GET", "https://eroq.ai/v1/gpu/types", nil)
	req.Header.Set("Authorization", "Bearer "+os.Getenv("EROQ_API_KEY"))

	res, _ := http.DefaultClient.Do(req)
	defer res.Body.Close()
	out, _ := io.ReadAll(res.Body)
	fmt.Println(string(out))
}
```

### Response


```json
{
"object": "list",
"data": [{ "id": "l40s", "name": "L40S", "vram_gb": 48, "credits_per_hour": 460, "credits_at_launch": 39, "best_for": "Heavy scenes that need 48 GB" }],
"software": [{ "id": "blender", "name": "Blender", "version": "5.2" }]
}
```

## POST /v1/gpu/machines

Launch a machine: takes its first five minutes, returns it `starting`.

### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `gpu` | string | yes | A GPU id from GET /v1/gpu/types. |
| `idle_minutes` | number | no | Stop after this long without a task (5–60, default 15). |
| `max_hours` | number | no | Never run longer than this (0.25–24, default 4). |
| `recipe` | string | no | The one-click recipe it is for (informational). |

### Example request

```bash
curl https://eroq.ai/v1/gpu/machines \
  -H "Authorization: Bearer $EROQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "gpu": "l40s",
  "idle_minutes": 15,
  "max_hours": 4
}'
```

```javascript
const res = await fetch('https://eroq.ai/v1/gpu/machines', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.EROQ_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "gpu": "l40s",
    "idle_minutes": 15,
    "max_hours": 4
  }),
})
console.log(await res.json())
```

```python
import os, requests

res = requests.post(
    "https://eroq.ai/v1/gpu/machines",
    headers={"Authorization": f"Bearer {os.environ['EROQ_API_KEY']}"},
    json={
        "gpu": "l40s",
        "idle_minutes": 15,
        "max_hours": 4
    },
)
print(res.json())
```

```go
package main

import (
	"fmt"
	"io"
	"net/http"
	"os"
	"strings"
)

func main() {
	body := strings.NewReader(`{
  "gpu": "l40s",
  "idle_minutes": 15,
  "max_hours": 4
}`)

	req, _ := http.NewRequest("POST", "https://eroq.ai/v1/gpu/machines", body)
	req.Header.Set("Authorization", "Bearer "+os.Getenv("EROQ_API_KEY"))
	req.Header.Set("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)
	defer res.Body.Close()
	out, _ := io.ReadAll(res.Body)
	fmt.Println(string(out))
}
```

### Response


```json
{ "id": "gpu_150619b208e436e1", "object": "gpu.machine", "status": "starting", "gpu": { "id": "l40s", "name": "L40S", "vram_gb": 48 }, "credits_per_hour": 460, "credits_prepaid": 39, "seconds": 0 }
```

## GET /v1/gpu/machines

Your machines, newest first (`?open=1`: the running ones).

### Example request

```bash
curl https://eroq.ai/v1/gpu/machines \
  -H "Authorization: Bearer $EROQ_API_KEY"
```

```javascript
const res = await fetch('https://eroq.ai/v1/gpu/machines', {
  headers: { Authorization: `Bearer ${process.env.EROQ_API_KEY}` },
})
console.log(await res.json())
```

```python
import os, requests

res = requests.get("https://eroq.ai/v1/gpu/machines", headers={"Authorization": f"Bearer {os.environ['EROQ_API_KEY']}"})
print(res.json())
```

```go
package main

import (
	"fmt"
	"io"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("GET", "https://eroq.ai/v1/gpu/machines", nil)
	req.Header.Set("Authorization", "Bearer "+os.Getenv("EROQ_API_KEY"))

	res, _ := http.DefaultClient.Do(req)
	defer res.Body.Close()
	out, _ := io.ReadAll(res.Body)
	fmt.Println(string(out))
}
```

### Response


```json
{ "object": "list", "data": [{ "id": "gpu_150619b208e436e1", "status": "ready", "seconds": 204, "credits_spent": 27 }] }
```

## GET /v1/gpu/machines/{id}

One machine, its meter and its tasks.

### Example request

```bash
curl https://eroq.ai/v1/gpu/machines/MACHINE_ID \
  -H "Authorization: Bearer $EROQ_API_KEY"
```

```javascript
const res = await fetch('https://eroq.ai/v1/gpu/machines/MACHINE_ID', {
  headers: { Authorization: `Bearer ${process.env.EROQ_API_KEY}` },
})
console.log(await res.json())
```

```python
import os, requests

res = requests.get("https://eroq.ai/v1/gpu/machines/MACHINE_ID", headers={"Authorization": f"Bearer {os.environ['EROQ_API_KEY']}"})
print(res.json())
```

```go
package main

import (
	"fmt"
	"io"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("GET", "https://eroq.ai/v1/gpu/machines/MACHINE_ID", nil)
	req.Header.Set("Authorization", "Bearer "+os.Getenv("EROQ_API_KEY"))

	res, _ := http.DefaultClient.Do(req)
	defer res.Body.Close()
	out, _ := io.ReadAll(res.Body)
	fmt.Println(string(out))
}
```

### Response


```json
{ "id": "gpu_150619b208e436e1", "object": "gpu.machine", "status": "ready", "blender": "5.2.4", "device": { "name": "NVIDIA L40S", "util": 97 }, "seconds": 204, "credits_spent": 27, "runs": [] }
```

## POST /v1/gpu/machines/{id}/runs

Send a task (202): it runs as soon as the machine is free.

### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `kind` | string | yes | `script`, `render`, `turntable` or `export`. |
| `code` | string | no | script: Blender Python (bpy). |
| `file` | string | no | render (or script, to open first): https URL of a .blend or a .zip holding one. |
| `model` | string | no | turntable: https URL of a glb, gltf, fbx, obj, stl, ply or usd model. |
| `frames` | string | no | A frame ("12") or a range ("1-120", back as an MP4). |
| `engine` | string | no | `cycles` (default) or `eevee`. |
| `samples` | integer | no | Cycles samples. |
| `width` | integer | no | Render width in pixels (with height). |
| `height` | integer | no | Render height in pixels. |
| `format` | string | no | export: blend, glb, fbx, obj, usd; render: mp4 (default) or png frames. |
| `timeout_minutes` | number | no | Stop the task after this long (1–180). |

### Example request

```bash
curl https://eroq.ai/v1/gpu/machines/MACHINE_ID/runs \
  -H "Authorization: Bearer $EROQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "kind": "script",
  "code": "import bpy\nbpy.ops.mesh.primitive_monkey_add(size=2)\n"
}'
```

```javascript
const res = await fetch('https://eroq.ai/v1/gpu/machines/MACHINE_ID/runs', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.EROQ_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "kind": "script",
    "code": "import bpy\nbpy.ops.mesh.primitive_monkey_add(size=2)\n"
  }),
})
console.log(await res.json())
```

```python
import os, requests

res = requests.post(
    "https://eroq.ai/v1/gpu/machines/MACHINE_ID/runs",
    headers={"Authorization": f"Bearer {os.environ['EROQ_API_KEY']}"},
    json={
        "kind": "script",
        "code": "import bpy\nbpy.ops.mesh.primitive_monkey_add(size=2)\n"
    },
)
print(res.json())
```

```go
package main

import (
	"fmt"
	"io"
	"net/http"
	"os"
	"strings"
)

func main() {
	body := strings.NewReader(`{
  "kind": "script",
  "code": "import bpy\nbpy.ops.mesh.primitive_monkey_add(size=2)\n"
}`)

	req, _ := http.NewRequest("POST", "https://eroq.ai/v1/gpu/machines/MACHINE_ID/runs", body)
	req.Header.Set("Authorization", "Bearer "+os.Getenv("EROQ_API_KEY"))
	req.Header.Set("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)
	defer res.Body.Close()
	out, _ := io.ReadAll(res.Body)
	fmt.Println(string(out))
}
```

### Response


```json
{ "id": "run_efc85d997a9ab677", "object": "gpu.run", "kind": "script", "status": "queued", "progress": 0, "outputs": [] }
```

## GET /v1/gpu/machines/{id}/runs/{run}

A task, its log, what Blender saw and its files.

### Example request

```bash
curl https://eroq.ai/v1/gpu/machines/MACHINE_ID/runs/{run} \
  -H "Authorization: Bearer $EROQ_API_KEY"
```

```javascript
const res = await fetch('https://eroq.ai/v1/gpu/machines/MACHINE_ID/runs/{run}', {
  headers: { Authorization: `Bearer ${process.env.EROQ_API_KEY}` },
})
console.log(await res.json())
```

```python
import os, requests

res = requests.get("https://eroq.ai/v1/gpu/machines/MACHINE_ID/runs/{run}", headers={"Authorization": f"Bearer {os.environ['EROQ_API_KEY']}"})
print(res.json())
```

```go
package main

import (
	"fmt"
	"io"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("GET", "https://eroq.ai/v1/gpu/machines/MACHINE_ID/runs/{run}", nil)
	req.Header.Set("Authorization", "Bearer "+os.Getenv("EROQ_API_KEY"))

	res, _ := http.DefaultClient.Do(req)
	defer res.Body.Close()
	out, _ := io.ReadAll(res.Body)
	fmt.Println(string(out))
}
```

### Response


```json
{ "id": "run_efc85d997a9ab677", "object": "gpu.run", "status": "succeeded", "result": { "backend": "optix", "scene": { "object_count": 4 } }, "outputs": [{ "name": "preview.png", "bytes": 172161, "url": "https://cdn.eroq.ai/…" }] }
```

## POST /v1/gpu/machines/{id}/runs/{run}/cancel

Cancel a waiting or running task.

### Example request

```bash
curl -X POST https://eroq.ai/v1/gpu/machines/MACHINE_ID/runs/{run}/cancel \
  -H "Authorization: Bearer $EROQ_API_KEY"
```

```javascript
const res = await fetch('https://eroq.ai/v1/gpu/machines/MACHINE_ID/runs/{run}/cancel', {
  method: 'POST',
  headers: { Authorization: `Bearer ${process.env.EROQ_API_KEY}` },
})
console.log(await res.json())
```

```python
import os, requests

res = requests.post("https://eroq.ai/v1/gpu/machines/MACHINE_ID/runs/{run}/cancel", headers={"Authorization": f"Bearer {os.environ['EROQ_API_KEY']}"})
print(res.json())
```

```go
package main

import (
	"fmt"
	"io"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("POST", "https://eroq.ai/v1/gpu/machines/MACHINE_ID/runs/{run}/cancel", nil)
	req.Header.Set("Authorization", "Bearer "+os.Getenv("EROQ_API_KEY"))

	res, _ := http.DefaultClient.Do(req)
	defer res.Body.Close()
	out, _ := io.ReadAll(res.Body)
	fmt.Println(string(out))
}
```

### Response


```json
{ "id": "run_efc85d997a9ab677", "status": "canceled" }
```

## POST /v1/gpu/machines/{id}/files

A presigned upload for a file the machine will use (.blend, .zip, 3D model, up to 5 GB).

### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | yes | The file name, its extension included. |
| `bytes` | integer | yes | Its size. |

### Example request

```bash
curl https://eroq.ai/v1/gpu/machines/MACHINE_ID/files \
  -H "Authorization: Bearer $EROQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "scene.blend",
  "bytes": 48211200
}'
```

```javascript
const res = await fetch('https://eroq.ai/v1/gpu/machines/MACHINE_ID/files', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.EROQ_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "name": "scene.blend",
    "bytes": 48211200
  }),
})
console.log(await res.json())
```

```python
import os, requests

res = requests.post(
    "https://eroq.ai/v1/gpu/machines/MACHINE_ID/files",
    headers={"Authorization": f"Bearer {os.environ['EROQ_API_KEY']}"},
    json={
        "name": "scene.blend",
        "bytes": 48211200
    },
)
print(res.json())
```

```go
package main

import (
	"fmt"
	"io"
	"net/http"
	"os"
	"strings"
)

func main() {
	body := strings.NewReader(`{
  "name": "scene.blend",
  "bytes": 48211200
}`)

	req, _ := http.NewRequest("POST", "https://eroq.ai/v1/gpu/machines/MACHINE_ID/files", body)
	req.Header.Set("Authorization", "Bearer "+os.Getenv("EROQ_API_KEY"))
	req.Header.Set("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)
	defer res.Body.Close()
	out, _ := io.ReadAll(res.Body)
	fmt.Println(string(out))
}
```

### Response


```json
{ "name": "scene.blend", "put": "https://…(PUT the bytes here)", "url": "https://cdn.eroq.ai/…(pass as file)" }
```

## POST /v1/gpu/machines/{id}/stop

Stop the machine: billed to the second, the rest goes back.

### Example request

```bash
curl -X POST https://eroq.ai/v1/gpu/machines/MACHINE_ID/stop \
  -H "Authorization: Bearer $EROQ_API_KEY"
```

```javascript
const res = await fetch('https://eroq.ai/v1/gpu/machines/MACHINE_ID/stop', {
  method: 'POST',
  headers: { Authorization: `Bearer ${process.env.EROQ_API_KEY}` },
})
console.log(await res.json())
```

```python
import os, requests

res = requests.post("https://eroq.ai/v1/gpu/machines/MACHINE_ID/stop", headers={"Authorization": f"Bearer {os.environ['EROQ_API_KEY']}"})
print(res.json())
```

```go
package main

import (
	"fmt"
	"io"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("POST", "https://eroq.ai/v1/gpu/machines/MACHINE_ID/stop", nil)
	req.Header.Set("Authorization", "Bearer "+os.Getenv("EROQ_API_KEY"))

	res, _ := http.DefaultClient.Do(req)
	defer res.Body.Close()
	out, _ := io.ReadAll(res.Body)
	fmt.Println(string(out))
}
```

### Response


```json
{ "id": "gpu_150619b208e436e1", "status": "stopped", "seconds": 204, "credits_spent": 27, "credits_prepaid": 78, "stop_reason": "user" }
```

---
Canonical: https://eroq.ai/docs/gpu · Index for agents: https://eroq.ai/llms.txt · OpenAPI: https://eroq.ai/openapi.json
