プロンプトライブラリ

プロンプトをコードではなくワークスペースで管理します。バージョンとラベルを持ち、どの OpenAI SDK からも ID で呼び出せます。ラベルを移動すれば、次のリクエストから新しいバージョンが使われ、再デプロイは不要です。

プロンプトを呼び出す

通常の /v1/chat/completions、/v1/responses、/v1/messages のいずれかのエンドポイントを使い、リクエストボディに prompt_id と prompt_variables を追加します。SDK では model と messages が必須なので、モデル名は任意、メッセージは空の user メッセージを 1 件送ってください。OpenAI と Anthropic の SDK では追加フィールドを 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)

HTTP で直接呼ぶ場合、これらのフィールドはボディの最上位に置きます。次の呼び出しは staging ラベルが指すバージョンを使います。

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."}
  }'

フィールド

リクエストがどう変わるか

• バージョンのメッセージが先、あなたのメッセージが後に続きます。会話を続けるには自分のメッセージを送ります。それまでのターン、ツール呼び出し、ツールの結果は送ったとおりに残ります。取り除かれるのは、SDK のために送る空の user メッセージだけです。
• リクエストのモデルはバージョンのモデルに置き換わります。バージョンにモデルがなければ、あなたが指定したモデルのままです。
• あなたのパラメーターが優先されます。バージョンの temperature、max_tokens、top_p、JSON モードは、リクエストで同じパラメーターを指定していない場合にだけ使われます。
• 4 つの prompt_* フィールドはゲートウェイで取り除かれます。プロバイダーには通常のリクエストが届きます。
• /v1/responses では、メッセージは input に入り(文字列の input はあなたの user ターンになります)、max_tokens は max_output_tokens に、JSON モードは text.format になります。

/v1/messages の場合

同じ 4 つのフィールドは Anthropic SDK でも使えます。バージョンの system テキストはあなたの system の前に、バージョンのメッセージはあなたのメッセージの前に置かれ、temperature、top_p、max_tokens はリクエストで指定していない場合にだけ適用されます。このエンドポイントには JSON モードに当たるフィールドがないため、その設定は送られません。

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)

ツール呼び出しとマルチターン会話

ライブラリのプロンプトを使わない場合と同じように、tools とそれまでの会話を送ってください。システムプロンプトと最初のメッセージはバージョンが担い、モデルのツール呼び出しやツールの結果を含む残りの会話はあなたのメッセージが運びます。

# 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},
)

バージョンに含めるツールと出力スキーマ

バージョンには、関数ツール、ツールの選択方法、回答が従う JSON スキーマを含められます。これらは呼び出すエンドポイントの形式で書き出されます。リクエストで送ったツールはバージョンのツールの後ろに追加され、同じ名前のツールはリクエストのものに置き換わります。リクエスト側の tool_choice とレスポンス形式が優先されます。

パーシャル

パーシャルは、一度だけ保存して複数のプロンプトから {{>id}} で取り込めるテキストのまとまりです。プロンプトのバージョンを保存すると、取り込みはその時点のパーシャルの最新バージョンに固定され（{{>id@4}} と表示されます）、後からパーシャルを変更しても保存済みのバージョンは変わりません。新しいパーシャルのバージョンがあるとプロンプトのページに表示され、更新するとプロンプトの新しいバージョンが保存されます。パーシャル内の変数は、呼び出し時の prompt_variables で埋められます。パーシャルは単独では呼び出せず、保存済みのバージョンが取り込んでいるものは削除できません。

バージョンとラベル

保存するたびに次のバージョンが作られ、保存済みのバージョンは変更されません。どのプロンプトにも production、staging、development のラベルがあり、独自のラベルも追加できます。production をあるバージョンに向ければリリース、古いバージョンに戻せばロールバックです。コードは同じ ID を呼び続けるだけです。

ラベルの移動や削除は約 10 秒以内に呼び出しへ反映されます。ラベルの移動とプロンプトの削除には管理者またはワークスペースの所有者の権限が必要です。

下書きを試す

Prompts ページのエディタでは、左側で下書きを書き、右側でそのまま試せます。各変数に値を入れて Run を押すと、下書きがレンダリングされて設定したモデルに送られ、回答がレイテンシとコストとともに表示されます。この呼び出しは Playground の呼び出しと同じように課金・記録され、バージョンを保存するまで下書き自体は保存されません。Show the request は、モデルを呼び出さずに、各エンドポイント向けにレンダリングしたリクエストを表示します。

リリース前にバージョンをテストする

プロンプトのテストにはテストセットを保存できます。各行は変数の値で、必要に応じて user メッセージと期待する回答を付けられます。回答が満たすべきチェック（文字列を含む、パターンに一致、期待する回答と一致、有効な JSON、出力スキーマに従う、レイテンシやコストの上限、自分で書いた基準に沿ってモデルが判定）も設定できます。実行すると、選んだバージョンと比較対象のバージョンを各行で呼び出し、2 つの回答を並べて表示し、合格した行数とそれぞれのコスト・レイテンシを示します。各呼び出しは Playground の呼び出しと同じように課金・記録され、1 回の実行は 1 つのトレースにまとまります。ラベルを移動するときは、ダイアログにそのバージョンの直近の実行結果が表示されます。参考情報であり、移動をブロックはしません。テストセットと実行の回答は暗号化して保存され、回答は 30 日間保持されます。

段階的リリース

ラベルは、呼び出しの一部を別のバージョンに振り分けられます（例: 「production: v6、v7 が 10%」）。どちらのバージョンになるかはセッション ID で決まり、セッションがなければエンドユーザー、それもなければリクエスト単位で決まるため、1 つの会話は同じバージョンのままです。X-Synthorai-Prompt-Version で応答したバージョンがわかり、Prompts ページでは 2 つのバージョンを並べて比較できます。管理者は割合の変更、候補バージョンへのラベル移動、リリースの停止ができます。prompt_version でバージョンを固定した呼び出しは対象外です。

変更 Webhook

管理者は Prompts ページでアドレスを 3 件まで追加でき、プロンプトの作成、バージョンの追加、ラベルの移動、段階的リリースの変更、削除があると POST が送られます。各リクエストには署名が付きます。X-Synthorai-Signature: t=…,v1=… は、アドレス追加時に一度だけ表示されるシークレットで「タイムスタンプ、ピリオド、生のボディ」を HMAC-SHA256 したものです。バージョンのテキストは、そのアドレスでオンにした場合にのみ送信されます。配信に失敗すると約 30 分かけてさらに 3 回再試行し、5 件続けて断念するとアドレスは停止され、再度オンにするまで送信されません。

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

インポート、エクスポート、OpenAI の保存済みプロンプト

新しいプロンプト › インポートでは、貼り付けた Chat Completions / Responses のリクエストボディ、または LiteLLM の .prompt ファイルを最初のバージョンとして読み込みます（メッセージ、モデル、パラメーター、ツール、出力スキーマ）。プロンプトのエクスポートは、すべてのバージョンを含む 1 つの JSON ファイルをダウンロードし、同じ方法でインポートできます。ワークスペースにコピーは、所属している別のワークスペースにコピーします。OpenAI の保存済みプロンプトは 2026-11-30 に停止し、取り出すこともできません。ここで同じ pmpt_… の ID でプロンプトを作り直せば、その ID の prompt を送る /v1/responses リクエストはコードを変えずにライブラリから応答されます。version が数値ならライブラリのそのバージョン、指定がなければ production が使われます。

モデルを呼び出さずにレンダリングする

POST /v1/prompts/{id}/render は、モデルを呼び出さずに、呼び出し時に送られるリクエストと解決されたバージョンを返します。prompt_variables と、必要に応じて prompt_version または prompt_label、そして format(chat(既定)、responses、messages のいずれか)を送ります。課金されず、Logs にも表示されませんが、キーのレート制限には数えられます。あるバージョンが実際に何を送るかの確認や、prompt_* フィールドに対応していないエンドポイントを呼び出すときに使えます。

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."}
    ]
  }
}

レスポンスヘッダー

X-Synthorai-Prompt-Version は、どのバージョンが応答したかを示します。ラベルで呼び出した場合、これ以外に知る方法はありません。ライブラリを読み取れないとき、ゲートウェイは最後に読み取ったコピーで最長 24 時間応答し、X-Synthorai-Prompt-Stale: 1 を付けます。その間に移動したラベルは、ライブラリが再び読めるようになってから反映されます。

エラー

これらはモデルを呼び出す前に返されるため、課金されることはありません。エラーの形式は呼び出したエンドポイントに従います。

バージョン別の統計

呼び出しごとに、使われたプロンプトとバージョンが記録されます。Prompts ページでは、直近 7 日・30 日・90 日のいずれかについて、バージョンごとの呼び出し数、エラー数、利用額、トークン、レイテンシ、最初のトークンまでの時間を確認でき、呼び出し数をクリックするとその呼び出しが Logs で開きます。新しいバージョンを staging で production と並行して動かし、比較してから production を移動してください。

Logs では prompt = support-reply と prompt_version = 7 で絞り込めます。リクエストの詳細には、使われたプロンプトとバージョンが表示されます。エクスポートされるレコードにも含まれ、ファイルと webhook では run.prompt_id と run.prompt_version、OTLP スパンでは gen_ai.prompt.name と gen_ai.prompt.version です。

関連項目: プロンプト · Chat Completions · Responses API