# GPU-Bridge
> Unified AI API — 26 services, 47 models, one endpoint

GPU-Bridge is a REST API for AI agents and developers. It provides 26 AI services across text, image, video, audio, and vision — all accessible through a single `POST /run` endpoint. Jobs are automatically routed across multiple GPU backends with failover.

## API Base URL
https://api.gpubridge.xyz

## Authentication

Three payment methods — use any one:

### 1. x402 Protocol (autonomous AI agents)
- No account or API key required
- Pay per request using USDC on Base (Chain ID 8453)
- Send USDC to `0xB0FdC6030B9f30652e8B221B8090d443Dd3C6381` (USDC contract: `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913`)
- Base64-encode a JSON proof and include it as the `X-Payment` header
- Instant on-chain verification, ~$0.001 gas fees

```http
POST /run HTTP/1.1
Host: api.gpubridge.xyz
Content-Type: application/json
X-Payment: eyJ0eEhhc2giOiIweC4uLiIsImZyb20iOiIweC4uLiJ9

{"service":"llm-4090","input":{"prompt":"Hello"}}
```

The `X-Payment` header is a base64-encoded JSON object:
```json
{
  "txHash": "0x<64 hex chars>",
  "from": "0x<your wallet address>"
}
```

**Flow for AI agents:**
1. Call any endpoint without payment → receive HTTP 402 with spec-compliant x402 response
2. Parse `accepts[0].maxAmountRequired` (USDC units, 6 decimals) and `accepts[0].payTo`
3. Send USDC on Base to `payTo` address (amount >= `maxAmountRequired`)
4. Base64-encode `{"txHash":"0x...","from":"0x..."}` and set as `X-Payment` header
5. Retry the same request → payment verified on-chain, job executes

The 402 response follows the x402 spec (https://x402.org):
```json
{
  "x402Version": 1,
  "accepts": [{
    "scheme": "exact",
    "network": "base",
    "maxAmountRequired": "10000",
    "payTo": "0xB0FdC6030B9f30652e8B221B8090d443Dd3C6381",
    "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "maxTimeoutSeconds": 300
  }]
}
```
The `maxAmountRequired` varies per service (e.g. 3000 for LLM, 300000 for video). Response includes header `X-Payment-Version: 1`.

Payment window: 5 minutes from transaction confirmation. Each tx hash can only be used once.

### 2. API Key + Prepaid Credits (developers)
- Register: POST https://api.gpubridge.xyz/account/register (body: {"email":"you@example.com"})
- Top up with card: POST /account/topup with API key (minimum $10, bonus credits on $25/$50/$100)
- Top up with crypto: POST /account/topup-crypto with API key (USDC on Base via NOWPayments, 0.5% fee)
- Auth header: `Authorization: Bearer gpub_your_key`
- Credits never expire. Auto-topup available.
- Volume discounts: 5% at $100+, 10% at $500+, 15% at $1000+
- Daily spending limit: $50/day default, configurable via POST /account/spending-limit

### 3. Crypto Top-Up (humans who prefer crypto)
- Requires an account (register first)
- POST /account/topup-crypto with API key and `{"package":"credits_10"}`
- Returns a USDC payment address on Base
- Send the exact amount; credits are added automatically when payment confirms
- Same credit packages as card: $10, $25 (+5%), $50 (+10%), $100 (+15%)
- Fee: 0.5% (vs 2.9% for card)

## Important: Media URLs
When providing `audio_url` or `image_url`, use direct CDN links (e.g. soundhelix.com for audio, imgbb.com or similar for images). GitHub raw URLs and Wikimedia URLs often return 403/404 from compute nodes. URLs must be publicly accessible without authentication.

## Main Endpoint

### POST /run
Run any service. This is the primary endpoint for all 26 services.

```json
{
  "service": "<service_key>",
  "input": { ... },
  "webhook_url": "https://your-server/callback"
}
```

Returns 202 with job_id. Poll GET /status/{job_id} for results, or receive via webhook.

Headers:
- `Authorization: Bearer gpub_your_key` (required for API key auth; omit when using x402)
- `X-Payment: <base64-proof>` (required for x402 auth; omit when using API key)
- `X-Priority: fast|cheap` (optional — controls backend routing)
- `Idempotency-Key: <unique_id>` (optional — prevents duplicate charges on retry)

## Available Services (26)

### Text & Intelligence
- `llm-4090` — LLM Inference (4 models, sub-second, from $0.003/req)
  Input: `{"prompt":"...","max_tokens":512,"model":"llama-3.3-70b-versatile"}`
  Available models: llama-3.3-70b-versatile, llama-3.1-8b-instant, llama-4-scout, qwen3-32b
- `embedding-l4` — Text Embeddings, 1024-dim vectors ($0.01/req)
  Input: `{"text":"your text here"}` (also accepts `{"text":["text1","text2"]}`)
- `llava-4090` — Visual Q&A, describe/analyze images ($0.05/req)
  Input: `{"image_url":"https://...","prompt":"What is this?"}`
- `caption` — Image Captioning ($0.01/req)
  Input: `{"image_url":"https://..."}`
- `clip` — CLIP Interrogator, image to text prompt ($0.02/req)
  Input: `{"image_url":"https://..."}`

### Image & Video Generation
- `image-4090` — Image Generation, 6 models from $0.003/image
  Input: `{"prompt":"A cat astronaut"}`
  Models: flux-schnell (fast), flux-dev, flux-1.1-pro, sd-3.5-large, sdxl-lightning, playground-v2.5
- `video` — Video Generation from text or image (from $0.30/clip, typical $0.65)
  Input: `{"prompt":"A sunset timelapse","image_url":"https://... (optional)"}`
- `inpaint` — Inpainting/outpainting ($0.04/req)
  Input: `{"image_url":"...","mask_url":"...","prompt":"..."}`
- `controlnet` — Edge/depth-guided generation ($0.05/req)
  Input: `{"image_url":"...","prompt":"..."}`
- `img2img` — Image-to-image style transfer ($0.04/req)
  Input: `{"image_url":"...","prompt":"..."}`
- `image-variation` — Create variations of an image ($0.04/req)
  Input: `{"image_url":"..."}`
- `photomaker` — AI portrait from reference photo ($0.05/req)
  Input: `{"image_url":"...","prompt":"a portrait in watercolor style"}`
- `sticker` — AI sticker maker ($0.02/req)
  Input: `{"image_url":"... (face)","prompt":"..."}`
- `ad-inpaint` — Product advertising image ($0.05/req)
  Input: `{"image_url":"...","prompt":"product on marble table"}`
- `animate` — Animate still images into video ($0.10/req)
  Input: `{"image_url":"...","prompt":"gentle motion"}`

### Audio & Speech
- `whisper-l4` — Speech-to-Text, under 1 second (from $0.05/req)
  Input: `{"audio_url":"https://..."}`
- `whisperx` — STT with speaker diarization ($0.05/req)
  Input: `{"audio_url":"https://..."}`
- `tts-l4` — Text-to-Speech, 40+ voices ($0.02/req)
  Input: `{"text":"Hello world","voice":"af_alloy"}`
- `bark` — Expressive TTS with sound effects ($0.03/req)
  Input: `{"text":"Hello [laughter] how are you?"}`
- `musicgen-l4` — Text-to-music ($0.05/req)
  Input: `{"prompt":"calm piano melody","duration_seconds":10}`
- `voice-clone` — Voice cloning (from $0.10/req, typical $0.65)
  Input: `{"audio_url":"https://... (voice sample)"}`

### Utilities
- `rembg-l4` — Background removal ($0.01/req)
  Input: `{"image_url":"https://..."}`
- `upscale-l4` — Image upscaling 2x/4x ($0.04/req)
  Input: `{"image_url":"https://...","scale":4}`
- `face-restore` — Face restoration/enhancement ($0.02/req)
  Input: `{"image_url":"https://..."}`
- `ocr` — Text extraction from images ($0.01/req)
  Input: `{"image_url":"https://..."}`
- `segmentation` — Object segmentation ($0.02/req)
  Input: `{"image_url":"https://..."}`

## Pricing Model

Prices shown above are typical costs per request. Actual cost depends on the provider and execution time:
- LLM and Whisper: per-token billing, extremely cheap — most requests cost $0.003-0.01
- Image generation: per-output flat rate — e.g. flux-schnell = $0.003/image, flux-dev = $0.025/image
- Audio, video, and utilities: per-second of compute time with a minimum charge of $0.01

To get the exact cost before running a job, use `GET /catalog/estimate?service=<key>`.
The POST /run response also includes `estimated_cost_usd` for every job.
For credit users, excess charges based on time estimates are refunded after the job completes.

## Other Endpoints

- GET /catalog — Full JSON catalog with all services, models, pricing, and input schemas
- GET /catalog/estimate?service=llm-4090&seconds=30 — Cost estimator (no auth required)
  Returns: {"service":"llm-4090","estimated_seconds":25,"price_per_second":0.0024,"estimated_cost_usd":0.06,"note":"..."}
  Use this before POST /run to know what a job will cost. Override `seconds` for custom durations.
- GET /status/{job_id} — Job status and results (no auth required)
- GET /account/balance — Credit balance, daily spend, volume discount tier
- GET /account/jobs — Job history with costs
- POST /account/topup — Create Stripe checkout for credits (card)
- POST /account/topup-crypto — Create USDC payment for credits (crypto, 0.5% fee)
- POST /account/recover — Check if account exists for an email
- POST /account/recover-reset — Generate new API key (invalidates old one)
- POST /account/spending-limit — Set daily spend limit ($1-$10,000)
- POST /account/auto-topup — Configure automatic credit top-up
- POST /account/regenerate-key — Generate new API key (requires current valid key)
- GET /account/dashboard — Web dashboard (balance, top-up, job history)
- GET /health — API health check (JSON)

## Web Pages

- https://gpubridge.xyz — Landing page
- https://gpubridge.xyz/catalog — Visual service catalog (26 services, filterable)
- https://gpubridge.xyz/docs — Full API documentation
- https://gpubridge.xyz/status — System status page (live checks)
- https://api.gpubridge.xyz/account/register — Create account (web form)
- https://api.gpubridge.xyz/account/dashboard — Account dashboard (balance, top-up, jobs)

## Quick Start Example

```bash
# 1. Register
curl -X POST https://api.gpubridge.xyz/account/register \
  -H "Content-Type: application/json" \
  -d '{"email":"you@example.com"}'
# Returns: {"api_key":"gpub_...","topup_url":"..."}

# 2. Generate an image
curl -X POST https://api.gpubridge.xyz/run \
  -H "Authorization: Bearer gpub_your_key" \
  -H "Content-Type: application/json" \
  -d '{"service":"image-4090","input":{"prompt":"A red cube on white"}}'
# Returns: {"job_id":"...","status_url":"/status/..."}

# 3. Get results
curl https://api.gpubridge.xyz/status/{job_id}
# Returns: {"status":"completed","output":{"url":"https://..."}}
```

## x402 Payment Details (for AI agent developers)

- Spec: x402.org (x402Version: 1, accepts[] array with scheme "exact")
- Network: Base (Chain ID 8453)
- Asset: USDC (6 decimals)
- Contract: `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913`
- Recipient: `0xB0FdC6030B9f30652e8B221B8090d443Dd3C6381`
- 402 response: `accepts[0].maxAmountRequired` = price in USDC smallest units (varies per service)
- 402 header: `X-Payment-Version: 1`
- Payment header: `X-Payment: base64({"txHash":"0x...","from":"0x..."})`
- Payment window: 300 seconds (5 minutes)
- Confirmations: 1 (for amounts <= $10), 5 (for amounts > $10)
- Anti-replay: each tx hash can only be used for one job
- OFAC screening: all sender addresses are checked against the Chainalysis Sanctions Oracle
- Discovery: `/.well-known/ai-plugin.json` (public, no auth)

## Company
Healthtech Capital LLC
30 N Gould St Ste R, Sheridan, WY 82801, USA
Website: https://gpubridge.xyz
API: https://api.gpubridge.xyz
Catalog: https://api.gpubridge.xyz/catalog