Raw-Prompt-Modus

Senden Sie einen benutzerdefinierten System-/User-Prompt direkt an das Modell statt an eine benannte Pipeline — Anfrageform, Modellauswahl und die Einschränkungen, die für benannte Pipelines nicht gelten.

Jede andere Anleitung in diesem Abschnitt ruft eine benannte Pipeline auf (translate-string, summarize usw.) — eine feste Prompt-Vorlage mit deklarierten Eingaben. Raw mode überspringt die Vorlage: Sie senden Ihren eigenen system_prompt und user_prompt direkt, und die Plattform führt ihn unverändert aus. Verwenden Sie es, um einen Prompt zu prototypisieren, bevor es sich lohnt, ihn zu einer echten Pipeline zu machen, oder für einen einmaligen Aufruf, der in keines der eingebauten Tools passt.

Aktivierung

Raw mode wird getrennt von benannten Pipelines freigeschaltet. Die pipelines[]-Claim Ihres JWT benötigt einen expliziten "raw"-Eintrag — dieselbe Claim, die für benannte Pipeline-IDs verwendet wird, nur mit diesem einen zusätzlichen String. Er wird nicht standardmäßig gewährt, und die meisten Endnutzer-Session-Tokens sollten ihn niemals haben: Die Kosten einer benannten Pipeline sind durch ihre Vorlage begrenzt, aber die Kosten eines Raw-Prompts sind nur dadurch begrenzt, wie lang ein Prompt Sie zu senden bereit sind und wie viele Tokens Sie das Modell generieren lassen.

Wenn Ihre App selbst Session-Tokens erstellt (siehe den Abschnitt POST /auth/token in Node.js server integration), fordern Sie "raw" nur für die spezifischen Tokens an, die es benötigen — z. B. ein internes Admin-Tool, nicht Tokens, die beliebigen Endnutzern ausgehändigt werden. Bitten Sie Ihren Plattformbetreiber zu bestätigen, dass allowed_pipelines Ihrer Application "raw" enthält, bevor Sie ein Token mit dieser Claim anfordern; eine Claim, die Ihre Application nicht gewähren darf, wird stillschweigend aus dem ausgestellten Token entfernt.

Ein statischer x-api-key (ungebunden, Operator-Scope — siehe Holen Sie sich Ihren API-Schlüssel) umgeht die Pipeline-Listen-Prüfung vollständig, genau wie bei benannten Pipelines. Ein über die Console ausgestellter, App-gebundener x-api-key und ein JWT-/Webtoken-Aufrufer benötigen beide die explizite "raw"-Freigabe.

Aufruf — SDK

const out = await ai.run({
  raw: {
    system_prompt: "You are a terse assistant. Answer in one sentence.",
    user_prompt: "What does raw mode skip that a named pipeline has?",
    model: "gpt-5-mini",   // optional — see "Choosing a model" below
    temperature: 0.2,       // optional
    max_tokens: 500,        // optional, up to 32768
  },
});
console.log(out.text);

user_prompt kann auch eine Funktion von inputs sein, wenn zusammen mit ai.runMany(...) verwendet — siehe den ausführlicheren Integration Guide des SDK (fragen Sie Ihren Plattformbetreiber nach einer Kopie — er ist nicht öffentlich) für dieses Muster. ai.button(...) akzeptiert ebenfalls eine raw-Konfiguration anstelle von pipeline.

Aufruf — direktes HTTP

Erfordert Authorization: Bearer <jwt> mit der "raw"-Freigabe (ein statischer x-api-key funktioniert ebenfalls, sofern es sich um die ungebundene Operator-Art handelt — siehe oben). params ist optional, und beide Felder darin sind optional:

curl -X POST "https://api.quravin.com/tickets" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your-jwt>" \
  -d '{
    "mode": "raw",
    "system_prompt": "You are a terse assistant. Answer in one sentence.",
    "user_prompt": "What does raw mode skip that a named pipeline has?",
    "model": "gpt-5-mini",
    "params": { "temperature": 0.2, "max_tokens": 500 }
  }'

Antwort (202), dann genauso pollen wie bei jedem anderen Ticket — siehe Direkte API-Integration, falls Sie diese Schleife noch nicht gebaut haben:

{ "ticket_id": "01J...ULID", "status": "QUEUED" }

curl "https://api.quravin.com/tickets/01J...ULID" \
  -H "Authorization: Bearer <your-jwt>"

Antwort nach Abschluss — die Form besteht immer aus denselben vier Feldern plus text, unabhängig davon, welches Modell sie ausgeführt hat:

{
  "ticket_id": "01J...ULID",
  "status": "DONE",
  "mode": "raw",
  "result": {
    "text": "It skips the fixed prompt template and declared input schema.",
    "model": "gpt-5-mini",
    "latency_ms": 640,
    "tokens_in": 38,
    "tokens_out": 14
  },
  "created_at": "2026-07-10T12:00:00.000Z",
  "updated_at": "2026-07-10T12:00:02.000Z"
}

Es gibt kein Pipeline-spezifisches Feld nachzuschlagen (kein translation, kein tldr) — result.text ist immer der Ort, an dem die Modellausgabe landet.

Modellauswahl

model ist optional — weglassen, um den aktuellen Standard der Plattform zu verwenden. Wenn Sie es explizit setzen, muss es eines sein, für das die Plattform eine verifizierte Kostenrate hat, geprüft bevor der Aufruf das LLM erreicht: Senden Sie etwas anderes, erhalten Sie 400 invalid_model statt einer teuren Überraschung. Zum Zeitpunkt dieses Schreibens ist diese Liste gpt-4o-mini, gpt-4o, o3 und gpt-5-mini — fragen Sie Ihren Plattformbetreiber nach der aktuellen Liste, da sie sich ändert, sobald Modelle hinzugefügt werden.

Was sich von einer benannten Pipeline unterscheidet

Kein Eingabeschema. Eine benannte Pipeline validiert Ihre inputs gegen ihr deklariertes Schema, bevor der Aufruf akzeptiert wird (fehlendes Feld, falscher Typ → 400). Raw mode hat kein Schema — system_prompt und user_prompt sind erforderliche Strings, aber ihr Inhalt wird niemals validiert. Ein Prompt, der für das Modell keinen Sinn ergibt, schlägt nicht im Voraus fehl; das Ticket läuft, und Sie erfahren es erst beim Pollen des Ergebnisses.
Kein Caching. Benannte Pipelines cachen identische Aufrufe anhand ihrer Eingaben. Raw mode prüft niemals einen Cache — jeder Aufruf ist jedes Mal ein frischer Modellaufruf, selbst wenn Sie genau denselben Prompt zweimal hintereinander senden.
Der globale Eingabegrößen-Backstop gilt weiterhin, nur anders gemessen: `system_prompt.length
- user_prompt.lengthzusammen müssen unter der Zeichenobergrenze der Plattform bleiben (standardmäßig 50.000) — dieselbe Defense-in-Depth-Grenze, dieinputs` bei benannten Pipelines begrenzt, nur über die beiden Felder statt über den gesamten JSON-Body aufsummiert.
max_tokens ist auf 32768 begrenzt, unabhängig davon, was das zugrunde liegende Modell ansonsten erlauben würde — eine Obergrenze für den Worst Case eines einzelnen Aufrufs, kein Zielwert, den man anstreben sollte.

Fehler

Dieselbe Fehlertabelle für den authentifizierten Pfad wie bei jedem anderen Aufruf — siehe Direkte API-Integration für die vollständige Liste. Ein Fehler ist spezifisch für Raw mode: 400 invalid_model, oben behandelt.

Wenn Ihr JWT die "raw"-Freigabe nicht trägt, erhalten Sie denselben 403 wie beim Aufruf einer benannten Pipeline, die Sie nicht verwenden dürfen — siehe Wählen Sie Ihren Auth-Modus dafür, wie Zugangsdaten-Freigaben funktionieren.