Every endpoint, end to end.

Authentication

Every billable call needs a bearer key. Get one instantly — no card, no signup form:

curl -X POST https://api.vellaquant.com/v1/trial \
  -H "Content-Type: application/json" \
  -d '{"email":"[email protected]"}'

{
  "api_key": "vq-…",
  "free_credit_usd": 0.05,
  "base_url": "https://api.vellaquant.com/v1"
}

email is optional — include it and the key is emailed to you as a receipt. One trial key is issued per network per 24 hours.

Drop-in OpenAI compatibility

from openai import OpenAI

client = OpenAI(
    base_url="https://api.vellaquant.com/v1",
    api_key="vq-your-key",
)
print(client.chat.completions.create(
    model="vella",
    messages=[{"role": "user", "content": "Hello"}],
).choices[0].message.content)

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.vellaquant.com/v1",
  apiKey: "vq-your-key",
});
const r = await client.chat.completions.create({
  model: "vella",
  messages: [{ role: "user", content: "Hello" }],
});
console.log(r.choices[0].message.content);

curl https://api.vellaquant.com/v1/chat/completions \
  -H "Authorization: Bearer vq-your-key" \
  -H "Content-Type: application/json" \
  -d '{"model":"vella","messages":[{"role":"user","content":"Hello"}]}'

Endpoints

POST /v1/chat/completions · $0.40 / 1M tokens

OpenAI-compatible chat completions served by MLX. Accepts messages, max_tokens, temperature. Returns the standard choices[] / usage shape plus a vella billing block.

{
  "choices": [{ "index": 0, "message": { "role": "assistant", "content": "OK" },
                "finish_reason": "stop" }],
  "usage": { "prompt_tokens": 38, "completion_tokens": 2, "total_tokens": 40 },
  "vella": { "billed_usd": 0.000016, "remaining_usd": 0.049984 }
}

POST /v1/embeddings · $0.02 / 1M tokens

384-dimension vectors from all-MiniLM-L6-v2. input takes a string or a list of strings. OpenAI-compatible response shape.

curl https://api.vellaquant.com/v1/embeddings \
  -H "Authorization: Bearer vq-your-key" \
  -H "Content-Type: application/json" \
  -d '{"input":["sovereign inference","apple silicon"]}'

POST /v1/documents · billed as embeddings

Upsert documents into a private vector namespace scoped to your key. Returns the stored ids and the namespace count. No infrastructure to run.

curl https://api.vellaquant.com/v1/documents \
  -H "Authorization: Bearer vq-your-key" \
  -H "Content-Type: application/json" \
  -d '{"documents":["Vella Quant serves MLX inference.","Castle Pines is in Colorado."]}'

{"ids":["b353ba3d24ad4fd7","8627deb9cfc7462c"],"count":2,
 "vella":{"billed_usd":0.0,"remaining_usd":0.049984}}

POST /v1/search · $0.001 / query

Semantic retrieval over your namespace. Takes query and optional top_k (default 5); returns scored hits — the retrieval half of a RAG stack.

{"results":[
   {"id":"8627deb9cfc7462c","text":"Castle Pines is in Colorado.","score":0.819773},
   {"id":"b353ba3d24ad4fd7","text":"Vella Quant serves MLX inference.","score":-0.073192}],
 "model":"sentence-transformers/all-MiniLM-L6-v2"}

POST /v1/rerank · billed as embeddings

Reorder candidate documents by semantic relevance to a query. Takes query, documents and optional top_n; returns each document with its original index and a relevance_score.

POST /v1/briefing · $0.05 / call

A market-intelligence briefing: live cross-asset signals blended with an AI analyst narrative, generated on sovereign hardware. Informational research only — not financial advice.

GET /v1/models · GET /v1/usage · GET /health

/v1/models lists servable models. /v1/usage (authenticated) returns your prepaid balance, spend, request and token counts. /health is public and unauthenticated — use it for uptime checks.

{"status":"ok","backend":"mlx","node":"Roberts-Mac-mini.local","payments":"stripe"}

POST /v1/checkout

Creates a top-up checkout session for your key. Prepaid credit only — no subscriptions, seats or minimums.

Errors & limits

Errors use the OpenAI envelope: {"error":{"message":…,"type":…}}.

• 400 invalid_request_error — malformed JSON or a missing or mistyped field.
• 401 authentication_error — missing or invalid bearer key.
• 402 insufficient_quota — prepaid credit exhausted; top up via /v1/checkout.
• 429 rate_limit — per-IP token bucket (240 req/min, burst 60), or a trial key already issued to your network in the last 24 hours.
• 500 api_error — backend failure. Check /health.

Every successful billable response carries vella.billed_usd and vella.remaining_usd, so you can meter spend without a second API call.

FAQ

Is it really OpenAI-compatible?

Chat completions and embeddings follow the OpenAI request/response shapes, so the official SDKs work by changing base_url and api_key. Search, rerank, briefings and checkout are Vella-native additions.

Do I need a credit card to try it?

No. POST /v1/trial returns a key with $0.05 of credit instantly.

Where does inference run?

On Apple Silicon owned and physically controlled by Vella Quant, via MLX. Traffic arrives over a Cloudflare tunnel, so the node has no open inbound ports. Your prompts and stored documents are not resold and are not used for training.

What happens when my credit runs out?

Calls return 402 insufficient_quota and stop billing. Top up and the same key keeps working — keys are never silently rotated.