# PayPerQ (PPQ) API

> PayPerQ is a unified AI API gateway with 500+ models including Chat, Image, Video, STT, TTS, and more from all major providers. OpenAI-compatible endpoints, pay-per-use pricing (no subscriptions), and cryptocurrency payment support for Bitcoin, Bitcoin lightning, USDT, USDC, XMR, LTC, and any other cryptocurrency.

PayPerQ provides a single API that gives you access to models from OpenAI, Anthropic, Google, xAI, Mistral, Meta, Deepseek, Qwen, and more — all through an OpenAI-compatible interface. You pay only for what you use with no minimum spend or monthly commitment. Top up your balance with crypto (Bitcoin Lightning, BTC, Monero, Litecoin, Liquid BTC), Nostr Wallet Connect (NWC) auto-topup, or a credit or debit card via Stripe.

The API works with any tool that supports the OpenAI API format: Claude Code, OpenCode, Cursor, Cline, Aider, Roo, OpenWebUI, Goose, and thousands more.

## API Basics

- **Chat API Base URL**: `https://api.ppq.ai`
- **Audio API Base URL**: `https://ppq.ai/api/v1`
- **Authentication**: `Authorization: Bearer YOUR_API_KEY` (keys are prefixed with `sk-`)
- **Schema**: OpenAI-compatible — use the OpenAI SDK with a custom `base_url`
- **Streaming**: Supported via SSE (Server-Sent Events)

To get an API key, sign up at https://ppq.ai and visit https://ppq.ai/api-docs to generate one.

### Quickstart (Python)

```python
import requests

api_key = "sk-YOUR_API_KEY"
url = "https://api.ppq.ai/v1/chat/completions"

headers = {
    "Content-Type": "application/json",
    "Authorization": f"Bearer {api_key}"
}

data = {
    "model": "claude-sonnet-4-5",
    "messages": [{"role": "user", "content": "Hello, how are you?"}]
}

response = requests.post(url, json=data, headers=headers)
print(response.json())
```

### Quickstart (cURL)

```bash
curl https://api.ppq.ai/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-YOUR_API_KEY" \
  -d '{
    "model": "claude-sonnet-4-5",
    "messages": [{"role": "user", "content": "Hello, how are you?"}]
  }'
```

### Using the OpenAI SDK

```python
from openai import OpenAI

client = OpenAI(
    api_key="sk-YOUR_API_KEY",
    base_url="https://api.ppq.ai/v1"
)

response = client.chat.completions.create(
    model="claude-sonnet-4-5",
    messages=[{"role": "user", "content": "Hello!"}]
)

print(response.choices[0].message.content)
```

## Endpoints

### Chat Completions
- `POST https://api.ppq.ai/v1/chat/completions` — Send messages to any supported LLM
- `POST https://api.ppq.ai/chat/completions` — Alias (same behavior, without `/v1` prefix)

### Online Mode (Web Search)
Any model can search the web in real time by including a `plugins` array in the request:

```bash
curl -X POST https://api.ppq.ai/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-YOUR_API_KEY" \
  -d '{
    "model": "claude-sonnet-4-5",
    "plugins": [{"id": "web", "max_results": 5}],
    "messages": [{"role": "user", "content": "What is the weather in Omaha, Nebraska right now?"}]
  }'
```

- **Plugin parameters**: `id` (required, use `"web"`) and `max_results` (number of web results to retrieve and inject into context, default: 5)
- **Search providers**: Models from Perplexity, OpenAI (GPT-5+), and Anthropic (Claude) use their provider's native web search. All other models use Exa.AI ($0.02/request, in addition to token costs).

### Models
- `GET https://api.ppq.ai/v1/models` — List all available models with pricing info

### Speech-to-Text (STT)
- `POST https://ppq.ai/api/v1/audio/transcriptions` — Transcribe audio to text
- Powered by Deepgram Nova-3
- Supported formats: mp3, mp4, mpeg, mpga, m4a, wav, webm (max 25MB)
- Models: `nova-3` (default), `nova-2`
- Response formats: json, text, srt, vtt, verbose_json
- Parameters: `file` (required), `model`, `response_format`, `language` (e.g. "en", "es", "multi" for auto-detect), `prompt`

```python
from openai import OpenAI

client = OpenAI(api_key="sk-YOUR_API_KEY", base_url="https://ppq.ai/api/v1")

with open("audio.mp3", "rb") as f:
    transcription = client.audio.transcriptions.create(
        model="nova-3",
        file=f,
        response_format="json"
    )
print(transcription.text)
```

### Text-to-Speech (TTS)
- `POST https://ppq.ai/api/v1/audio/speech` — Convert text to speech
- Powered by DeepGram Aura
- Default model: `deepgram_aura_2`
- Max input: 2000 characters
- Parameters: `input` (required), `model`, `voice`
- Available voices:
  - `aura-2-arcas-en` — Natural, Smooth, Clear
  - `aura-2-thalia-en` — Clear, Confident, Energetic
  - `aura-2-andromeda-en` — Casual, Expressive
  - `aura-2-helena-en` — Caring, Natural, Friendly
  - `aura-2-apollo-en` — Confident, Comfortable
  - `aura-2-aries-en` — Warm, Energetic, Caring

```python
from openai import OpenAI

client = OpenAI(api_key="sk-YOUR_API_KEY", base_url="https://ppq.ai/api/v1")

response = client.audio.speech.create(
    model="deepgram_aura_2",
    voice="aura-2-arcas-en",
    input="Hello, welcome to PayPerQ!"
)
response.stream_to_file("output.mp3")
```

## Models

PPQ offers 500+ models from major providers. Fetch the current list with pricing dynamically:

```bash
curl https://api.ppq.ai/v1/models
```

Key providers include:
- **OpenAI**: GPT-5, GPT-4o, o3, o4-mini
- **Anthropic**: Claude Opus 4.6, Claude Sonnet 4.6, Claude Sonnet 4.5, Claude Haiku 4.5
- **Google**: Gemini 2.5 Pro, Gemini 2.5 Flash, Gemini 3 Pro
- **xAI**: Grok 3, Grok 3 Mini
- **Mistral**: Mistral Large, Codestral
- **Meta**: Llama 3, Llama 3.1
- **Deepseek**: Deepseek-R1, Deepseek-V3
- **Qwen**: Qwen 3

Model availability and pricing change over time. Always use the `GET /v1/models` endpoint for current information.

## Errors & Status Codes

The API returns standard HTTP status codes with JSON error bodies:

```json
{
  "status": "error",
  "statusCode": 401,
  "message": "Unauthorized"
}
```

Common status codes:
- **400** — Bad Request (malformed JSON or invalid parameters)
- **401** — Unauthorized (missing or invalid API key)
- **402** — Payment Required (insufficient credit balance)
- **500** — Internal Server Error

There is no explicit rate limiting — usage is controlled by your credit balance. If your balance is insufficient for a request, you'll receive a 402 response.

## Billing & Topups

PayPerQ uses a **pay-per-query** model — no subscriptions, no monthly fees. You add credits to your account and each API call deducts from your balance based on the model and token usage.

### Account Management
- `POST https://api.ppq.ai/accounts/create` — Create a new account (returns credit_id and api_key)
- `POST https://api.ppq.ai/credits/balance` — Check your current balance (body: `{"credit_id": "YOUR_CREDIT_ID"}`)

### Crypto Topup Endpoints
All topup endpoints accept `Authorization: Bearer YOUR_API_KEY` and a JSON body with `amount` and `currency`.

- `POST https://api.ppq.ai/topup/create/btc-lightning` — Bitcoin Lightning
  - Currencies: USD, BTC, SATS
  - USD limits: $0.10–$1,000 | SATS limits: 100–1,000,000
  - Expiration: 15 minutes | Bonus: 5% Lightning fee bonus

- `POST https://api.ppq.ai/topup/create/btc` — Bitcoin on-chain
  - Currencies: USD, BTC
  - USD limits: $10–$10,000
  - Expiration: 60 minutes

- `POST https://api.ppq.ai/topup/create/ltc` — Litecoin
  - Currencies: USD, LTC
  - USD limits: $2–$1,000
  - Expiration: 60 minutes

- `POST https://api.ppq.ai/topup/create/lbtc` — Liquid Bitcoin
  - Currencies: USD, LBTC
  - USD limits: $2–$10,000
  - Expiration: 60 minutes

- `POST https://api.ppq.ai/topup/create/xmr` — Monero
  - Currencies: USD, XMR
  - USD limits: $5–$10,000
  - Expiration: 60 minutes

### Topup Utilities
- `GET https://api.ppq.ai/topup/status/{invoice_id}` — Check invoice payment status
- `GET https://api.ppq.ai/topup/payment-methods` — List all supported payment methods with limits

### NWC Auto-Topup (Nostr Wallet Connect)
Connect a Nostr Wallet Connect (NWC) compatible Lightning wallet to automatically top up your balance when it falls below a threshold. Compatible wallets include Alby Hub, LNBits, Primal, and others.

All NWC endpoints require `Authorization: Bearer YOUR_API_KEY` and `x-credit-id: YOUR_CREDIT_ID` headers.

- `POST https://api.ppq.ai/nwc-auto-topup/connect` — Connect an NWC wallet for automatic top-ups
  - Parameters: `nwc_url` (required), `threshold_usd` (optional, default: 10, min: 5), `topup_amount_usd` (optional, default: 10)
  - Wallet must support the `pay_invoice` NIP-47 capability

- `GET https://api.ppq.ai/nwc-auto-topup` — Get current NWC auto-topup settings

- `DELETE https://api.ppq.ai/nwc-auto-topup/connection` — Disconnect wallet and disable auto-topup

### Example: Create a Lightning topup

```bash
curl -X POST https://api.ppq.ai/topup/create/btc-lightning \
  -H "Authorization: Bearer sk-YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"amount": 1000, "currency": "SATS"}'
```

Fiat payments (credit/debit card) are also available via Stripe on the website at https://ppq.ai.

## Important Notes

- **Different base URLs**: Chat API uses `https://api.ppq.ai`, audio APIs (STT/TTS) use `https://ppq.ai/api/v1`
- **OpenAI SDK compatibility**: Set `base_url="https://api.ppq.ai/v1"` for chat, `base_url="https://ppq.ai/api/v1"` for audio
- **Dynamic model list**: Always fetch available models from `/v1/models` rather than hardcoding — models are added and updated regularly
- **Streaming**: Chat completions support `"stream": true` for SSE streaming responses

## Documentation

- [API Documentation](https://ppq.ai/api-docs): Full interactive API docs with code examples
- [Blog](https://ppq.ai/blog): Additional guides and announcements

## Integration Guides

- [Claude Code](https://ppq.ai/blog/using-claude-code-with-payperq)
- [OpenCode](https://ppq.ai/blog/using-opencode-with-payperq)
- [Cursor](https://ppq.ai/blog/using-cursor-with-payperq)
- [Cline](https://ppq.ai/blog/using-cline-with-payperq)
- [Aider](https://ppq.ai/blog/using-aider-with-payperq)
- [Roo](https://ppq.ai/blog/using-roo-with-payperq)
- [OpenWebUI](https://ppq.ai/blog/using-openwebui-with-payperq)
- [Goose](https://ppq.ai/blog/using-goose-with-payperq)