提示詞庫

把提示詞放在工作區裡,而不是寫死在程式碼裡:有版本、有標籤,任何 OpenAI SDK 都能依 ID 呼叫。移動一個標籤,你的程式碼下一次請求拿到的就是新版本,不必重新部署。

呼叫提示詞

使用一般的 /v1/chat/completions、/v1/responses 或 /v1/messages 端點,在請求內容裡加上 prompt_id 和 prompt_variables。SDK 規定必須有 model 和 messages:模型名稱隨意填,訊息傳一則空的 user 訊息即可。在 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 模式,只在你的請求沒設同一個參數時才生效。
• 四個 prompt_* 欄位到閘道為止。供應商收到的是一個一般請求。
• 在 /v1/responses 上,訊息寫進 input(字串形式的 input 視為你的 user 訊息),max_tokens 變成 max_output_tokens,JSON 模式變成 text.format。

在 /v1/messages 上

同樣的四個欄位也能搭配 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},
)

版本裡的工具和輸出 schema

版本裡可以儲存函式工具、工具選擇方式和回答要遵循的 JSON schema，呼叫時會依你使用的端點格式寫出。請求自帶的工具排在版本的工具之後；同名時以請求的為準。請求自己的 tool_choice 和回應格式優先。

片段（Partials）

片段是一段只儲存一份、可被多個提示詞用 {{>id}} 引用的文字。儲存提示詞版本時，每個引用都會固定到片段當時的最新版本，顯示為 {{>id@4}}，所以片段之後再改，已儲存的版本也不會變。片段有了更新的版本時，提示詞頁面會提示並提供更新入口，更新會替提示詞儲存一個新版本。片段裡的變數由呼叫時的 prompt_variables 填入。片段不能單獨呼叫；仍被已儲存版本引用的片段不能刪除。

版本與標籤

每次儲存都會產生下一個版本,已儲存的版本不會再改。每個提示詞都有 production、staging 和 development 三個標籤,你也可以加自己的標籤。把 production 指向某個版本就是上線,指回舊版本就是回復,你的程式碼一直呼叫同一個 ID。

移動標籤或刪除提示詞後,大約 10 秒內對呼叫生效。移動標籤和刪除提示詞需要管理員或工作區擁有者。

試跑草稿

Prompts 頁面的編輯器左邊寫草稿，右邊可以直接試。替每個變數填一個值，按Run：草稿渲染後送給它設定的模型，回答連同延遲和成本一起顯示。這次呼叫按 Playground 呼叫計費並記入日誌；在你儲存版本之前，草稿本身不會被儲存。Show the request 只顯示各端點渲染後的請求，不呼叫模型。

上線前測試一個版本

提示詞的測試裡可以儲存測試集：每一列是一組變數值，可以附帶一則 user 訊息和期望答案；還可以設定回答必須通過的檢查項（包含某段文字、符合正規表示式、等於期望答案、是合法 JSON、符合輸出 schema、延遲或成本上限，或由模型依你寫的標準評審）。執行時，會對每一列分別呼叫你選的版本和比對版本，把兩個回答並排顯示，並列出通過的列數以及各自的成本和延遲。每次呼叫都按 Playground 呼叫計費並記入日誌，一次執行歸在同一個 trace 下。移動標籤時，對話框會顯示該版本最近一次執行的結果，僅供參考，不會攔截。測試集和執行得到的回答都加密儲存，回答保留 30 天。

漸進式發布

一個標籤可以把一部分呼叫分給另一個版本，例如「production：v6，v7 占 10%」。一次呼叫落在哪個版本，依它的 session id 決定；沒有 session 時依終端使用者，再沒有就依單次請求，所以同一段對話始終使用同一個版本。X-Synthorai-Prompt-Version 會告訴你實際回應的版本，Prompts 頁面會並排顯示兩個版本的數據。管理員可以調整占比、把標籤移到候選版本，或停止漸進式發布；用 prompt_version 指定版本的呼叫不參與漸進式發布。

變更 webhook

管理員可以在 Prompts 頁面新增最多三個位址。提示詞被建立、儲存新版本、標籤移動、漸進式發布變更或被刪除時，這些位址會收到一次 POST。每個請求都帶簽章：X-Synthorai-Signature: t=…,v1=…，也就是用新增位址時只顯示一次的密鑰，對「時間戳記 + 句點 + 原始請求內容」做 HMAC-SHA256。只有為該位址開啟對應開關時，才會傳送版本的文字內容。傳送失敗會在約半小時內再重試三次；連續五個事件都放棄後，該位址會被停用，需要你手動重新啟用。

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 檔案讀成第一個版本，包含訊息、模型、參數、工具和輸出 schema。提示詞的匯出會把它連同全部版本下載成一個 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 頁面依版本顯示呼叫數、錯誤數、花費、token、延遲和首個 token 耗時，範圍可選最近 7、30 或 90 天；點某個版本的呼叫數，會在 Logs 中開啟這些呼叫。可以先把新版本掛在 staging 下與 production 並行執行，比較之後再移動 production。

在 Logs 裡可以用 prompt = support-reply 和 prompt_version = 7 篩選；請求詳情會寫明它用的提示詞和版本。匯出的紀錄也帶這兩項：檔案和 webhook 裡是 run.prompt_id 和 run.prompt_version，OTLP span 上是 gen_ai.prompt.name 和 gen_ai.prompt.version。

另請參閱: 提示詞 · Chat Completions · Responses API