Libreria di prompt

Tieni i prompt nel workspace invece che nel codice: versionati, con etichette e chiamati per ID da qualsiasi SDK OpenAI. Spostando un’etichetta, il tuo codice riceve la nuova versione dalla richiesta successiva, senza nuovo deploy.

Chiamare un prompt

Usa il normale endpoint /v1/chat/completions, /v1/responses o /v1/messages e aggiungi prompt_id e prompt_variables al corpo. Gli SDK richiedono model e messages: invia un nome di modello qualsiasi e un messaggio utente vuoto. Negli SDK di OpenAI e Anthropic i campi aggiuntivi vanno 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)

Via HTTP diretto, i campi stanno al primo livello del body. Questa chiamata chiede la versione a cui punta l’etichetta 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."}
  }'

Campi

Cosa diventa la richiesta

• Prima i messaggi della versione, poi i tuoi. Sono i tuoi messaggi a far proseguire una conversazione: i turni precedenti, le chiamate agli strumenti e i loro risultati restano come li invii. Viene scartato solo il messaggio utente vuoto richiesto dagli SDK.
• Il modello della versione sostituisce quello della richiesta. Una versione senza modello mantiene il tuo.
• I tuoi parametri hanno la precedenza. temperature, max_tokens, top_p e modalità JSON della versione valgono solo se la tua richiesta non imposta lo stesso parametro.
• I quattro campi prompt_* si fermano al gateway. Il provider riceve una richiesta normale.
• Su /v1/responses i messaggi finiscono in input (un input di tipo stringa è il tuo turno utente), max_tokens diventa max_output_tokens e la modalità JSON diventa text.format.

Su /v1/messages

Gli stessi quattro campi funzionano con l’SDK di Anthropic. Il testo di sistema della versione precede il tuo system, i suoi messaggi precedono i tuoi, e temperature, top_p e max_tokens si applicano dove la tua richiesta non li imposta. La modalità JSON non ha un campo su questo endpoint e viene omessa.

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)

Chiamate agli strumenti e conversazioni a più turni

Invia tools e la conversazione fin qui esattamente come faresti senza un prompt della libreria. La versione fornisce il prompt di sistema e il messaggio iniziale; i tuoi messaggi portano il resto della conversazione, comprese le chiamate agli strumenti del modello e i tuoi risultati.

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

Strumenti e schema di output in una versione

Una versione può contenere strumenti di tipo funzione, una scelta dello strumento e uno schema JSON per la risposta; vengono scritti nel formato dell’endpoint chiamato. Gli strumenti inviati dalla tua richiesta si aggiungono dopo quelli della versione, e un tuo strumento con lo stesso nome sostituisce quello della versione. Il tuo tool_choice e il tuo formato di risposta prevalgono.

Partial

Un partial è un blocco di testo conservato una sola volta e incluso nei prompt con {{>id}}. Quando salvi una versione di un prompt, ogni inclusione viene fissata alla versione più recente del partial e mostrata come {{>id@4}}: una versione salvata quindi non cambia quando cambia il partial. La pagina del prompt segnala quando esiste una versione più recente del partial e propone l’aggiornamento, che salva una nuova versione del prompt. Le variabili di un partial vengono compilate con i prompt_variables della chiamata. Un partial non può essere chiamato da solo, e uno incluso in versioni salvate non può essere eliminato.

Versioni ed etichette

Ogni salvataggio crea la versione successiva e una versione salvata non cambia mai. production, staging e development esistono su ogni prompt; puoi aggiungere le tue etichette. Punta production su una versione per rilasciarla e di nuovo su quella vecchia per tornare indietro. Il tuo codice continua a chiamare lo stesso ID.

Lo spostamento di un’etichetta o l’eliminazione di un prompt arriva alle chiamate entro circa 10 secondi. Spostare etichette ed eliminare prompt richiede il ruolo di admin o di proprietario del workspace.

Provare una bozza

Nell’editor della pagina Prompts la bozza si scrive a sinistra e si prova a destra. Dai un valore a ogni variabile e premi Run: la bozza viene renderizzata e inviata al suo modello, e la risposta arriva con latenza e costo. La chiamata viene addebitata e registrata come una chiamata del Playground, e della bozza non resta nulla finché non salvi la versione. Show the request mostra la richiesta renderizzata per ogni endpoint, senza chiamare alcun modello.

Testare una versione prima di rilasciarla

I Test di un prompt contengono set di test: righe di valori per le sue variabili, con un messaggio utente e una risposta attesa facoltativi, e i controlli che una risposta deve superare (contiene, corrisponde a un pattern, è uguale alla risposta attesa, JSON valido, rispetta lo schema di output, un limite di latenza o di costo, oppure un modello che giudica secondo un criterio scritto da te). Un’esecuzione chiama, per ogni riga, la versione scelta e quella con cui la confronti, mostra le due risposte affiancate e indica quante righe sono state superate, oltre al costo e alla latenza di ciascuna. Ogni chiamata viene fatturata e registrata come una chiamata del Playground, sotto un’unica traccia per esecuzione. Quando sposti un’etichetta, la finestra mostra l’ultima esecuzione della versione; informa la decisione, non la blocca. I set di test e le risposte di un’esecuzione sono salvati cifrati; le risposte vengono conservate per 30 giorni.

Rilascio graduale

Un’etichetta può inviare una parte delle sue chiamate a un’altra versione: «production: v6, v7 al 10%». La versione ricevuta dipende dall’id di sessione, o dall’utente finale se non c’è sessione, altrimenti dalla singola richiesta: una conversazione resta quindi sulla stessa versione. X-Synthorai-Prompt-Version indica quale ha risposto, e la pagina Prompts mostra le due affiancate. Un amministratore modifica la quota, sposta l’etichetta sulla versione candidata o interrompe il rilascio; una chiamata che fissa prompt_version non ne fa mai parte.

Webhook di modifica

Gli amministratori possono aggiungere fino a tre indirizzi nella pagina Prompts, che ricevono una POST quando un prompt viene creato, riceve una versione, ha un’etichetta spostata o un rilascio modificato, oppure viene eliminato. Ogni richiesta è firmata: X-Synthorai-Signature: t=…,v1=…, l’HMAC-SHA256 di timestamp, punto e corpo non elaborato, con il segreto mostrato una sola volta quando si aggiunge l’indirizzo. Il testo di una versione viene inviato solo se lo attivi per quell’indirizzo. Una consegna non riuscita viene ritentata altre tre volte in circa mezz’ora; dopo cinque eventi abbandonati di seguito, l’indirizzo viene disattivato finché non lo riattivi.

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

Importazione, esportazione e prompt salvati di OpenAI

Nuovo prompt › Importa legge il corpo incollato di una richiesta Chat Completions o Responses, o un file .prompt di LiteLLM, e ne fa una prima versione: messaggi, modello, parametri, strumenti e schema di output. Esporta scarica un prompt con tutte le versioni in un unico file JSON, che si importa allo stesso modo, e Copia in un workspace lo copia in un altro workspace di cui fai parte. I prompt salvati di OpenAI smettono di funzionare il 2026-11-30 e non possono essere letti: ricrea qui il prompt con il suo ID pmpt_…, e una richiesta a /v1/responses che invia prompt con quell’ID viene servita dalla libreria senza modificare il codice. La sua version, quando è un numero, sceglie quella versione della libreria; senza, la chiamata riceve production.

Rendering senza chiamare un modello

POST /v1/prompts/{id}/render restituisce la richiesta che una chiamata invierebbe, e la versione risolta, senza chiamare un modello. Invia prompt_variables, facoltativamente prompt_version o prompt_label, e format: chat (predefinito), responses o messages. Non viene fatturato e non compare in Logs; conta nel limite di frequenza della chiave. Usalo per verificare che cosa invia una versione o per chiamare un endpoint che i campi prompt_* non raggiungono.

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

Header di risposta

X-Synthorai-Prompt-Version indica quale versione ha risposto, cosa che una chiamata per etichetta non può sapere altrimenti. Se la libreria non è leggibile, il gateway risponde con l’ultima copia letta, per 24 ore al massimo, e aggiunge X-Synthorai-Prompt-Stale: 1; un’etichetta spostata nel frattempo ha effetto quando la libreria torna leggibile.

Errori

Vengono restituiti prima di chiamare qualsiasi modello, quindi non sono mai addebitati. Seguono il formato di errore dell’endpoint chiamato.

Statistiche per versione

Ogni chiamata viene registrata con il prompt e la versione usati. La pagina Prompts mostra per versione chiamate, errori, spesa, token, latenza e tempo al primo token degli ultimi 7, 30 o 90 giorni; il numero di chiamate di una versione apre quelle chiamate in Logs. Esegui una nuova versione in staging accanto a production e confrontale prima di spostare production.

In Logs filtra con prompt = support-reply e prompt_version = 7; il dettaglio di una richiesta indica prompt e versione. Anche i record esportati li riportano: run.prompt_id e run.prompt_version in file e webhook, gen_ai.prompt.name e gen_ai.prompt.version sugli span OTLP.

Vedi anche: Prompt · Chat Completions · Responses API