Prompt-Bibliothek

Prompts liegen im Workspace statt im Code: versioniert, mit Labels und per ID aus jedem OpenAI-SDK aufrufbar. Wenn Sie ein Label verschieben, bekommt Ihr Code ab der nächsten Anfrage die neue Version, ganz ohne Redeploy.

Einen Prompt aufrufen

Verwenden Sie den gewohnten Endpunkt /v1/chat/completions, /v1/responses oder /v1/messages und ergänzen Sie im Body prompt_id und prompt_variables. Die SDKs verlangen model und messages: Geben Sie einen beliebigen Modellnamen und eine leere User-Nachricht an. In den SDKs von OpenAI und Anthropic gehören die zusätzlichen Felder in extra_body.

import os
from openai import OpenAI

client = OpenAI(base_url="https://synthorai.io/v1", api_key=os.environ["SYNTHORAI_API_KEY"])

reply = client.chat.completions.create(
    model="any",  # the version's model is used
    messages=[{"role": "user", "content": ""}],  # required by the SDK; dropped
    extra_body={
        "prompt_id": "support-reply",
        "prompt_variables": {
            "product": "Acme Cloud",
            "customer_message": "My invoice shows two charges.",
        },
    },
)
print(reply.choices[0].message.content)

Bei reinem HTTP stehen die Felder auf oberster Ebene des Bodys. Dieser Aufruf fordert die Version an, auf die das Label staging zeigt:

curl https://synthorai.io/v1/chat/completions \
  -H "Authorization: Bearer $SYNTHORAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "any",
    "messages": [],
    "prompt_id": "support-reply",
    "prompt_label": "staging",
    "prompt_variables": {"product": "Acme Cloud", "customer_message": "My invoice shows two charges."}
  }'

Felder

Was aus der Anfrage wird

• Zuerst die Nachrichten der Version, dann Ihre. Mit Ihren eigenen Nachrichten geht ein Gespräch weiter: frühere Runden, Tool-Aufrufe und Tool-Ergebnisse bleiben so, wie Sie sie senden. Nur die leere User-Nachricht, die die SDKs verlangen, fällt weg.
• Das Modell der Version ersetzt das der Anfrage. Hat die Version kein Modell, bleibt Ihres.
• Ihre Parameter haben Vorrang. temperature, max_tokens, top_p und JSON-Modus der Version gelten nur, wenn Ihre Anfrage denselben Parameter nicht setzt.
• Die vier Felder prompt_* enden am Gateway. Der Anbieter erhält eine gewöhnliche Anfrage.
• Bei /v1/responses landen die Nachrichten in input (ein String-Input ist Ihre User-Runde), aus max_tokens wird max_output_tokens und aus dem JSON-Modus text.format.

Mit /v1/messages

Dieselben vier Felder funktionieren auch mit dem Anthropic-SDK. Der Systemtext der Version steht vor Ihrem eigenen system, ihre Nachrichten stehen vor Ihren, und temperature, top_p und max_tokens gelten dort, wo Ihre Anfrage sie nicht setzt. Für den JSON-Modus gibt es an diesem Endpunkt kein Feld; er wird weggelassen.

import os
from anthropic import Anthropic

client = Anthropic(base_url="https://synthorai.io", api_key=os.environ["SYNTHORAI_API_KEY"])

reply = client.messages.create(
    model="any",  # the version's model is used
    max_tokens=1024,
    messages=[{"role": "user", "content": ""}],  # required by the SDK; dropped
    extra_body={
        "prompt_id": "support-reply",
        "prompt_variables": {
            "product": "Acme Cloud",
            "customer_message": "My invoice shows two charges.",
        },
    },
)
print(reply.content[0].text)

Tool-Aufrufe und Gespräche über mehrere Runden

Senden Sie tools und das bisherige Gespräch genau so wie ohne Bibliotheks-Prompt. Die Version liefert den System-Prompt und die erste Nachricht; Ihre Nachrichten tragen den Rest des Gesprächs, einschließlich der Tool-Aufrufe des Modells und Ihrer Tool-Ergebnisse.

# Round 2 of a tool loop: send the conversation so far, as without a prompt.
# The gateway puts the version's messages first and these after them.
reply = client.chat.completions.create(
    model="any",
    tools=tools,
    messages=[
        {"role": "user", "content": ""},  # the SDK placeholder, dropped
        first.choices[0].message,           # the model's tool call
        {"role": "tool", "tool_call_id": call.id, "content": lookup_invoice(call)},
    ],
    extra_body={"prompt_id": "support-reply", "prompt_variables": variables},
)

Tools und Ausgabeschema in einer Version

Eine Version kann Function-Tools, eine Tool-Auswahl und ein JSON-Schema für die Antwort enthalten; sie werden im Format des aufgerufenen Endpunkts geschrieben. Tools aus Ihrer Anfrage werden nach denen der Version angefügt, und ein Tool gleichen Namens ersetzt das der Version. Ihr eigenes tool_choice und Ihr Antwortformat haben Vorrang.

Partials

Ein Partial ist ein Textblock, der einmal gespeichert und mit {{>id}} in Prompts eingebunden wird. Beim Speichern einer Prompt-Version wird jede Einbindung auf die neueste Version des Partials festgelegt und als {{>id@4}} angezeigt; eine gespeicherte Version ändert sich also nicht, wenn sich das Partial ändert. Die Seite des Prompts zeigt an, wenn es eine neuere Partial-Version gibt, und bietet die Aktualisierung an, die eine neue Version des Prompts speichert. Die Variablen eines Partials werden aus den prompt_variables des Aufrufs gefüllt. Ein Partial lässt sich nicht einzeln aufrufen, und eines, das gespeicherte Versionen einbinden, lässt sich nicht löschen.

Versionen und Labels

Jedes Speichern erzeugt die nächste Version, und eine gespeicherte Version ändert sich nie. production, staging und development gibt es bei jedem Prompt; eigene Labels lassen sich ergänzen. Setzen Sie production auf eine Version, um sie auszuliefern, und zurück auf die alte für einen Rollback. Ihr Code ruft weiter dieselbe ID auf.

Ein verschobenes Label oder ein gelöschter Prompt wirkt nach etwa 10 Sekunden auf die Aufrufe. Labels verschieben und Prompts löschen dürfen Admins und der Workspace-Eigentümer.

Einen Entwurf ausprobieren

Im Editor auf der Prompts-Seite steht links der Entwurf, rechts probieren Sie ihn aus. Geben Sie jeder Variable einen Wert und klicken Sie auf Run: Der Entwurf wird gerendert und an sein Modell geschickt, die Antwort erscheint mit Latenz und Kosten. Der Aufruf wird wie ein Playground-Aufruf abgerechnet und protokolliert, und vom Entwurf wird nichts gespeichert, bis Sie die Version speichern. Show the request zeigt die gerenderte Anfrage für jeden Endpunkt, ohne ein Modell aufzurufen.

Eine Version vor der Freigabe testen

Unter Tests hält ein Prompt Testsets: Zeilen mit Werten für seine Variablen, optional mit einer User-Nachricht und einer erwarteten Antwort, sowie die Prüfungen, die eine Antwort bestehen muss (enthält, entspricht einem Muster, entspricht der erwarteten Antwort, gültiges JSON, folgt dem Ausgabeschema, Obergrenze für Latenz oder Kosten oder ein Modell, das nach einem von Ihnen formulierten Kriterium bewertet). Ein Lauf ruft für jede Zeile die gewählte Version und die Vergleichsversion auf, zeigt beide Antworten nebeneinander und nennt, wie viele Zeilen bestanden haben, sowie Kosten und Latenz je Version. Jeder Aufruf wird wie ein Playground-Aufruf berechnet und protokolliert, unter einem Trace pro Lauf. Wenn Sie ein Label verschieben, zeigt der Dialog den letzten Lauf der Version; er informiert und blockiert nicht. Testsets und die Antworten eines Laufs werden verschlüsselt gespeichert; Antworten bleiben 30 Tage erhalten.

Schrittweise Einführung

Ein Label kann einen Teil seiner Aufrufe an eine andere Version senden: „production: v6, v7 mit 10 %“. Welche Version ein Aufruf erhält, entscheidet seine Sitzungs-ID, ohne Sitzung der Endnutzer, sonst die einzelne Anfrage; ein Gespräch bleibt also bei einer Version. X-Synthorai-Prompt-Version nennt die Version, die geantwortet hat, und die Seite Prompts zeigt beide nebeneinander. Ein Admin ändert den Anteil, verschiebt das Label auf die Kandidatenversion oder stoppt die Einführung; ein Aufruf mit festem prompt_version gehört nie dazu.

Änderungs-Webhooks

Admins können auf der Seite Prompts bis zu drei Adressen hinzufügen, die einen POST erhalten, wenn ein Prompt erstellt wird, eine Version erhält, ein Label verschoben oder eine Einführung geändert wird oder er gelöscht wird. Jede Anfrage ist signiert: X-Synthorai-Signature: t=…,v1=…, der HMAC-SHA256 über Zeitstempel, Punkt und Rohdaten des Bodys, mit dem Geheimnis, das beim Hinzufügen der Adresse einmalig angezeigt wird. Der Text einer Version wird nur gesendet, wenn Sie das für die Adresse einschalten. Eine fehlgeschlagene Zustellung wird innerhalb von etwa einer halben Stunde noch dreimal versucht; nach fünf aufgegebenen Ereignissen in Folge wird die Adresse abgeschaltet, bis Sie sie wieder einschalten.

POST /hooks/prompts
X-Synthorai-Event: prompt.label_moved
X-Synthorai-Signature: t=1791140000,v1=5f2c…

{
  "type": "prompt.label_moved",
  "created_at": "2026-10-05T03:12:44Z",
  "prompt": "support-reply",
  "kind": "prompt",
  "label": "production",
  "from": 6,
  "version": 7,
  "by": 42
}

# Verify: hex(HMAC-SHA256(secret, "1791140000" + "." + raw_body)) == v1

Import, Export und die gespeicherten Prompts von OpenAI

Neuer Prompt › Importieren liest einen eingefügten Chat-Completions- oder Responses-Request-Body oder eine .prompt-Datei von LiteLLM als erste Version ein: Nachrichten, Modell, Parameter, Tools und Ausgabeschema. Exportieren lädt einen Prompt mit allen Versionen als eine JSON-Datei herunter, die sich genauso importieren lässt, und In einen Workspace kopieren kopiert ihn in einen anderen Workspace, in dem Sie Mitglied sind. Die gespeicherten Prompts von OpenAI funktionieren ab dem 2026-11-30 nicht mehr und lassen sich nicht auslesen: Legen Sie den Prompt hier unter seiner pmpt_…-ID neu an, dann wird eine /v1/responses-Anfrage, die prompt mit dieser ID sendet, ohne Codeänderung aus der Bibliothek bedient. Ist version eine Zahl, wählt sie diese Bibliotheksversion; ohne sie erhält der Aufruf production.

Rendern, ohne ein Modell aufzurufen

POST /v1/prompts/{id}/render liefert die Anfrage, die ein Aufruf senden würde, samt der aufgelösten Version, ohne ein Modell aufzurufen. Senden Sie prompt_variables, optional prompt_version oder prompt_label, und format: chat (Standard), responses oder messages. Der Aufruf wird nicht berechnet und erscheint nicht in Logs; er zählt zum Rate-Limit des Schlüssels. So prüfen Sie, was eine Version sendet, oder rufen einen Endpunkt auf, den die prompt_*-Felder nicht erreichen.

curl https://synthorai.io/v1/prompts/support-reply/render \
  -H "Authorization: Bearer $SYNTHORAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "format": "chat",
    "prompt_variables": {"product": "Acme Cloud", "customer_message": "My invoice shows two charges."}
  }'

{
  "prompt_id": "support-reply",
  "version": 6,
  "format": "chat",
  "request": {
    "model": "claude-sonnet-5",
    "temperature": 0.3,
    "messages": [
      {"role": "system", "content": "You answer billing mail for Acme Cloud."},
      {"role": "user", "content": "My invoice shows two charges."}
    ]
  }
}

Antwort-Header

X-Synthorai-Prompt-Version nennt die Version, die geantwortet hat; bei einem Aufruf per Label erfahren Sie das sonst nicht. Ist die Bibliothek nicht lesbar, antwortet das Gateway bis zu 24 Stunden lang aus der zuletzt gelesenen Kopie und ergänzt X-Synthorai-Prompt-Stale: 1; ein in der Zwischenzeit verschobenes Label wirkt, sobald die Bibliothek wieder lesbar ist.

Fehler

Diese Fehler kommen, bevor ein Modell aufgerufen wird, und werden daher nie berechnet. Sie haben das Fehlerformat des aufgerufenen Endpunkts.

Statistik je Version

Jeder Aufruf wird mit dem Prompt und der Version aufgezeichnet, die er verwendet hat. Die Seite Prompts zeigt pro Version Aufrufe, Fehler, Ausgaben, Tokens, Latenz und die Zeit bis zum ersten Token für die letzten 7, 30 oder 90 Tage; die Zahl der Aufrufe einer Version öffnet diese Aufrufe in Logs. Lassen Sie eine neue Version unter staging neben production laufen und vergleichen Sie beide, bevor Sie production verschieben.

In Logs filtern Sie mit prompt = support-reply und prompt_version = 7; die Detailansicht einer Anfrage nennt Prompt und Version. Exportierte Datensätze enthalten beides ebenfalls: run.prompt_id und run.prompt_version in Dateien und Webhooks, gen_ai.prompt.name und gen_ai.prompt.version an OTLP-Spans.

Siehe auch: Prompts · Chat Completions · Responses API