# 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, Image & Video 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) for chat completions

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

### Image Generation
- `POST https://api.ppq.ai/v1/images/generations` — Generate images from text prompts
- 50+ models from OpenAI (GPT Image), Google (Imagen), Black Forest Labs (Flux), xAI (Grok), ByteDance, Recraft, and more
- Also supports image editing, background removal, and upscaling models
- Parameters: `model` (required), `prompt` (required), `n` (number of images, 1-10), `size` (e.g. "1024x1024"), `quality` ("low", "medium", "high")
- For interactive examples and full parameter docs, see the [API Documentation](https://ppq.ai/api-docs)

```bash
curl -X POST https://api.ppq.ai/v1/images/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-YOUR_API_KEY" \
  -d '{
    "model": "fal-ai/flux-2",
    "prompt": "A serene mountain landscape at sunset",
    "size": "1024x1024"
  }'
```

```python
import requests

response = requests.post(
    "https://api.ppq.ai/v1/images/generations",
    headers={"Authorization": "Bearer sk-YOUR_API_KEY", "Content-Type": "application/json"},
    json={"model": "fal-ai/flux-2", "prompt": "A serene mountain landscape at sunset", "size": "1024x1024"}
)
data = response.json()
print(data["data"][0]["url"])  # Signed URL to the generated image (valid 24h)
```

Key image models include:
- `fal-ai/gpt-image-1.5` — OpenAI GPT Image 1.5
- `fal-ai/imagen4/preview` — Google Imagen 4
- `fal-ai/flux-2` — Black Forest Labs Flux 2
- `black-forest-labs/flux-pro` — Flux Pro
- `xai/grok-imagine` — xAI Grok Imagine
- `fal-ai/qwen-image` — Qwen Image
- `fal-ai/bytedance/seedream/v4.5/text-to-image` — ByteDance SeedDream
- `fal-ai/imageutils/rembg` — Background removal
- `fal-ai/clarity-upscaler` — Image upscaling

### Video Generation
- `POST https://api.ppq.ai/v1/videos` — Generate videos from text or image prompts (async)
- `GET https://api.ppq.ai/v1/videos/{id}` — Check video generation status and retrieve result
- 24+ models from Google (Veo), OpenAI (Sora), Luma, MiniMax, Kling, xAI, ByteDance, and more
- Supports both text-to-video and image-to-video
- Parameters: `model` (required), `prompt` (required), `aspect_ratio` (e.g. "16:9", "9:16"), `duration`, `generate_audio`
- For interactive examples and full parameter docs, see the [API Documentation](https://ppq.ai/api-docs)

Video generation is **asynchronous**: the POST returns a job ID with HTTP 202, and you poll the GET endpoint until status is `"completed"`.

```bash
# Submit a video generation job
curl -X POST https://api.ppq.ai/v1/videos \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-YOUR_API_KEY" \
  -d '{
    "model": "fal-ai/veo3.1",
    "prompt": "A golden retriever running on a beach at sunset"
  }'
# Response: {"id": "gen_abc123", "status": "pending", ...}

# Poll for completion
curl https://api.ppq.ai/v1/videos/gen_abc123 \
  -H "Authorization: Bearer sk-YOUR_API_KEY"
# Response (when done): {"id": "gen_abc123", "status": "completed", "data": {"url": "..."}, "cost": 3.68}
```

```python
import requests, time

headers = {"Authorization": "Bearer sk-YOUR_API_KEY", "Content-Type": "application/json"}

# Submit job
resp = requests.post("https://api.ppq.ai/v1/videos", headers=headers,
    json={"model": "fal-ai/veo3.1", "prompt": "A golden retriever running on a beach at sunset"})
job = resp.json()

# Poll until complete
while job["status"] not in ("completed", "failed"):
    time.sleep(5)
    job = requests.get(f"https://api.ppq.ai/v1/videos/{job['id']}", headers=headers).json()

print(job["data"]["url"])  # Signed URL to the generated video (valid 24h)
```

Key video models include:
- `fal-ai/veo3.1` — Google Veo 3.1
- `fal-ai/sora-2/text-to-video` — OpenAI Sora 2
- `fal-ai/kling-video/o3/standard/text-to-video` — Kling 3
- `fal-ai/luma-dream-machine` — Luma Dream Machine
- `fal-ai/minimax/hailuo-02/pro/text-to-video` — MiniMax Hailuo
- `xai/grok-imagine-video/text-to-video` — xAI Grok Video
- `fal-ai/mochi-v1` — Mochi
- `fal-ai/haiper-video-v2` — Haiper Video

### Data Enrichment
- `GET https://api.ppq.ai/v1/data/endpoints` — List all available data endpoints with pricing (no auth required)
- `POST https://api.ppq.ai/v1/data/api/{provider}/{action}` — Call a data enrichment endpoint
- `GET https://api.ppq.ai/v1/data/api/{provider}/{action}` — Call a data GET endpoint (e.g. place details)
- All enrichment endpoints require `Authorization: Bearer YOUR_API_KEY`
- Each call deducts from your PPQ credit balance (endpoint price × markup)

Covers people search, company lookup, web scraping, Google Maps, Reddit, email verification, and social media enrichment.

For full parameter documentation and request/response schemas for each endpoint, see: https://ppq.ai/data-providers

Available providers and endpoints:

| Endpoint | Method | Price |
|----------|--------|-------|
| `/v1/data/api/google-maps/text-search/full` | POST | $0.08 |
| `/v1/data/api/google-maps/text-search/partial` | POST | $0.02 |
| `/v1/data/api/google-maps/nearby-search/full` | POST | $0.08 |
| `/v1/data/api/google-maps/nearby-search/partial` | POST | $0.02 |
| `/v1/data/api/google-maps/place-details/full` | GET | $0.05 |
| `/v1/data/api/google-maps/place-details/partial` | GET | $0.02 |
| `/v1/data/api/apollo/people-search` | POST | $0.02 |
| `/v1/data/api/apollo/org-search` | POST | $0.02 |
| `/v1/data/api/apollo/people-enrich` | POST | $0.0495 |
| `/v1/data/api/apollo/org-enrich` | POST | $0.0495 |
| `/v1/data/api/exa/search` | POST | $0.01 |
| `/v1/data/api/exa/find-similar` | POST | $0.01 |
| `/v1/data/api/exa/contents` | POST | $0.002 |
| `/v1/data/api/exa/answer` | POST | $0.01 |
| `/v1/data/api/firecrawl/scrape` | POST | $0.0126 |
| `/v1/data/api/firecrawl/search` | POST | $0.0252 |
| `/v1/data/api/clado/contacts-enrich` | POST | $0.20 |
| `/v1/data/api/clado/linkedin-scrape` | POST | $0.04 |
| `/v1/data/api/serper/news` | POST | $0.04 |
| `/v1/data/api/serper/shopping` | POST | $0.04 |
| `/v1/data/api/reddit/search` | POST | $0.02 |
| `/v1/data/api/reddit/post-comments` | POST | $0.02 |
| `/v1/data/api/whitepages/person-search` | POST | $0.44 |
| `/v1/data/api/whitepages/property-search` | POST | $0.44 |
| `/v1/data/api/hunter/email-verifier` | POST | $0.03 |
| `/v1/data/api/influencer/enrich-by-email` | POST | $0.40 |
| `/v1/data/api/influencer/enrich-by-social` | POST | $0.40 |

```bash
# Discover all endpoints and prices
curl https://api.ppq.ai/v1/data/endpoints

# Search for people (Apollo)
curl -X POST https://api.ppq.ai/v1/data/api/apollo/people-search \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-YOUR_API_KEY" \
  -d '{"q_keywords": "software engineer", "person_locations": ["San Francisco"], "per_page": 5}'

# Scrape a web page (Firecrawl)
curl -X POST https://api.ppq.ai/v1/data/api/firecrawl/scrape \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-YOUR_API_KEY" \
  -d '{"url": "https://example.com"}'

# Semantic web search (Exa)
curl -X POST https://api.ppq.ai/v1/data/api/exa/search \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-YOUR_API_KEY" \
  -d '{"query": "AI agent startups 2025", "numResults": 10}'
```

```python
import requests

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

# People search via Apollo
resp = requests.post(
    "https://api.ppq.ai/v1/data/api/apollo/people-search",
    headers=headers,
    json={"q_keywords": "software engineer", "person_locations": ["San Francisco"], "per_page": 5}
)
print(resp.json())

# Enrich a person's profile
resp = requests.post(
    "https://api.ppq.ai/v1/data/api/apollo/people-enrich",
    headers=headers,
    json={"email": "tim@apple.com"}
)
print(resp.json())
```

### Models
- `GET https://api.ppq.ai/v1/models` — List available models with pricing info
- Filter by modality with the `type` query parameter:
  - `GET /v1/models` — Chat models only (default)
  - `GET /v1/models?type=image` — Image generation models only
  - `GET /v1/models?type=video` — Video generation models only
  - `GET /v1/models?type=image,video` — Image and video models
  - `GET /v1/models?type=all` — All models across all modalities (chat, image, video, audio)
- Filter popular models: `GET /v1/models?popular=true`

### 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, Image, and Video APIs use `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/images, `base_url="https://ppq.ai/api/v1"` for audio
- **Async video generation**: Video generation is asynchronous — submit a job, then poll for completion. Images are synchronous.
- **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
- [Data Enrichment Reference](https://ppq.ai/data-providers): Full parameter docs for all 27 data enrichment endpoints
- [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)