API Documentation

26 services, 47 models, one endpoint. Base URL: https://api.gpubridge.xyz

Quick Start

From zero to running AI jobs in 3 steps:

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

# 2. Top up credits ($10 minimum)
curl -X POST https://api.gpubridge.xyz/account/topup \
  -H "Authorization: Bearer gpub_your_key" \
  -H "Content-Type: application/json" \
  -d '{"package":"credits_10"}'
# Returns: {"checkout_url":"https://checkout.stripe.com/..."}

# 3. Run a job
curl -X POST https://api.gpubridge.xyz/run \
  -H "Authorization: Bearer gpub_your_key" \
  -H "Content-Type: application/json" \
  -d '{"service":"llm-4090","input":{"prompt":"Hello world"}}'
# Returns: {"job_id":"...","status":"pending","estimated_cost_usd":0.003}

# 4. Get results
curl https://api.gpubridge.xyz/status/{job_id}
# Returns: {"status":"completed","output":{"text":"..."}}
Copy

Authentication

Three payment methods. Use any one per request:

Option A: API Key (developers)

Register, buy credits, authenticate with a Bearer token.

Authorization: Bearer gpub_your_api_key
Copy

Option B: x402 USDC Direct (AI agents)

No account needed. Send USDC on Base, include tx proof. See x402 Protocol for full details.

X-Payment: base64({"txHash":"0x...","from":"0xYourWallet"})
Copy

Option C: Crypto Top-Up (humans preferring crypto)

Register an account, then top up with USDC instead of card. 0.5% fee vs 2.9% for card.

POST /run

Main endpoint for all 26 services. Submit a job, get results via polling or webhook.

Request body

{
  "service": "llm-4090",
  "input": { "prompt": "Explain quantum computing", "max_tokens": 512 },
  "webhook_url": "https://your-server.com/callback"  // optional
}
Copy

Optional headers

Response (202)

{
  "job_id": "a1b2c3d4-...",
  "service": "llm-4090",
  "status": "pending",
  "status_url": "/status/a1b2c3d4-...",
  "estimated_cost_usd": 0.003
}
Copy

GET /status/:job_id

Poll until status is completed or failed. Sync services (LLM, Whisper) complete in the initial response.

{
  "id": "a1b2c3d4-...",
  "status": "completed",
  "output": { "text": "Quantum computing leverages..." },
  "execution_time_seconds": 0.45
}
Copy

GET /catalog

GET /catalog/estimate

{
  "service": "llm-4090",
  "estimated_seconds": 25,
  "price_per_second": 0.0024,
  "estimated_cost_usd": 0.06
}
Copy

GET /account/balance

curl https://api.gpubridge.xyz/account/balance \
  -H "Authorization: Bearer gpub_your_key"
Copy

{
  "balance": 8.50,
  "email": "you@example.com",
  "daily_spend": 1.50,
  "daily_limit": 50,
  "volume_discount": { "tier": "Standard", "discount_percent": 0 }
}
Copy

POST /account/topup

curl -X POST https://api.gpubridge.xyz/account/topup \
  -H "Authorization: Bearer gpub_your_key" \
  -H "Content-Type: application/json" \
  -d '{"package":"credits_25"}'
# Returns: {"checkout_url":"https://checkout.stripe.com/..."}
Copy

POST /account/topup-crypto

curl -X POST https://api.gpubridge.xyz/account/topup-crypto \
  -H "Authorization: Bearer gpub_your_key" \
  -H "Content-Type: application/json" \
  -d '{"package":"credits_10"}'
# Returns payment address — send USDC, credits added automatically
Copy

GET /account/jobs

POST /account/spending-limit

curl -X POST https://api.gpubridge.xyz/account/spending-limit \
  -H "Authorization: Bearer gpub_your_key" \
  -H "Content-Type: application/json" \
  -d '{"daily_limit":100}'
Copy

POST /account/auto-topup

'{"enabled":true,"threshold":1.00,"package":"credits_10"}'
Copy

Key Recovery

curl -X POST https://api.gpubridge.xyz/account/recover-reset \
  -H "Content-Type: application/json" \
  -d '{"email":"you@example.com"}'
# Returns: {"api_key":"gpub_new_key_...", ...}
Copy

Text & Intelligence

Image & Video

Audio & Speech

Utilities

Pricing

• Pay per request, zero cost when idle. No monthly fees.
• LLM / Whisper: per-token billing (cheapest category)
• Image generation: per-output flat rate
• Everything else: per-second of compute time
• Volume discounts: 5% at $100 spent, 10% at $500, 15% at $1,000+
• Refunds: excess charges (based on time estimates) refunded after job completes

Always check cost before running: GET /catalog/estimate?service=llm-4090

x402 Protocol

For AI agent developers building autonomous clients. Spec-compliant with x402.org.

Flow

1. Call any endpoint without auth → receive HTTP 402
2. Parse accepts[0].maxAmountRequired (USDC units) and accepts[0].payTo
3. Send USDC on Base to payTo (amount ≥ maxAmountRequired)
4. Base64-encode {"txHash":"0x...","from":"0x..."} as X-Payment header
5. Retry the same request → job executes

402 response format

{
  "x402Version": 1,
  "accepts": [{
    "scheme": "exact",
    "network": "base",
    "maxAmountRequired": "10000",  // varies per service
    "payTo": "0xB0FdC6030B9f30652e8B221B8090d443Dd3C6381",
    "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "maxTimeoutSeconds": 300
  }]
}
Copy

Important Notes

• Media URLs must be publicly accessible. Use CDN links (soundhelix.com, imgbb.com). GitHub raw and Wikimedia URLs often return 403 from compute nodes.
• Webhooks are delivered via POST with 3 retries and exponential backoff. URL must be HTTPS and not point to private networks.
• Job results are available for 24 hours after completion.
• Rate limits: 30 requests/minute per API key, 20 requests/second per IP via nginx.
• Failover: if a backend fails, requests automatically retry on the next available. Failed jobs are fully refunded.