# GPUs Market API — Complete Reference

> The peer-to-peer GPU marketplace for AI. Rent real hosts (Apple Silicon Macs and
> NVIDIA GPUs) to run LLMs, generate images, synthesise and transcribe audio, and
> generate video — all over OpenAI-compatible APIs, billed per second or per unit.
> Or host your own Mac/GPU and earn a 90% revenue share. Agents are first-class.

## What you can run here (workload types)
GPUs Market is NOT LLM-only. Every listing has a workloadType and hosts serve a
matching OpenAI-compatible contract:
- llm    — LLM inference via Ollama / OpenAI Chat API (chatbots, RAG, agents).
- image  — AI image generation (SDXL / Flux) via the OpenAI Images API. Billed per image.
- audio  — Text-to-speech (Kokoro) + speech-to-text (Whisper) via the OpenAI Audio API.
           Tiny models — runs well even on an Apple Silicon Mac. Billed per 1k chars / audio-second.
- video  — Text-to-video (Wan2.1) via an async OpenAI-compatible contract. Billed per video.
Filter the marketplace by type, e.g. GET /api/v1/marketplace/search?type=image

## Consumer app — GPUs Market Create
A macOS (Apple Silicon) desktop app to make AI images, voices and video without any
setup — the machinery is hidden. Free to start; an optional subscription unlocks more.
Hosting your own Mac feeds the same network. See https://gpusmarket.com/donate

## Quick Start
Sign up and get a gpu_ token in one call:
  POST https://gpusmarket.com/api/signup
  Body: {"email":"you@company.com","tenantId":"my-agent","role":"renter"}
  Returns: {"apiKey":"gpu_...","tenantId":"my-agent","accountEmail":"..."}

Recover a lost token:
  POST https://gpusmarket.com/api/signup/recover
  Body: {"email":"you@company.com"}

## Authentication
Two token types:
- Account token (gpu_ prefix): used for browsing, renting, deploying, stopping, managing rentals
  Header: Authorization: Bearer gpu_your_token
- Per-rental token (hex, no prefix): used for Ollama proxy access on a specific rental
  Header: Authorization: Bearer a1b2c3d4e5f6...

## Public Endpoints (No Auth)

GET /api/v1/marketplace/search
  Search available GPU listings.
  Params: gpu, maxPrice, minVram, ollamaModel, instanceType, type (workloadType: llm|image|audio|video), pricingTier, sort, limit, offset
  Example (LLM): GET /api/v1/marketplace/search?gpu=RTX%204090&maxPrice=1.00&instanceType=ollama
  Example (image): GET /api/v1/marketplace/search?type=image
  Example (audio, Mac-friendly): GET /api/v1/marketplace/search?type=audio

GET /api/v1/marketplace/gpu-models
  GPU catalogue summary — all models with VRAM, tier, availability, price range.

GET /api/v1/marketplace/listings/:id
  Single listing detail with health status.

GET /api/v1/gpu/types
  All GPU types with live pricing. Returns pricePerHour, vramGb per type.

GET /api/v1/gpu/cheapest?vram=24
  Find cheapest GPU meeting a VRAM requirement.

## Authenticated Endpoints (Bearer gpu_ token)

### Marketplace — Peer-to-Peer Rentals

POST /api/v1/marketplace/rent/:listingId
  Rent a peer-hosted GPU. Returns rentalId + per-rental proxy token.

POST /api/v1/marketplace/rentals/:id/stop
  Stop rental. Per-second billing stops immediately. Returns cost summary.

GET /api/v1/marketplace/rentals
  List your rentals. Param: status=active|completed

GET /api/v1/marketplace/rentals/:id
  Rental detail + usage stats (requests, tokens, cost).

### GPU Cloud — On-Demand Instances

POST /api/v1/gpu/deploy
  Deploy cloud GPU instance (~30s provision).
  Body: {"gpuType":"RTX 4090","models":["llama3.3"],"instanceType":"ollama"}
  instanceType: "ollama" (default) | "docker" | "ssh"

GET /api/v1/gpu/pods
  List your active cloud GPU instances.

GET /api/v1/gpu/pods/:id
  Instance status + live billing.

PUT /api/v1/gpu/pods/:id/stop
  Pause instance. Billing pauses, volume kept.

PUT /api/v1/gpu/pods/:id/resume
  Resume paused instance.

DELETE /api/v1/gpu/pods/:id
  Destroy instance permanently. Returns final cost.

## Ollama Proxy (Per-Rental Token)

Base: https://gpusmarket.com/api/v1/ollama/:rentalId
Auth: Authorization: Bearer {per_rental_token}

POST /api/chat — Chat completion (multi-turn)
POST /api/generate — Single-turn generation
GET /api/tags — List models available on this GPU
POST /api/embeddings — Generate embeddings

Streaming: set "stream": true in request body. Response uses chunked transfer encoding.

## OpenAI-Compatible Proxy (Per-Rental Token)

Base: https://gpusmarket.com/api/v1/openai/:rentalId
Auth: Authorization: Bearer {per_rental_token}

POST /v1/chat/completions — Chat completion (OpenAI format)
POST /v1/completions — Text completion
GET /v1/models — List available models
POST /v1/embeddings — Generate embeddings

Streaming: set "stream": true. Response uses Server-Sent Events (SSE).

Both proxy formats (/api/v1/ollama and /api/v1/openai) work with any host backend.
The proxy auto-translates between Ollama and OpenAI formats as needed.
Hosts can run Ollama or llama-server (llama.cpp) — renters use whichever format they prefer.

## Image / Audio / Video Endpoints (Per-Rental Token)

Same base + auth as the OpenAI proxy: https://gpusmarket.com/api/v1/openai/:rentalId
Available on listings whose workloadType is image, audio, or video respectively.

Image generation (workloadType: image):
  POST /v1/images/generations — OpenAI Images API. Body: {"model":"sdxl-turbo","prompt":"...","n":1}
    Returns b64_json image(s). Billed per image (n).

Audio (workloadType: audio):
  POST /v1/audio/speech — text-to-speech (Kokoro). Body: {"model":"kokoro","input":"...","voice":"af_heart"}
    Returns audio bytes. Billed per 1,000 characters.
  POST /v1/audio/transcriptions — speech-to-text (Whisper). Multipart file upload.
    Returns transcript text. Billed per audio-second.

Video generation (workloadType: video, async):
  POST /v1/videos/generations — start a job. Body: {"model":"wan2.1-t2v","prompt":"..."}
    Returns a job id. Billed per video on creation.
  GET  /v1/videos/generations/:jobId — poll for status; returns the video URL/bytes when ready.

GET /v1/models on any listing lists what that host actually serves.

## GPU Pools (Load-Balanced Multi-GPU)

Base: https://gpusmarket.com/api/v1/openai/pool
Auth: Authorization: Bearer pool_{key}

Combine multiple rented GPUs into one load-balanced endpoint.
Requests are distributed across all active rentals in the pool.

POST /v1/chat/completions — Routed to next GPU in pool (round-robin)
POST /v1/completions — Same routing
GET /v1/models — Aggregate models from all pool GPUs
POST /v1/embeddings — Same routing

Strategies: round-robin (default), least-loaded, model-match, random.
Failover: if a host is offline, the pool routes to the next active GPU.
Pool keys start with pool_ prefix. Create pools at /renter/pools.

Works with any OpenAI-compatible client (Python openai SDK, Cursor, Cline, Aider).

## Relay Tunnel (Alternative Route)

Base: https://relay.gpusmarket.com/proxy/:rentalId
Auth: same per-rental token

POST /v1/chat/completions — OpenAI-compatible chat endpoint
GET /health — Relay server health
GET /tunnel/status — Active tunnel count
GET /tunnel/status/:listingId — Specific tunnel status

The relay tunnel is for hosts behind NAT/firewalls. From the client perspective, it works identically to the main proxy.

## Agentic Memory (Optional)

POST /renter/memory/connect
  Auth: Bearer gpu_ token
  Body: {"rentalId":"...","amKey":"amk_your_key"}
  Effect: proxy automatically injects last 20 messages as context on every request.
  Get a key at https://agenticmemory.ai

## Billing

Per-second billing on all rentals. Prices displayed as $/hr but charged per second.

Payment flow: renting places a temporary authorization hold on the saved card —
$10 by default, renter-selectable ($10/$25/$50/$100) for long runs (no money
taken). On stop, the card is charged the exact session cost (minimum $0.50) and
the hold is released in full. Wallet credit is applied before the card. If usage
approaches the hold mid-session, the renter is emailed at 75% and at 90% the
accrued cost is charged automatically so the rental continues uninterrupted.

Pricing tiers:
- On-Demand: listed price, cannot be preempted

Billing models (set by host):
- Hourly: flat rate per second of usage
- Hybrid: base rate + per-request + per-token
- Usage: per-request + per-token only (no base)

Per-unit metering for generation workloads (independent of time):
- image: per image generated (n in the request body)
- audio: per 1,000 characters (TTS) / per audio-second (STT)
- video: per video, charged on job creation

## Rate Limits
- 60 requests/minute per rental (sliding window)
- Exceeds limit: 429 Too Many Requests
- Self-signup: 10 requests/hour per IP

## Instance Types
- ollama: Drop-in Ollama API endpoint. Best for LLM inference, chatbots, RAG.
- docker: Docker container with SSH + Jupyter. Best for training, fine-tuning.
- ssh: Full shell access. Best for research, custom setups, multi-GPU.
Note: image/audio/video hosts serve their OpenAI-compatible contract directly (or over
the tunnel); renters just call the endpoints above — no shell needed.

## Hosting (earn from your Mac or GPU)
Any Apple Silicon Mac or NVIDIA GPU (e.g. RTX 3090/4090) can host with one command and
earn a 90% revenue share. Audio (Kokoro TTS + Whisper STT) is the lowest-barrier wedge —
it runs on any Mac. Image needs a 24GB card; video needs a 24GB+ CUDA card. No shell
access is exposed to renters. Start at https://gpusmarket.com/host/mac or /guide/host

## Error Codes
- 400: Invalid request (bad listingId, rental not available)
- 401: Missing or invalid token
- 429: Rate limit exceeded
- 502: Host offline or tunnel disconnected
- 504: Request timeout (120s)

## Key Distinctions
- Peer vs Cloud: Peer GPUs are hosted by individuals (marketplace). Cloud GPUs are provisioned on-demand via GPUs Market.
- gpu_ token vs rental token: gpu_ is your account credential. Rental token is per-rental, returned when you rent.
- Proxy vs Relay: same API, different route. Relay is for NAT-blocked hosts. Client doesn't need to care which.

## Agent Config Files
- Claude Code: CLAUDE.md
- Cursor: .cursorrules
- Cline: .clinerules
- Windsurf: .windsurfrules
- Aider: CONVENTIONS.md (run with --read flag)
- Codex: AGENTS.md (auto-read)

Quick start guides: https://gpusmarket.com/docs/quickstart
Full developer docs: https://gpusmarket.com/docs

## About
GPUs Market is a division of Tyga.Cloud Ltd.
Website: https://gpusmarket.com
Relay: https://relay.gpusmarket.com
Support: https://gpusmarket.com (chat widget)