# LLM Buyer Guide (/docs/llm/buyer)



Call a publisher's AI model through Voidnet. One model per app, billed per token. Use the OpenAI SDK — just change the `base_url`.

## Credentials [#credentials]

Use an API key from **Voidnet Console → API Keys** (`vnb-sk-*`) or a short-lived JWT from `POST /oauth/token` (`grant_type=client_credentials`, `scope=llm:completions`). The gateway accepts both.

## Find an app [#find-an-app]

Browse the **Voidnet Marketplace** and note the publisher's username, the app name, and the model ID listed on the app page (for example `Qwen/Qwen2.5-7B-Instruct`). Each app serves exactly one model — the `model` in your request must match it.

## Get access [#get-access]

Apps offer free tiers, paid tiers, or both. Purchase in the Marketplace to gain access:

* **Free tier** — tap Get Free. Access is instant, no payment.
* **Paid tier** — tap Subscribe/Purchase. Paid access runs on wallet: the price is deducted from your wallet balance (one-time/setup charge at grant, plus per-token charges per call on usage-based apps). Top up first if your balance is short.
* **Upgrade** — own free and want paid? The app page shows an **Upgrade** button that moves you to the paid tier. Your free access is revoked automatically when the paid grant completes. There is exactly one active tier per app.

Top up at **Voidnet Console → Wallet**: $5–$1000 per top-up via Stripe Checkout. You return to the wallet page and the balance credits automatically.

## Call it [#call-it]

### cURL [#curl]

```bash
curl -X POST https://api.openvoidnet.com/v1-beta/llm/acmecorp/my-llm \
  -H "Authorization: Bearer vnb-sk-a1b2c3..." \
  -H "Content-Type: application/json" \
  -d '{"model":"Qwen/Qwen2.5-7B-Instruct","messages":[{"role":"user","content":"Write a haiku"}],"temperature":0.7,"max_tokens":64,"stream":false}'
```

Response (OpenAI-compatible):

```json
{
  "id": "chatcmpl-abc",
  "object": "chat.completion",
  "created": 1730000000,
  "model": "Qwen/Qwen2.5-7B-Instruct",
  "choices": [{"index":0,"message":{"role":"assistant","content":"An old pond..."},"finish_reason":"stop"}],
  "usage": {"prompt_tokens":10,"completion_tokens":12,"total_tokens":22}
}
```

### Streaming [#streaming]

`stream:true` is supported (SSE, OpenAI shape). The gateway injects `stream_options.include_usage:true` when missing so the call stays metered. A stream whose publisher never sends a final usage chunk fails loudly instead of going unbilled.

```bash
curl -X POST https://api.openvoidnet.com/v1-beta/llm/acmecorp/my-llm \
  -H "Authorization: Bearer vnb-sk-a1b2c3..." \
  -H "Content-Type: application/json" \
  -d '{"model":"Qwen/Qwen2.5-7B-Instruct","messages":[{"role":"user","content":"hi"}],"stream":true}'
```

### OpenAI SDK [#openai-sdk]

```python
from openai import OpenAI
client = OpenAI(base_url="https://api.openvoidnet.com/v1-beta/llm/acmecorp/my-llm", api_key="vnb-sk-a1b2c3...")
response = client.chat.completions.create(model="Qwen/Qwen2.5-7B-Instruct", messages=[{"role":"user","content":"hi"}])
print(response.choices[0].message.content, response.usage.total_tokens)
```

```ts
import OpenAI from "openai"
const openai = new OpenAI({ baseURL: "https://api.openvoidnet.com/v1-beta/llm/acmecorp/my-llm", apiKey: "vnb-sk-..." })
const response = await openai.chat.completions.create({ model: "Qwen/Qwen2.5-7B-Instruct", messages: [{role:"user",content:"hi"}] })
```

The only changes from a standard OpenAI call are the `baseURL` (your app's gateway URL) and the `model` (must match the app's published model).

## Models listing [#models-listing]

A read-only listing of the publisher's models (proxied from their server, OpenAI shape):

```bash
curl https://api.openvoidnet.com/v1-beta/llm/acmecorp/my-llm/models \
  -H "Authorization: Bearer vnb-sk-a1b2c3..."
```

Non-billable — no metering, no wallet charge.

Full interactive reference (parameters, responses, Try-it) for every LLM operation: [LLM API](https://docs.openvoidnet.com/docs/reference/api/llm).

## Billing [#billing]

Paid LLM apps price per 1M tokens (shown as $X/1M on the app page). Each call deducts `total_tokens / 1M × price` from your wallet; an empty wallet returns `402 insufficient_balance`. Track spending per app in **Voidnet Console → Usage**.

## Errors you will see [#errors-you-will-see]

| Status | Code                                  | Meaning                                                                                     |
| ------ | ------------------------------------- | ------------------------------------------------------------------------------------------- |
| 401    | `api_key_invalid` / `api_key_missing` | Bad or missing credential                                                                   |
| 403    | `app_not_purchased`                   | No live purchase — get the free tier or subscribe first                                     |
| 404    | `app_not_found`                       | Wrong publisher username or app name                                                        |
| 400    | `invalid_request`                     | Missing `model`/`messages`, bad JSON, or multimodal content (`image_url`, `audio`, `video`) |
| 4xx    | `publisher_client_error`              | The publisher's server rejected the request (for example unknown model) — body preserved    |
| 429    | `rate_limit_exceeded`                 | Too fast — back off and retry (see [Rate Limiting](https://docs.openvoidnet.com/docs/reference/rate-limiting))          |
| 429    | `meter_limit_exceeded`                | Monthly tier quota used — wait for reset or upgrade tier                                    |
| 402    | `insufficient_balance`                | Wallet too low for a paid call — top up in Console → Wallet                                 |
| 502    | `publisher_error`                     | Publisher offline, invalid JSON, or stream without a usage chunk                            |

## Limits [#limits]

* TEXT only — `content` must be a string. `image_url`, `audio`, and `video` are rejected.
* Only `chat/completions` for inference, plus the read-only models listing above — no embeddings.
* Single model per app.