Saltar al contenido principal
POST
Crear un mensaje
Envía un payload de la API Anthropic Messages a /v1/messages y recibe una respuesta con formato de Anthropic, para cualquier modelo que enrute Phaseo. Se admiten los campos de uso de herramientas de Anthropic, y el encabezado X-Phaseo-Strictness controla cómo se tratan los parámetros no admitidos. Configura stream: true para recibir server-sent events en formato de Anthropic (message_start, content_block_*, message_delta, message_stop). El streaming también funciona en bucles de herramientas.

Mensajes de sistema a mitad de la conversación

Añade un mensaje role: "system" a messages para una instrucción que se aplica desde ese punto de la conversación. El campo system de nivel superior no cambia, así que un prefijo en caché sigue acertando.
Un mensaje de sistema acepta una cadena o bloques de texto. Debe ir justo después de un turno del usuario (o de un turno del asistente que termine en un resultado de herramienta del servidor) y ser el último mensaje o ir seguido de un turno del asistente. Las demás posiciones devuelven 400. No se admiten clear_at, output_config ni los bloques tool_addition o tool_removal.

Usa herramientas del servidor

Añade una herramienta phaseo: a tools y Phaseo la ejecuta cuando el modelo la llama: la reescribe al formato de herramientas de Anthropic para el proveedor y continúa el bucle de herramientas en el servidor. /v1/messages acepta todas las herramientas del servidor excepto phaseo:apply_patch; la guía de Herramientas del servidor las enumera.
Las llamadas a herramientas del servidor se cuentan en usage.server_tool_use. El tipo antiguo gateway:datetime sigue funcionando. Con stream: true, Phaseo ejecuta los turnos de herramientas por su cuenta y después te transmite la respuesta continuada como un único stream.

Usa la búsqueda web nativa de Anthropic

Cuando el modelo y el proveedor de Anthropic enrutados admiten la búsqueda web nativa, pasa directamente la definición de herramienta de Anthropic, por ejemplo type: "web_search_20250305". El enrutamiento de proveedores sigue filtrando por compatibilidad con web_search_options antes de la ejecución.

Autorizaciones

Authorization
string
header
requerido

Autenticación con token Bearer

Cuerpo

application/json

Un campo opcional de nivel superior enviado como null se trata como no definido, igual que si se omitiera.

model
string
requerido
messages
object[]
requerido
Minimum array length: 1
max_tokens
integer
requerido
Rango requerido: x >= 1
models
string[]

Modelos de respaldo opcionales y ordenados que se prueban después de model. model es obligatorio y siempre es el modelo principal. Cuando un intento falla con 429, 500, 502, 503 o 504, se prueba la siguiente entrada; los demás errores se devuelven sin cambios. Acepta hasta 25 IDs de modelo o presets; se ignoran los duplicados y las entradas iguales a model. Cada intento se valida, registra y factura como una solicitud independiente, y el campo model de la respuesta y la traza de enrutamiento muestran el modelo que atendió la solicitud. Las solicitudes en streaming solo recurren a un respaldo antes del primer byte, y los trabajos de video y música solo al enviarse. Las solicitudes de batch, realtime y council rechazan models. Los respaldos definidos en una ruta dinámica tienen prioridad, y phaseo/auto no se puede combinar con models.

Required array length: 1 - 25 elements
Minimum string length: 1
Ejemplo:
prompt
object

Rellena la plantilla de prompt guardada en un preset. Omite model o usa la misma referencia, y envía una conversación vacía o los turnos que se añadirán después de la plantilla.

system
service_tier
enum<string>

Selecciona un nivel de enrutamiento o precios compatible en las API de texto que lo admiten.

Opciones disponibles:
standard,
default,
fast,
ultrafast,
priority,
flex,
batch,
auto,
standard_only
temperature
number
Rango requerido: 0 <= x <= 1
top_p
number
Rango requerido: 0 <= x <= 1
top_k
integer
Rango requerido: x >= 1
tools
object[]

Herramientas compatibles con Anthropic y herramientas de servidor gestionadas por el gateway.

tool_choice

Objeto o cadena de selección de herramientas de Anthropic. También se aceptan los nombres de herramientas de servidor gestionadas por el gateway, que este transforma.

plugins
object[]

Plugins del gateway para esta solicitud. web añade búsqueda web y web-fetch añade la lectura de páginas a cualquier modelo; response-healing repara el JSON mal formado en las respuestas estructuradas no transmitidas en streaming. Los valores predeterminados del espacio de trabajo y del preset se combinan con esta lista. Un id de plugin desconocido devuelve 400 unknown_gateway_plugin.

Añade a la solicitud la herramienta de servidor phaseo:web_search, para que cualquier modelo pueda buscar en la web. La solicitud se ejecuta, y las búsquedas se cuentan y facturan, exactamente igual que con una herramienta phaseo:web_search. Si la solicitud ya tiene una herramienta de búsqueda web, el plugin no añade nada. Las demás opciones se ignoran.

stream
boolean
metadata
object
session_id
string

Identificador único para agrupar solicitudes relacionadas (por ejemplo, una conversación o un flujo de trabajo de agente) y facilitar la observabilidad.

Maximum string length: 256
reasoning
object
context_management
object

Edición de contexto de Anthropic. edits admite las estrategias clear_tool_uses_* y clear_thinking_* y se envía a Anthropic con su cabecera beta. Los demás proveedores ejecutan la solicitud sin este campo e incluyen context_management en X-Phaseo-Dropped-Params. Las ediciones de compactación (compact_*) devuelven 400.

user
string

Identificador del usuario final, igual que en Chat Completions. Los modelos Claude lo reciben como metadata.user_id, salvo que metadata.user_id ya esté definido.

prompt_cache_key
string | null

Agrupa las solicitudes relacionadas para que se mantengan en el proveedor que tiene su caché de prompts. Phaseo envía al proveedor un hash de tu espacio de trabajo y esta clave, nunca la clave sin procesar.

stop_sequences
string[]
cache_control
object

Control de la caché de prompts. Usa type ephemeral con un ttl opcional de 5m o 1h. scope solo se aplica a una política de caché de Claude de nivel superior. Amazon Bedrock y Google Vertex AI almacenan en caché Claude 3.7 Sonnet, 3.5 Sonnet y 3 Opus solo durante 5 minutos; allí se elimina el ttl y un 1h eliminado se informa en X-Phaseo-Dropped-Params como cache_control.ttl.

provider_options
object

Opciones específicas del proveedor, si se necesitan.

usage
boolean
meta
boolean
echo_upstream_request
boolean
debug
object

Controles de depuración de la pasarela. Estas opciones nunca se reenvían al proveedor.

provider
object

Preferencias de enrutamiento de proveedores para la selección de la pasarela.

Respuesta

Respuesta del mensaje

id
string
type
string
role
enum<string>
Opciones disponibles:
assistant
model
string
content
object[]
stop_reason
string
stop_sequence
string
usage
object
context_management
object

Aparece cuando la solicitud usó context_management y Anthropic aplicó una edición. applied_edits enumera cada edición con lo que eliminó. En streaming, llega en el evento message_delta final.

Última modificación el 5 de noviembre de 2026