Biblioteca de prompts

Mantenha os prompts no seu workspace em vez de no código: versionados, com rótulos e chamados por ID a partir de qualquer SDK da OpenAI. Mover um rótulo muda o que o seu código recebe já na próxima requisição, sem novo deploy.

Chamar um prompt

Use o endpoint habitual /v1/chat/completions, /v1/responses ou /v1/messages e acrescente prompt_id e prompt_variables ao corpo. Os SDKs exigem model e messages: envie qualquer nome de modelo e uma mensagem de usuário vazia. Nos SDKs da OpenAI e da Anthropic, os campos extra vão em 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 direto, os campos ficam no nível superior do corpo. Esta chamada pede a versão para a qual o rótulo staging aponta:

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

Campos

No que a requisição se transforma

• Primeiro as mensagens da versão, depois as suas. É com as suas próprias mensagens que uma conversa continua: turnos anteriores, chamadas de ferramentas e seus resultados são mantidos como você os envia. Só a mensagem de usuário vazia, exigida pelos SDKs, é descartada.
• O modelo da versão substitui o da requisição. Uma versão sem modelo mantém o seu.
• Os seus parâmetros têm prioridade. A temperature, max_tokens, top_p e o modo JSON da versão só valem quando a sua requisição não define o mesmo parâmetro.
• Os quatro campos prompt_* param no gateway. O provedor recebe uma requisição comum.
• Em /v1/responses, as mensagens vão para input (um input em texto é o seu turno de usuário), max_tokens vira max_output_tokens e o modo JSON vira text.format.

Em /v1/messages

Os mesmos quatro campos funcionam com o SDK da Anthropic. O texto de sistema da versão vem antes do seu próprio system, as mensagens dela antes das suas, e temperature, top_p e max_tokens valem quando a sua requisição não os define. O modo JSON não tem campo neste endpoint e é omitido.

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)

Chamadas de ferramentas e conversas com vários turnos

Envie tools e a conversa até aqui exatamente como faria sem um prompt da biblioteca. A versão fornece o prompt do sistema e a mensagem de abertura; as suas mensagens levam o resto da conversa, incluindo as chamadas de ferramentas do modelo e os resultados que você devolve.

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

Ferramentas e esquema de saída numa versão

Uma versão pode conter ferramentas de função, uma escolha de ferramenta e um esquema JSON para a resposta; eles são escritos no formato do endpoint chamado. As ferramentas enviadas pela sua requisição são acrescentadas depois das da versão, e uma ferramenta sua com o mesmo nome substitui a da versão. O seu próprio tool_choice e o seu formato de resposta prevalecem.

Partials

Um partial é um bloco de texto salvo uma única vez e incluído em prompts com {{>id}}. Ao salvar uma versão de um prompt, cada inclusão fica fixada na versão mais recente do partial e aparece como {{>id@4}}; assim, uma versão salva não muda quando o partial muda. A página do prompt avisa quando existe uma versão mais recente do partial e propõe a atualização, que salva uma nova versão do prompt. As variáveis de um partial são preenchidas pelos prompt_variables da chamada. Um partial não pode ser chamado sozinho, e um partial incluído em versões salvas não pode ser excluído.

Versões e rótulos

Cada vez que você salva, cria a próxima versão, e uma versão salva nunca muda. production, staging e development existem em todo prompt; você pode adicionar seus próprios rótulos. Aponte production para uma versão para publicá-la, e de volta para a antiga para reverter. O seu código continua chamando o mesmo ID.

Mover um rótulo ou excluir um prompt passa a valer para as chamadas em cerca de 10 segundos. Mover rótulos e excluir prompts exige ser administrador ou dono do workspace.

Experimentar um rascunho

No editor da página Prompts, você escreve o rascunho à esquerda e o testa à direita. Dê um valor a cada variável e clique em Run: o rascunho é renderizado e enviado ao seu modelo, e a resposta aparece com a latência e o custo. A chamada é cobrada e registrada como uma chamada do Playground, e nada do rascunho é salvo até você salvar a versão. Show the request mostra a requisição renderizada para cada endpoint, sem chamar nenhum modelo.

Testar uma versão antes de a publicar

Os Testes de um prompt guardam conjuntos de testes: linhas com valores para as variáveis dele, com uma mensagem de usuário e uma resposta esperada opcionais, e as verificações pelas quais uma resposta precisa passar (contém, corresponde a um padrão, é igual à resposta esperada, JSON válido, segue o esquema de saída, um limite de latência ou de custo, ou um modelo que avalia segundo um critério escrito por você). Uma execução chama, para cada linha, a versão escolhida e a versão com que ela é comparada, mostra as duas respostas lado a lado e indica quantas linhas foram aprovadas, além do custo e da latência de cada uma. Cada chamada é cobrada e registrada como uma chamada do Playground, em um único trace por execução. Ao mover um rótulo, a caixa de diálogo mostra a última execução da versão; ela informa a decisão, não a bloqueia. Os conjuntos de testes e as respostas de uma execução são armazenados criptografados; as respostas são mantidas por 30 dias.

Lançamento gradual

Um rótulo pode enviar uma parte das suas chamadas para outra versão: “production: v6, v7 a 10%”. A versão que uma chamada recebe é decidida pelo id de sessão, ou pelo usuário final quando não há sessão, ou então por requisição; assim, uma conversa fica em uma só versão. X-Synthorai-Prompt-Version indica qual respondeu, e a página Prompts mostra as duas lado a lado. Um administrador altera a parte, move o rótulo para a versão candidata ou interrompe o lançamento; uma chamada que fixa prompt_version nunca faz parte dele.

Webhooks de alterações

Os administradores podem adicionar até três endereços na página Prompts, que recebem um POST quando um prompt é criado, recebe uma versão, tem um rótulo movido ou um lançamento alterado, ou é excluído. Cada requisição é assinada: X-Synthorai-Signature: t=…,v1=…, o HMAC-SHA256 do timestamp, um ponto e o corpo bruto, com o segredo exibido uma única vez ao adicionar o endereço. O texto de uma versão só é enviado se você ativar isso para esse endereço. Uma entrega que falha é repetida mais três vezes ao longo de cerca de meia hora; após cinco eventos abandonados seguidos, o endereço é desativado até você reativá-lo.

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

Importar, exportar e os prompts salvos da OpenAI

Novo prompt › Importar lê o corpo colado de uma requisição Chat Completions ou Responses, ou um arquivo .prompt do LiteLLM, e o transforma em uma primeira versão: mensagens, modelo, parâmetros, ferramentas e esquema de saída. Exportar baixa um prompt com todas as versões em um único arquivo JSON, que pode ser importado da mesma forma, e Copiar para um workspace o copia para outro workspace do qual você seja membro. Os prompts salvos da OpenAI deixam de funcionar em 2026-11-30 e não podem ser lidos: recrie o prompt aqui com o ID pmpt_… dele, e uma requisição a /v1/responses que envie prompt com esse ID é atendida pela biblioteca sem alterar o código. A version dela, quando é um número, escolhe essa versão da biblioteca; sem ela, a chamada recebe production.

Renderizar sem chamar um modelo

POST /v1/prompts/{id}/render retorna a requisição que uma chamada enviaria, e a versão resolvida, sem chamar um modelo. Envie prompt_variables, opcionalmente prompt_version ou prompt_label, e format: chat (padrão), responses ou messages. Não é cobrado nem aparece em Logs; conta para o limite de taxa da chave. Use-o para verificar o que uma versão envia ou para chamar um endpoint ao qual os campos prompt_* não chegam.

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

Cabeçalhos de resposta

X-Synthorai-Prompt-Version indica que versão respondeu, algo que uma chamada por rótulo não tem outra forma de saber. Se a biblioteca não puder ser lida, o gateway responde com a última cópia lida, durante 24 horas no máximo, e acrescenta X-Synthorai-Prompt-Stale: 1; um rótulo movido entretanto entra em vigor quando a biblioteca voltar a poder ser lida.

Erros

Eles são retornados antes de qualquer modelo ser chamado, por isso nunca são cobrados. Seguem o formato de erro do endpoint chamado.

Estatísticas por versão

Cada chamada é registrada com o prompt e a versão que usou. A página Prompts mostra, por versão, as chamadas, os erros, o gasto, os tokens, a latência e o tempo até o primeiro token nos últimos 7, 30 ou 90 dias; o número de chamadas de uma versão abre essas chamadas em Logs. Execute uma versão nova em staging ao lado de production e compare-as antes de mover production.

Em Logs, filtre com prompt = support-reply e prompt_version = 7; o detalhe de uma requisição indica o prompt e a versão. Os registros exportados também os incluem: run.prompt_id e run.prompt_version em arquivos e webhooks, gen_ai.prompt.name e gen_ai.prompt.version nos spans OTLP.

Veja também: Prompts · Chat Completions · Responses API