Biblioteca de prompts

Guarda los prompts en tu espacio de trabajo en lugar de en el código: versionados, con etiquetas y llamados por ID desde cualquier SDK de OpenAI. Al mover una etiqueta, tu código recibe la nueva versión en la siguiente solicitud, sin volver a desplegar.

Llamar a un prompt

Usa el endpoint habitual /v1/chat/completions, /v1/responses o /v1/messages y añade prompt_id y prompt_variables al cuerpo. Los SDK exigen model y messages: envía cualquier nombre de modelo y un mensaje de usuario vacío. En los SDK de OpenAI y Anthropic, los campos adicionales van en 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)

Por HTTP directo, los campos van en el nivel superior del cuerpo. Esta llamada pide la versión a la que apunta la etiqueta 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."}
  }'

Campos

En qué se convierte la solicitud

• Primero los mensajes de la versión, luego los tuyos. Con tus propios mensajes continúa una conversación: los turnos anteriores, las llamadas a herramientas y sus resultados se conservan tal como los envías. Solo se descarta el mensaje de usuario vacío que exigen los SDK.
• El modelo de la versión sustituye al de la solicitud. Si la versión no tiene modelo, se mantiene el tuyo.
• Tus parámetros tienen prioridad. La temperature, max_tokens, top_p y el modo JSON de la versión solo se aplican si tu solicitud no fija el mismo parámetro.
• Los cuatro campos prompt_* se quedan en la pasarela. El proveedor recibe una solicitud normal.
• En /v1/responses, los mensajes van en input (un input de texto es tu turno de usuario), max_tokens pasa a ser max_output_tokens y el modo JSON pasa a text.format.

En /v1/messages

Los mismos cuatro campos funcionan con el SDK de Anthropic. El texto de sistema de la versión va delante de tu propio system, sus mensajes delante de los tuyos, y temperature, top_p y max_tokens se aplican cuando tu solicitud no los define. El modo JSON no tiene campo en este endpoint y se omite.

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)

Llamadas a herramientas y conversaciones de varios turnos

Envía tools y la conversación hasta el momento exactamente como lo harías sin un prompt de la biblioteca. La versión aporta el prompt de sistema y el mensaje inicial; tus mensajes llevan el resto de la conversación, incluidas las llamadas a herramientas del modelo y sus resultados.

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

Herramientas y esquema de salida en una versión

Una versión puede contener herramientas de función, una elección de herramienta y un esquema JSON para la respuesta; se escriben con la forma del endpoint al que llamas. Las herramientas que envía tu solicitud se añaden después de las de la versión, y una herramienta tuya con el mismo nombre sustituye a la de la versión. Tu propio tool_choice y tu formato de respuesta prevalecen.

Partials

Un partial es un bloque de texto que se guarda una sola vez y se incluye en los prompts con {{>id}}. Al guardar una versión de un prompt, cada inclusión queda fijada a la versión más reciente del partial y se muestra como {{>id@4}}, así que una versión guardada no cambia cuando cambia el partial. La página del prompt indica cuándo existe una versión más reciente del partial y ofrece actualizar, lo que guarda una versión nueva del prompt. Las variables de un partial se rellenan con los prompt_variables de la llamada. Un partial no se puede llamar por sí solo, y uno incluido en versiones guardadas no se puede eliminar.

Versiones y etiquetas

Cada guardado crea la versión siguiente, y una versión guardada nunca cambia. production, staging y development existen en todos los prompts; puedes añadir tus propias etiquetas. Apunta production a una versión para publicarla y de vuelta a la anterior para revertir. Tu código sigue llamando al mismo ID.

Mover una etiqueta o borrar un prompt se refleja en las llamadas en unos 10 segundos. Mover etiquetas y borrar prompts requiere ser administrador o propietario del espacio de trabajo.

Probar un borrador

En el editor de la página Prompts, el borrador se escribe a la izquierda y se prueba a la derecha. Da un valor a cada variable y pulsa Run: el borrador se renderiza y se envía a su modelo, y la respuesta aparece con su latencia y su coste. La llamada se factura y se registra como una llamada del Playground, y no se guarda nada del borrador hasta que guardas la versión. Show the request muestra la solicitud renderizada para cada endpoint sin llamar a ningún modelo.

Probar una versión antes de publicarla

Las Pruebas de un prompt contienen conjuntos de pruebas: filas con valores para sus variables, con un mensaje de usuario y una respuesta esperada opcionales, y las comprobaciones que debe superar una respuesta (contiene, coincide con un patrón, es igual a la respuesta esperada, JSON válido, cumple el esquema de salida, un límite de latencia o de coste, o un modelo que juzga según un criterio que escribes tú). Una ejecución llama, para cada fila, a la versión que elijas y a la versión con la que la comparas, muestra las dos respuestas en paralelo e indica cuántas filas se superaron, además del coste y la latencia de cada una. Cada llamada se factura y se registra como una llamada del Playground, bajo una sola traza por ejecución. Al mover una etiqueta, el diálogo muestra la última ejecución de la versión; informa de la decisión, no la bloquea. Los conjuntos de pruebas y las respuestas de una ejecución se guardan cifrados; las respuestas se conservan 30 días.

Despliegue gradual

Una etiqueta puede enviar una parte de sus llamadas a otra versión: «production: v6, v7 al 10 %». Qué versión recibe una llamada lo decide su id de sesión, o su usuario final si no tiene sesión, o si no cada solicitud, así que una conversación se mantiene en una versión. X-Synthorai-Prompt-Version indica cuál respondió, y la página Prompts muestra las dos en paralelo. Un administrador cambia la parte, mueve la etiqueta a la versión candidata o detiene el despliegue; una llamada que fija prompt_version nunca forma parte de él.

Webhooks de cambios

Los administradores pueden añadir hasta tres direcciones en la página Prompts, que reciben un POST cuando un prompt se crea, recibe una versión, se le mueve una etiqueta o cambia un despliegue, o se elimina. Cada solicitud va firmada: X-Synthorai-Signature: t=…,v1=…, el HMAC-SHA256 de la marca de tiempo, un punto y el cuerpo sin procesar, con el secreto que se muestra una sola vez al añadir la dirección. El texto de una versión solo se envía si lo activas para esa dirección. Una entrega fallida se reintenta tres veces más en una media hora; tras cinco eventos abandonados seguidos, la dirección se desactiva hasta que la vuelvas a activar.

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 y los prompts almacenados de OpenAI

Nuevo prompt › Importar lee el cuerpo pegado de una solicitud de Chat Completions o Responses, o un archivo .prompt de LiteLLM, y lo convierte en una primera versión: mensajes, modelo, parámetros, herramientas y esquema de salida. Exportar descarga un prompt con todas sus versiones en un único archivo JSON, que se importa del mismo modo, y Copiar a un espacio de trabajo lo copia en otro espacio del que seas miembro. Los prompts almacenados de OpenAI dejan de funcionar el 2026-11-30 y no se pueden leer: vuelve a crear el prompt aquí con su ID pmpt_…, y una solicitud a /v1/responses que envíe prompt con ese ID se atiende desde la biblioteca sin cambiar el código. Su version, cuando es un número, elige esa versión de la biblioteca; sin ella, la llamada recibe production.

Renderizar sin llamar a un modelo

POST /v1/prompts/{id}/render devuelve la solicitud que enviaría una llamada, y la versión resuelta, sin llamar a un modelo. Envía prompt_variables, opcionalmente prompt_version o prompt_label, y format: chat (por defecto), responses o messages. No se factura ni aparece en Logs; cuenta para el límite de frecuencia de la clave. Úsalo para comprobar qué envía una versión o para llamar a un endpoint al que no llegan los campos 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."}
    ]
  }
}

Cabeceras de respuesta

X-Synthorai-Prompt-Version indica qué versión respondió, algo que una llamada por etiqueta no puede saber de otro modo. Si la biblioteca no se puede leer, el gateway responde con la última copia leída, durante 24 horas como máximo, y añade X-Synthorai-Prompt-Stale: 1; una etiqueta movida entretanto surte efecto cuando la biblioteca vuelve a poder leerse.

Errores

Se devuelven antes de llamar a ningún modelo, así que nunca se facturan. Siguen el formato de error del endpoint que llamó.

Estadísticas por versión

Cada llamada se registra con el prompt y la versión que usó. La página Prompts muestra por versión las llamadas, los errores, el gasto, los tokens, la latencia y el tiempo hasta el primer token de los últimos 7, 30 o 90 días; el número de llamadas de una versión abre esas llamadas en Logs. Ejecuta una versión nueva en staging junto a production y compáralas antes de mover production.

En Logs, filtra con prompt = support-reply y prompt_version = 7; el detalle de una solicitud indica su prompt y su versión. Los registros exportados también los incluyen: run.prompt_id y run.prompt_version en archivos y webhooks, gen_ai.prompt.name y gen_ai.prompt.version en los spans OTLP.

Véase también: Prompts · Chat Completions · Responses API