PrimaAPI

Schlüssel tragen genau einen Scope: ai. Damit erreichen sie den Gateway unter /api/prima/v1/ und sonst nichts — kein anderer Teil der Plattform ist damit ansprechbar. Ein Prima-Schlüssel kann insbesondere keine weiteren Schlüssel ausstellen; das geht nur angemeldet, hier im Portal.

OpenAI-Kompatibilität

Die Endpunkte /chat/completions, /embeddings und /models haben die Form, die OpenAI-Clients erwarten. Sie behalten Ihr SDK, Ihre Typen und Ihre Retry-Logik. Zwei Änderungen genügen:

1. base_url auf https://api.prima.li/api/prima/v1.
2. X-API-Key als Default-Header setzen. Den Authorization-Header des SDKs können Sie stehen lassen.

Mehr ist es nicht. Beide Schnellstarts oben sind genau in dieser Form gegen die Live-API ausgeführt worden.

Was gleich ist

• Request- und Response-Form inklusive usage.
• messages, temperature, max_tokens.
• tools und tool_choice werden durchgereicht.
• Das Feld model in der Antwort enthält immer den Alias, den Sie geschickt haben — nie einen internen Modellnamen.

Was anders ist

• Streaming funktioniert. stream: true liefert einen gewöhnlichen SSE-Strom aus chat.completion.chunk-Objekten, abgeschlossen mit data: [DONE]. Details unter Streaming.
• Ein Zusatzfeld prima in jeder Antwort, mit alias und request_id. OpenAI-Clients ignorieren unbekannte Felder, es bricht also nichts.
• Andere Modellnamen. Vier Aliase, nach Aufgabe benannt: prima-quick, prima-core, prima-deep, prima-embed.

Chat Completions

POST https://api.prima.li/api/prima/v1/chat/completions

Der prima-Block

Jede Antwort trägt ihn. request_id ist die Nummer, die Sie uns bei einer Rückfrage nennen — sie steht auch im Zähler, ohne dass dort je ein Inhalt gespeichert würde.

Bei prima-deep kann er zusätzlich max_tokens_floor_applied enthalten. Das Modell denkt vor dem Antworten, und mit einem knappen Limit bricht es mitten im Denken ab und liefert null Zeichen. Statt das zu tun, hebt der Gateway das Limit auf 8000 an und schreibt es in die Antwort:

"prima": {
  "alias": "prima-deep",
  "request_id": "primaapi_5202820bd9214f56a10a344b6064bf3b",
  "max_tokens_floor_applied": true,
  "requested_max_tokens": 1000,
  "effective_max_tokens": 8000
}

Was das für die Rechnung bedeutet, steht unter Tokens & Abrechnung — mit gemessenen Zahlen.

Embeddings

POST https://api.prima.li/api/prima/v1/embeddings — input ist ein String oder ein Array von Strings.

curl https://api.prima.li/api/prima/v1/embeddings \
  -H "X-API-Key: $PRIMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "prima-embed",
    "input": ["Vertragsklausel A", "Vertragsklausel B"]
  }'

{
  "object": "list",
  "model": "prima-embed",
  "data": [
    { "object": "embedding", "index": 0, "embedding": [1.359375, -1.84375, … 3584 Werte] },
    { "object": "embedding", "index": 1, "embedding": [0.76953125, -2.15625, … 3584 Werte] }
  ],
  "prima": {
    "alias": "prima-embed",
    "request_id": "primaapi_38d2ac0d2c1840dab8ba20d453d63b84",
    "request_count": 2
  }
}

Die Vektoren haben 3584 Dimensionen. Embeddings werden pro Anfrage gezählt, nicht pro Token — ein Array mit zwei Strings sind zwei Anfragen, wie request_count in der Antwort zeigt. Der Zähler spiegelt damit exakt, wie unser Vorlieferant abrechnet; eine eigene Kunstwährung gibt es nicht.

Modelle auflisten

curl https://api.prima.li/api/prima/v1/models -H "X-API-Key: $PRIMA_API_KEY"

Acht Einträge: vier gleitende Aliase und zu jedem ein festgeschriebenes Gegenstück. Jeder Eintrag beschreibt sich selbst über prima_kind, prima_floating und prima_pinned_variant — bauen Sie Ihre Auswahl auf diesen Feldern auf, nicht auf einer Liste von Namen in Ihrem Code. Zur Modellreferenz.

Tokens & Abrechnung

prima-deep denkt, bevor es antwortet. Diese Denkschritte sind Tokens, sie werden abgerechnet, und sie stehen nicht in der Antwort. Damit das Modell nicht mitten im Denken abgeschnitten wird und Sie für eine unbrauchbare Antwort zahlen, hebt der Gateway max_tokens auf einen Mindestwert an — und sagt Ihnen das im prima-Block.

Sechs Aufrufe vom 3. August 2026, alle mit derselben Frage „Antworte nur mit: ja“:

Zwei Tokens gegen dreihundert, für dieselbe Antwort. Wenn Sie prima-deep einsetzen, dann für Aufgaben, bei denen das Nachdenken den Preis wert ist — nicht als Standardmodell. Wofür welcher Alias gedacht ist, steht in der Modellreferenz.

Ob der Gateway eingegriffen hat, steht in jeder Antwort — im prima-Block als max_tokens_floor_applied. Prüfen Sie im Zweifel den, statt aus max_tokens auf die Kosten zu schliessen; das Feld ist oben unter OpenAI-Kompatibilität abgedruckt.

Was daraus folgt, ganz nüchtern:

• max_tokens ist keine Kostenbremse. Es begrenzt die sichtbare Ausgabe, nicht das Denken davor. Im Beispiel oben werden bei einem Limit von 16 gemessene 115 Tokens abgerechnet.
• Rechnen Sie mit dem, was usage zurückgibt, nicht mit einer Schätzung aus Ihrem Prompt. Der Wert steht in jeder Antwort.
• Kurze Antworten sind nicht billig. Ein Klassifikator, der ein Wort zurückgibt, kostet dreistellig Tokens pro Aufruf. Bei zehntausend Aufrufen am Tag ist das die Zahl, die zählt.
• Die harte Grenze ist Ihr Guthaben, nicht ein Tarif. Ist es aufgebraucht, lehnt der Gateway neue Arbeit ab, statt weiterzurechnen und hinterher zu belasten. Sie können zusätzlich ein eigenes Monatslimit setzen — Ausgabenlimit.

Was gezählt wird — und was nicht

Der Zähler kennt Zeitpunkt, Alias, internes Modell, Token- und Anfragezahlen sowie die request_id. Inhalte kennt er nicht. Es gibt in der Zählertabelle keine Spalte, in der ein Prompt oder eine Antwort landen könnte — auch nicht versehentlich. Deshalb kann Ihr Verbrauch Ihnen zeigen, wie viel Sie verbraucht haben, und nicht, was Sie geschrieben haben. Das ist keine fehlende Funktion, das ist die Zusage.

Fehler & Grenzen

Form einer Fehlerantwort

Fehler sind OpenAI-förmig: ein Objekt unter error, nicht ein String und nicht detail. Wer die Meldung auslesen will, liest error.message; wer verzweigen will, verzweigt auf error.code.

{
  "error": {
    "message": "Missing credentials",
    "type": "authentication_error",
    "param": null,
    "code": "AUTH_001",
    "request_id": "6e80a491-8385-46c6-85d5-48663b76af4c"
  }
}

request_id ist in jeder Antwort enthalten, auch im Fehlerfall. Nennen Sie sie, wenn Sie uns schreiben.

Leeres input

{
  "error": {
    "message": "`input` must be non-empty",
    "type": "invalid_request_error",
    "param": null,
    "code": "SRV_001",
    "request_id": "723bf49f-dd28-479c-bec0-bcdace8ba229"
  }
}

Statuscodes

Unbekannter Alias

Der Fehler listet auf, was gültig gewesen wäre:

{
  "error": {
    "message": "Unknown PrimaAPI model alias 'prima-turbo'. Valid: ['prima-core', 'prima-core-2026-08', 'prima-deep', 'prima-deep-2026-08', 'prima-quick', 'prima-quick-2026-08']",
    "type": "invalid_request_error",
    "param": null,
    "code": "SRV_001",
    "request_id": "c8a7303a-c65a-498a-9353-28c6e513634c"
  }
}

Streaming

stream: true wird unterstützt. Der Gateway antwortet mit einem gewöhnlichen SSE-Strom aus chat.completion.chunk-Objekten und schliesst mit data: [DONE] ab. Das offizielle OpenAI-SDK iteriert ihn ohne Sonderbehandlung — dieselben zwei Zeilen Konfiguration wie oben genügen.

const stream = await client.chat.completions.create({
  model: "prima-core",
  messages: [{ role: "user", content: "Zaehle von 1 bis 5." }],
  max_tokens: 100,
  stream: true,
});

for await (const chunk of stream) {
  const delta = chunk.choices[0]?.delta?.content;
  if (delta) process.stdout.write(delta);
}

ausgeführt gegen die Live-API, openai 7.3.0 auf Node v22.22.2

Hier ist die Zählung von 1 bis 5:

1. eins
2. zwei
3. drei
4. vier
5. fünf

Weitere Grenzen, offen benannt

• Early Access. PrimaAPI läuft, ist aber nicht allgemein verfügbar. Zugang bekommt man auf Anfrage.
• Kein Requests-pro-Sekunde-Limit. Verbrauchsgrenzen sind derzeit die einzige Verkehrssteuerung. Bauen Sie in Ihrem Client trotzdem ein Backoff ein.
• Keine ISO-27001-Zertifizierung. Wir arbeiten darauf hin, halten sie aber nicht. Was wir zusagen, ist der Ort der Verarbeitung und ein unterschreibbarer Auftragsverarbeitungsvertrag — nicht ein Zertifikat, das wir nicht haben.

Wenn etwas fehlt

Schreiben Sie an prima@alchemy.zuerich und nennen Sie die request_id. Wir sehen damit den Aufruf im Zähler — Zeitpunkt, Alias, Grösse. Ihren Prompt sehen wir nicht, und das können wir auch dann nicht ändern, wenn Sie uns darum bitten.

Alle Beispiele und Zahlen auf dieser Seite gegen die Live-API geprüft am 3. August 2026.