# PayPerQ (PPQ) API

> Unified AI API gateway with 500+ models from all major providers. OpenAI-compatible endpoints, pay-per-query pricing (no subscriptions), and cryptocurrency payment support including Bitcoin Lightning.

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) 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)

### 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.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

### 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
- [Claude Code Setup](https://ppq.ai/blog/using-claude-code-with-payperq): Guide for using PPQ with Claude Code
- [Cline Setup](https://ppq.ai/blog/using-cline-with-payperq): Guide for using PPQ with Cline
- [Aider Setup](https://ppq.ai/blog/using-aider-with-payperq): Guide for using PPQ with Aider
- [OpenWebUI Setup](https://ppq.ai/blog/using-openwebui-with-payperq): Guide for using PPQ with OpenWebUI
- [Cursor Setup](https://ppq.ai/blog/using-cursor-with-payperq): Guide for using PPQ with Cursor
- [Goose Setup](https://ppq.ai/blog/using-goose-with-payperq): Guide for using PPQ with Goose