API Reference

Complete reference for all AI Metal Cluster endpoints.

Authentication

All API requests require authentication using a Bearer token in the Authorization header.

Authorization: Bearer YOUR_API_KEY

Security Note: API keys are issued per-cluster and can be rotated via the admin dashboard. Never expose keys in client-side code.

LLM Queries

POST /query

Request Body

Parameter Type Required Description
prompt string Yes The input prompt
model string No Model ID (default: llama3.2)
max_tokens integer No Maximum response tokens (default: 2048)
temperature float No Sampling temperature 0-2 (default: 0.7)
stream boolean No Enable streaming response (default: false)

Example Request

curl -X POST https://cluster.example.com/query \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Explain machine learning",
    "model": "llama3.2",
    "max_tokens": 500
  }'

Transcription

POST /transcribe

Form Parameters

Parameter Type Required Description
file file Yes Audio file (mp3, wav, m4a, etc.)
language string No ISO language code (auto-detected if omitted)
format string No Output format: text, srt, vtt (default: text)

Example Request

curl -X POST https://cluster.example.com/transcribe \
  -H "Authorization: Bearer sk_live_xxx" \
  -F "[email protected]" \
  -F "language=en" \
  -F "format=srt"

Image Generation

POST /generate-image

Request Body

Parameter Type Required Description
prompt string Yes Image description
width integer No Image width (default: 1024)
height integer No Image height (default: 1024)
steps integer No Inference steps (default: 20)

Animation

POST /animate

Generate video animations from images using SVD, LivePortrait, or D-ID.

Animation endpoints require Professional tier or higher. Contact sales for access.

Browser Automation

Headless browser sessions for web scraping, form automation, and screenshot capture. Sessions run on our GPU cluster via Puppeteer with full Chrome DevTools support.

POST /api/browser/session/create

Launch a new headless browser session. Returns a session ID for subsequent operations.

Request Body

Parameter Type Required Description
viewport_width integer No Browser viewport width (default: 1280)
viewport_height integer No Browser viewport height (default: 720)

Example Request

curl -X POST https://aimetalcluster.com/api/browser/session/create \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "viewport_width": 1920,
    "viewport_height": 1080
  }'

Example Response

{
  "session_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "active",
  "created_at": "2026-02-21T12:00:00Z"
}
POST /api/browser/session/{id}/navigate

Navigate the browser to a URL. Waits for page load before returning.

Request Body

Parameter Type Required Description
url string Yes Target URL to navigate to

Example Request

curl -X POST https://aimetalcluster.com/api/browser/session/a1b2c3d4/navigate \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com"}'
POST /api/browser/session/{id}/input

Type text into a form field identified by CSS selector.

Request Body

Parameter Type Required Description
selector string Yes CSS selector for the input field
text string Yes Text to type into the field

Example Request

curl -X POST https://aimetalcluster.com/api/browser/session/a1b2c3d4/input \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "selector": "#search-input",
    "text": "AI metal cluster GPU pricing"
  }'
POST /api/browser/session/{id}/submit

Click a button or submit a form by CSS selector.

Request Body

Parameter Type Required Description
selector string Yes CSS selector for the button or form element

Example Request

curl -X POST https://aimetalcluster.com/api/browser/session/a1b2c3d4/submit \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"selector": "#search-btn"}'
POST /api/browser/session/{id}/capture

Take a screenshot of the current page. Screenshots are saved to NFS storage and accessible via the screenshots endpoint.

Example Request

curl -X POST https://aimetalcluster.com/api/browser/session/a1b2c3d4/capture \
  -H "Authorization: Bearer sk_live_xxx"

Example Response

{
  "screenshot": "a1b2c3d4/capture-1708523400.png",
  "url": "/api/browser/screenshots/a1b2c3d4/capture-1708523400.png"
}
GET /api/browser/screenshots/{session_id}/{filename}

Retrieve a screenshot PNG by session ID and filename. Returns the image directly with Content-Type: image/png.

GET /api/browser/session/{id}/details

Get session metadata including page navigation history, current URL, and session status.

Example Response

{
  "session_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "active",
  "current_url": "https://example.com/results",
  "history": [
    "https://example.com",
    "https://example.com/results"
  ],
  "screenshots": [
    "capture-1708523400.png"
  ]
}
POST /api/browser/session/{id}/close

Destroy a browser session and release resources. Always close sessions when done to free cluster capacity.

Example Request

curl -X POST https://aimetalcluster.com/api/browser/session/a1b2c3d4/close \
  -H "Authorization: Bearer sk_live_xxx"

Note: Browser sessions are automatically terminated after 10 minutes of inactivity. Sessions run on our central Puppeteer worker with screenshots stored on shared NFS storage across the cluster.

Error Codes

Code Meaning
400 Bad Request - Invalid parameters
401 Unauthorized - Invalid or missing API key
403 Forbidden - IP not whitelisted
429 Rate Limited - Too many requests
500 Internal Error - Server issue
503 Service Unavailable - Model loading