Quickstart

from openai import OpenAI

client = OpenAI(
    api_key="<your-velona-key>",
    base_url="http://www.velona.in/v1",
)

completion = client.chat.completions.create(
    model="openai/gpt-4o-mini",
    messages=[{"role": "user", "content": "Hello!"}],
)
print(completion.choices[0].message.content)

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: "<your-velona-key>",
  baseURL: "http://www.velona.in/v1",
});

const completion = await client.chat.completions.create({
  model: "openai/gpt-4o-mini",
  messages: [{ role: "user", content: "Hello!" }],
});
console.log(completion.choices[0].message.content);

import httpx

with httpx.stream(
    "POST",
    "http://www.velona.in/gateway/v1/inference/run",
    headers={"Authorization": "Bearer <your-key>"},
    json={
        "model": "openai/gpt-4o-mini",
        "turns": [{"role": "user", "content": "Count to 5."}],
        "stream": True,
    }
) as r:
    for line in r.iter_lines():
        if line.startswith("data:"):
            print(line[5:].strip())

curl -X POST http://www.velona.in/gateway/v1/inference/run \
  -H "Authorization: Bearer <your-key>" \
  -H "Content-Type: application/json" \
  -d '{"model": "openai/gpt-4o-mini", "turns": [{"role": "user", "content": "Count to 5."}], "stream": true}'

const res = await fetch("http://www.velona.in/gateway/v1/inference/run", {
  method: "POST",
  headers: {
    "Authorization": "Bearer <your-key>",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "openai/gpt-4o-mini",
    turns: [{ role: "user", content: "Count to 5." }],
    stream: true,
  }),
});

const reader = res.body.getReader();
const decoder = new TextDecoder();
while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  const lines = decoder.decode(value).split("\n");
  for (const line of lines) {
    if (line.startsWith("data:") && line !== "data: [DONE]") {
      const chunk = JSON.parse(line.slice(5).trim());
      if (chunk.event === "delta") process.stdout.write(chunk.data.delta);
    }
  }
}

import httpx

# Create a memory session (uses your JWT, not an API key)
response = httpx.post(
    "http://www.velona.in/memory/sessions",
    headers={"Authorization": "Bearer <your-jwt>"},
    json={
        "name": "My Project Assistant",
        "max_chars": 150000   # Medium tier
    }
)
session = response.json()
memory_id = session["memory_id"]  # e.g. "mem_4a7b2c3d1e9f0a8b"
print(f"Session created: {memory_id}")

curl -X POST http://www.velona.in/memory/sessions \
  -H "Authorization: Bearer <your-jwt>" \
  -H "Content-Type: application/json" \
  -d '{"name": "My Project Assistant", "max_chars": 150000}'

# Response:
# {"memory_id": "mem_4a7b2c3d1e9f0a8b", "name": "My Project Assistant",
#  "max_chars": 150000, "char_count": 0, "created_at": "..."}

import httpx

MEMORY_ID = "mem_4a7b2c3d1e9f0a8b"

# First turn
r1 = httpx.post(
    "http://www.velona.in/gateway/v1/inference/run",
    headers={"Authorization": "Bearer <your-key>"},
    json={
        "model": "openai/gpt-4o-mini",
        "turns": [{"role": "user", "content": "My name is Rohan. Remember that."}],
        "velona": {"memory_session": MEMORY_ID},
    }
)
print(r1.json()["data"]["output"])

# Second turn, context from first turn is injected automatically
r2 = httpx.post(
    "http://www.velona.in/gateway/v1/inference/run",
    headers={"Authorization": "Bearer <your-key>"},
    json={
        "model": "openai/gpt-4o-mini",
        "turns": [{"role": "user", "content": "What's my name?"}],
        "velona": {"memory_session": MEMORY_ID},
    }
)
print(r2.json()["data"]["output"])  # "Your name is Rohan."

# First turn
curl -X POST http://www.velona.in/gateway/v1/inference/run \
  -H "Authorization: Bearer <your-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-4o-mini",
    "turns": [{"role": "user", "content": "My name is Rohan. Remember that."}],
    "velona": {"memory_session": "mem_4a7b2c3d1e9f0a8b"}
  }'

# Second turn, prior context injected automatically
curl -X POST http://www.velona.in/gateway/v1/inference/run \
  -H "Authorization: Bearer <your-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-4o-mini",
    "turns": [{"role": "user", "content": "What is my name?"}],
    "velona": {"memory_session": "mem_4a7b2c3d1e9f0a8b"}
  }'

import httpx

response = httpx.post(
    "http://www.velona.in/gateway/v1/inference/run",
    headers={"Authorization": "Bearer <your-key>"},
    json={"model": "openai/gpt-4o-mini", "turns": [{"role": "user", "content": "Hi"}]}
)

body = response.json()
if body["status"] == "error":
    code = body["error"]["code"]
    if code == "INSUFFICIENT_CREDITS":
        print("Top up your wallet at /wallet")
    elif code == "INVALID_KEY":
        print("Check your API key")
    elif code == "RATE_LIMIT_EXCEEDED":
        print("Slow down, retry after", response.headers.get("Retry-After"), "seconds")
    elif code in ("UPSTREAM_ERROR", "UPSTREAM_TIMEOUT"):
        print("Provider issue, retry with exponential backoff")
    else:
        print(f"Error: {code} -- {body['error']['message']}")
else:
    print(body["data"]["output"])

# An invalid key returns HTTP 401:
curl -X POST http://www.velona.in/gateway/v1/inference/run \
  -H "Authorization: Bearer invalid-key" \
  -H "Content-Type: application/json" \
  -d '{"model": "openai/gpt-4o-mini", "turns": [{"role": "user", "content": "Hi"}]}'

# Response:
# {"request_id":"req_unknown","status":"error","error":{"code":"INVALID_KEY",...}}

# .env
VELONA_API_KEY=sk-<your-48-hex-key>
VELONA_BASE_URL=http://www.velona.in/v1

import os
from openai import OpenAI
from dotenv import load_dotenv

load_dotenv()

client = OpenAI(
    api_key=os.environ["VELONA_API_KEY"],
    base_url=os.environ["VELONA_BASE_URL"],
)