Dokumentation

Mit Soloniq starten.

Soloniq ist eine OpenAI-kompatible API für Open-Weight-Modelle auf Servern in der EU. Prompts und Antworten werden nie gespeichert. Spricht Ihr Code bereits mit der OpenAI-API, ändern Sie nur die Basis-URL, den Key und den Modellnamen – sonst nichts.

Schnellstart

Key erstellen. Melden Sie sich unter app.soloniq.com an, öffnen Sie Keys und erstellen Sie einen Key. Er beginnt mit sq_live_ und wird nur einmal angezeigt – bewahren Sie ihn als Secret auf Ihrem Server auf.
Guthaben aufladen unter Credits & invoices – per PayPal (zzgl. 2,5 % Gebühr) oder Überweisung, ab 30 €. Sie zahlen bei Soloniq im Voraus in Euro und erhalten für jede Zahlung eine Rechnung.
Anfrage senden:

curl https://api.soloniq.com/v1/chat/completions \
  -H "Authorization: Bearer $SOLONIQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "soloniq/agent",
    "max_tokens": 2000,
    "messages": [{"role": "user", "content": "Hallo!"}]
  }'

Basis-URL	`https://api.soloniq.com/v1`
Authentifizierung	`Authorization: Bearer sq_live_…`
Endpunkte	`POST /v1/chat/completions`, `GET /v1/models`

SDKs und Tools

Jeder OpenAI-kompatible Client funktioniert: Basis-URL und Key setzen, Soloniq-Modellnamen verwenden – fertig.

Python

import os
from openai import OpenAI

client = OpenAI(base_url="https://api.soloniq.com/v1", api_key=os.environ["SOLONIQ_API_KEY"])
reply = client.chat.completions.create(
    model="soloniq/agent",
    max_tokens=2000,
    messages=[{"role": "user", "content": "Fasse die DSGVO in einem Satz zusammen."}],
)
print(reply.choices[0].message.content)

JavaScript / TypeScript

import OpenAI from "openai";

const client = new OpenAI({ baseURL: "https://api.soloniq.com/v1", apiKey: process.env.SOLONIQ_API_KEY });
const reply = await client.chat.completions.create({
  model: "soloniq/agent",
  max_tokens: 2000,
  messages: [{ role: "user", content: "Fasse die DSGVO in einem Satz zusammen." }],
});
console.log(reply.choices[0].message.content);

Agenten-Frameworks und weitere Tools

Die meisten Tools lesen die üblichen Umgebungsvariablen:

OPENAI_BASE_URL=https://api.soloniq.com/v1
OPENAI_API_KEY=sq_live_…
MODEL=soloniq/agent            # Hauptmodell
AUX_MODEL=soloniq/agent-fast   # Zusammenfassungen, Komprimierung, Routineschritte

In LiteLLM binden Sie Soloniq als OpenAI-kompatiblen Anbieter ein:

model_list:
  - model_name: agent
    litellm_params:
      model: openai/soloniq/agent
      api_base: https://api.soloniq.com/v1
      api_key: os.environ/SOLONIQ_API_KEY

Soloniq Code: Programmieren im Terminal

Soloniq Code richtet OpenCode ein, einen Open-Source-Coding-Agenten für das Terminal (MIT-Lizenz), und verbindet ihn mit den Soloniq-Modellen. Er liest Ihr Projekt, bearbeitet Dateien und führt Befehle aus – wie andere KI-Coding-Assistenten auch. Ihr Code wird nur auf Servern in der EU verarbeitet und nie gespeichert.

Installieren

curl -fsSL https://soloniq.com/code.sh | sh

Linux und macOS; unter Windows in WSL. Das Skript installiert bei Bedarf OpenCode, fragt nach Ihrem Soloniq-Key, prüft ihn und schreibt eine Konfiguration mit den Modellen, die Ihr Key nutzen darf. Sie können das Skript vorher lesen: soloniq.com/code.sh.

Verwenden

cd mein-projekt
soloniq                                     # starten
soloniq run "Schreibe Tests für utils.py"   # eine Aufgabe, ohne Oberfläche
soloniq --key                               # anderen Key verwenden
soloniq --uninstall                         # Soloniq Code entfernen (OpenCode bleibt)

Modelle. Standard ist soloniq/agent. Wechseln Sie mit /models, zum Beispiel zu kimi-k2.7-code oder agent-pro für schwierigere Aufgaben.
Ein eigener Key für jede Person im Team, jeweils mit eigenem Monatsbudget. Unter Usage in der Konsole sehen Sie die Kosten pro Key.
Standardmäßig privat. Soloniq ist der einzige Anbieter; das Teilen von Sitzungen, die Update-Prüfung und das Herunterladen von Modelllisten sind abgeschaltet. Ihr Key liegt in ~/.config/soloniq/api-key, nur für Sie lesbar.
Farbschema. In Terminals mit voller Farbunterstützung Tokyonight, sonst die Farben Ihres Terminals – so bleibt alles gut lesbar. Tokyonight erzwingen: SOLONIQ_THEME=tokyonight soloniq.
Getestete Versionen. Wir installieren die OpenCode-Version, die wir mit Soloniq getestet haben (derzeit 1.19.5). Bitte wechseln Sie nicht per /update zu OpenCode 2. Die jeweils neueste getestete Version erhalten Sie, indem Sie den Installationsbefehl erneut ausführen.

Andere Coding-Tools

Coding-Tools, in denen Sie einen OpenAI-kompatiblen Anbieter hinzufügen können, funktionieren mit der Basis-URL https://api.soloniq.com/v1, Ihrem Key und einem Modellnamen. Schalten Sie Telemetrie und Funktionen zum Teilen im Tool aus, damit Ihr Code nur an Soloniq geht.

Modelle und Preise

Zehn Modelle von DeepSeek, Z.ai (GLM), Moonshot AI (Kimi), Alibaba (Qwen) und MiniMax – Preise, Kontextlänge, Bildunterstützung und Fallbacks finden Sie auf der Seite Modelle & Preise. GET /v1/models listet die Modelle, die Ihr Key nutzen darf. Für Agenten starten Sie mit diesen Namen:

Modell	Wofür	Input	Cached Input	Output
`soloniq/agent`	Empfohlener Standard für Agenten – Reasoning und Tool Calls	0,20	0,05	0,50
`soloniq/agent-fast`	Dasselbe Modell mit leichtem Reasoning – für Zusammenfassungen und Routineschritte	0,20	0,05	0,50
`soloniq/agent-pro`	Die stärkere Stufe – schwierigere Aufgaben, lange Agentenläufe (heute GLM-5.3)	1,75	0,44	4,50

Euro pro Million Tokens, zzgl. MwSt.

Aliasse und Fallback. agent, agent-fast und agent-pro sind Namen, keine Modelle: Sie zeigen auf das heute beste Modell für die Aufgabe – bei einem Upgrade ändern Sie nichts an Ihrer Konfiguration. Fällt das Standardmodell aus oder ist es zu langsam, antwortet automatisch das Fallback-Modell. Sie zahlen den Preis des Modells, das tatsächlich geantwortet hat – das Feld model jeder Antwort nennt es. Auch jedes andere Modell hat einen eigenen Fallback; die Preisseite zeigt ihn.

Modellnamen funktionieren mit und ohne Präfix: agent und soloniq/agent sind dasselbe.

Streaming

Mit "stream": true erhalten Sie Server-Sent Events im üblichen OpenAI-Format. Für die Tokenzahlen am Ende des Streams ergänzen Sie "stream_options": {"include_usage": true}.

Tool Calling

Wie bei OpenAI, mit tools und tool_choice. Tool Calls stehen in choices[0].message.tool_calls; senden Sie Ergebnisse als Nachrichten mit role: "tool".

"tools": [{
  "type": "function",
  "function": {
    "name": "book_table",
    "parameters": {"type": "object",
      "properties": {"date": {"type": "string"}, "people": {"type": "integer"}},
      "required": ["date", "people"]}
  }
}]

Bilder

Senden Sie Bilder als image_url-Inhalte (eine URL oder eine data:image/png;base64,…-URI). Anfragen mit Bild gehen an ein Modell der Fallback-Kette, das Bilder versteht – zu dessen Preis; welche Modelle Bilder verstehen, zeigt die Preisseite. Versteht keines davon Bilder, erhalten Sie 400 vision_not_supported.

Reasoning

soloniq/agent denkt nach, bevor es antwortet. Seine Überlegungen stehen in message.reasoning_content (nicht zur Anzeige für Nutzer gedacht) und zählen als Output-Tokens (usage.completion_tokens_details.reasoning_tokens).

Planen Sie genug Spielraum ein: max_tokens von 2.000 oder mehr – sonst verbraucht das Modell womöglich alles fürs Nachdenken.
Für schnelle, günstige Schritte nutzen Sie soloniq/agent-fast oder übergeben "reasoning_effort": "low".

Prompt Caching

Caching erfolgt automatisch. Beginnt eine Anfrage mit demselben Text wie eine vorherige – fester System-Prompt, gleiche Tool-Liste, der bisherige Verlauf –, werden diese Tokens zum deutlich günstigeren Cached-Input-Preis abgerechnet. Da Agenten ihren Kontext ständig erneut senden, lohnt es sich, den Anfang Ihrer Prompts gleich zu halten. Gecachte Tokens stehen in usage.prompt_tokens_details.cached_tokens – nur diese werden zum Cached-Input-Preis berechnet. Cache-Treffer sind wahrscheinlich, aber nicht bei jeder Anfrage garantiert.

Keys und Budgets

Ein Key pro Person, Team, Agent oder Instanz. Jeder Key hat einen Namen, Ihre eigene ID oder Referenz (Person, Kostenstelle, Kunde, Server), die erlaubten Modelle, ein Monatslimit in Euro und optional ein Tageslimit, Anfragen pro Minute und Tokens pro Minute. Ist ein Limit erreicht, pausiert nur dieser Key. Alles lässt sich in der Konsole unter Keys einstellen (New key, Edit) – oder, für Partner, über die Partner-API.
Sehen, wer was ausgibt: Usage zeigt Tokens und Kosten pro Key und Tag, filterbar nach Key, mit CSV-Export.
Keys bleiben auf Servern. Legen Sie nie einen Key in Browser- oder App-Code ab. Wir speichern Keys nur gehasht und zeigen sie Ihnen ein einziges Mal.
Rotieren Sie einen Key jederzeit in der Konsole: Sie erhalten einen neuen Key, der alte funktioniert noch 10 Minuten.
Sperren Sie einen Key sofort, wenn er in falsche Hände geraten ist. Mehr als sein eigenes Budget kann er ohnehin nicht ausgeben.
Teams: Laden Sie Kolleginnen und Kollegen in Ihr Konto ein. Inhaber und Admins sehen das Guthaben, alle Keys und die gesamte Nutzung; Mitglieder sehen nur die ihnen zugewiesenen Keys und ihre eigene Nutzung.

Limits

Jeder Key hat ein Limit für Anfragen pro Minute. Neue Konten haben außerdem ein Tageslimit für Ausgaben und eine Höchstzahl an Keys; wir heben sie an, je länger Ihr Konto besteht und je mehr Sie bezahlt haben. Ihre aktuellen Limits sehen Sie unter Credits & invoices – oder fragen Sie uns unter info@zana.ai nach mehr.

Fehler

Fehler haben das OpenAI-Format: {"error": {"message", "type", "code"}}.

Status	Code	Bedeutung und Abhilfe
400	`invalid_request`	Parameter und Nachrichtenformat prüfen.
400	`context_length_exceeded`	Die Eingabe ist länger als das Kontextfenster des Modells.
401	`invalid_api_key`	Key fehlt, ist falsch oder wurde widerrufen.
402	`budget_exceeded`	Der Key hat sein Monatsbudget verbraucht. Budget in der Konsole erhöhen. Nicht wiederholen.
402	`daily_budget_exceeded`	Der Key hat sein Tagesbudget verbraucht (Typ `budget_exceeded`). Es wird um Mitternacht (UTC) zurückgesetzt. Nicht wiederholen.
402	`balance_empty`	Ihr Prepaid-Guthaben ist aufgebraucht. Guthaben aufladen. Nicht wiederholen.
403	`key_blocked` / `model_not_allowed`	Der Key ist gesperrt oder darf dieses Modell nicht nutzen.
404	`model_not_found`	Unbekannter Modellname – siehe Modelle.
429	`rate_limited` / `token_rate_limited` / `daily_limit`	Zu viele Anfragen oder Tokens in dieser Minute (Typ `rate_limited`) oder das Tageslimit des Kontos. Kurz warten und erneut senden; das Tageslimit wird um Mitternacht (UTC) zurückgesetzt.
503	`model_unavailable`	Standard- und Fallback-Modell waren nicht verfügbar. Später erneut versuchen, mit zunehmenden Wartezeiten (Exponential Backoff).

Jede Antwort enthält den Header x-request-id – geben Sie ihn an, wenn Sie uns kontaktieren.

Datenschutz

Anfragen werden nur auf Servern in der EU verarbeitet – unser Gateway ebenso wie die Modelle.
Prompts, Dateien und Antworten werden nie gespeichert oder protokolliert, weder bei uns noch bei den Unternehmen, die die Modelle betreiben. Wir speichern nur Zählwerte: Zeit, Key, Modell, Tokens, Status.
Ihre Daten werden nie für Training verwendet.
Geschäftskunden erhalten unseren Auftragsverarbeitungsvertrag – siehe AVV & Unterauftragsverarbeiter.

Partner-API

Für Partner, die Soloniq als Teil ihres eigenen Produkts weiterverkaufen: Erstellen Sie einen Key pro Kunde, legen Sie sein Budget fest und rufen Sie die Nutzung ab – Ihre Kunden brauchen nie ein Soloniq-Konto. Einen Partner-Key (sq_partner_…) erstellen Sie in der Konsole unter Invoices & webhooks; Partnerkonten richten wir ein – sprechen Sie uns an.

Basis-URL https://api.soloniq.com/partner/v1, Header Authorization: Bearer sq_partner_…, Beträge in Euro.

Aufruf	Body / Query	Ergebnis
`POST /keys`	`name`, `customer_ref`, `models`, `monthly_budget_eur`; optional `daily_budget_eur`, `rate_limit_rpm`, `rate_limit_tpm`	der Key (`key`, einmal angezeigt) und seine `id`
`GET /keys`	optional `customer_ref`	Ihre Kunden-Keys mit Ausgaben dieses Monats (gefiltert nach Ihrer Referenz)
`GET /keys/{id}`	—	Budgets, Ausgaben im Monat und heute, Restbudget, Limits, Status, letzte Nutzung
`PATCH /keys/{id}`	beliebige Felder aus `name`, `customer_ref`, `models`, `monthly_budget_eur`, `daily_budget_eur`, `rate_limit_rpm`, `rate_limit_tpm`, `blocked` + `reason`; `null` entfernt Tagesbudget oder Token-Limit	der geänderte Key
`POST /keys/{id}/credit`	`amount_eur`	erhöht das Budget dieses Monats
`POST /keys/{id}/rotate`	—	ein neuer Key; der alte funktioniert noch 10 Minuten
`DELETE /keys/{id}`	—	der Key funktioniert nicht mehr
`GET /summary`	—	Anzahl der Keys, Gesamtausgaben dieses Monats
`GET /usage`	`from`, `to` (JJJJ-MM-TT), optional `key_id`	pro Key, Tag und Modell: Anfragen, Input-, Cached- und Output-Tokens, Fehler, Fallbacks, Kosten

curl -X POST https://api.soloniq.com/partner/v1/keys \
  -H "Authorization: Bearer $SOLONIQ_PARTNER_KEY" -H "Content-Type: application/json" \
  -d '{"name": "Kunde 1042", "customer_ref": "cust-1042",
       "models": ["agent", "agent-fast"], "monthly_budget_eur": 25, "rate_limit_rpm": 60}'

Monatsbudgets gelten pro Kalendermonat, Tagesbudgets pro Kalendertag (beide UTC). rate_limit_tpm zählt Input- und Output-Tokens pro Minute – das Limit, das zu Agenten passt, deren Kosten eher von der Kontextgröße als von der Zahl der Anfragen abhängen. Partner erhalten monatlich eine Rechnung über die Nutzung aller ihrer Kunden.

Webhooks

Hinterlegen Sie eine Webhook-URL in der Konsole. Ereignisse: usage.daily (Nutzung des Vortags pro Key, nach 02:00 UTC), key.b80 und key.b100 (Budget bei 80 % / aufgebraucht), key.blocked. Jeder Aufruf ist ein JSON-POST – {"id", "event", "created_at", "data"} –, signiert mit Ihrem Webhook-Secret. Antworten Sie innerhalb von 10 Sekunden mit einem 2xx-Status; sonst senden wir den Aufruf bis zu dreimal erneut, mit derselben id – ignorieren Sie eine id, die Sie bereits verarbeitet haben. Überschreitet eine einzelne Anfrage beide Schwellen, erhalten Sie key.b80 und key.b100.

X-Soloniq-Event: key.b80
X-Soloniq-Timestamp: 1792057830
X-Soloniq-Signature: sha256=<Hex-HMAC-SHA256 von "timestamp.body" mit Ihrem Secret>

// Node.js – Webhook prüfen
import { createHmac, timingSafeEqual } from "node:crypto";
const expected = "sha256=" + createHmac("sha256", process.env.SOLONIQ_WEBHOOK_SECRET)
  .update(`${req.headers["x-soloniq-timestamp"]}.${rawBody}`).digest("hex");
const ok = timingSafeEqual(Buffer.from(expected), Buffer.from(req.headers["x-soloniq-signature"]));

Lehnen Sie Aufrufe ab, deren Zeitstempel älter als fünf Minuten ist.

Fragen? info@zana.ai