Saltar al contenido principal
POST
Crear una respuesta

Usa herramientas del servidor

Añade una herramienta phaseo: a tools junto a tus propias herramientas de función, y Phaseo la ejecuta cuando el modelo la llama. /v1/responses acepta todas las herramientas del servidor, incluida phaseo:apply_patch, que solo admite este endpoint; la guía de Herramientas del servidor las enumera.
Cada llamada a una herramienta del servidor se cuenta 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.

Razonamiento en bucles de herramientas

En OpenAI, Azure OpenAI y xAI, Phaseo envía las solicitudes de Responses al proveedor con store: false, así que el razonamiento de un modelo continúa entre los pasos de un bucle de herramientas solo a través de los elementos de salida reasoning. Cada elemento reasoning tiene id, summary y content. Cuando el proveedor devuelve estado de razonamiento, el elemento también tiene encrypted_content, que contiene uno de estos:
  • El razonamiento cifrado de OpenAI, Azure OpenAI y xAI. Phaseo lo solicita con include: ["reasoning.encrypted_content"] para los modelos de razonamiento.
  • Las firmas de pensamiento y el pensamiento censurado de Claude.
  • Las firmas de pensamiento de Gemini, incluido un elemento reasoning aparte colocado justo antes de la llamada a función a la que pertenece una firma.
  • El nivel de esfuerzo con el que se ejecutó una respuesta de Claude, en el último elemento reasoning de la salida, que no tiene texto.
Las respuestas con streaming incluyen los mismos elementos en response.output_item.done y response.completed.
Devuelve todos los elementos de salida en input sin cambios en cada solicitud, no solo en los bucles de herramientas. Nunca descartes, edites ni reordenes elementos reasoning, con o sin encrypted_content, incluidos los elementos sin texto.
encrypted_content es opaco y registra el proveedor y el modelo que lo generaron. Phaseo solo lo envía a esa familia de proveedor y a ese modelo, así que un fallback a otro proveedor lo descarta en lugar de fallar. Sin él, Claude pierde su razonamiento entre los pasos del bucle de herramientas, y un cambio de reasoning.effort reinicia la caché de prompts de Claude; consulta Cambia el esfuerzo de razonamiento a mitad de la conversació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
input
requerido
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.

background
boolean
include
string[]
instructions
string
max_output_tokens
integer
Rango requerido: x >= 1
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
parallel_tool_calls
boolean
previous_response_id
string

No se admite. Phaseo no almacena respuestas, por lo que las solicitudes que definen previous_response_id o conversation devuelven 400 unsupported_param. Envía la conversación completa en input.

reasoning
object
service_tier
enum<string> | null

Selecciona un nivel de enrutamiento o precios compatible. auto (o null) no pide ningún nivel concreto y se enruta y factura como si el campo no estuviera definido; scale se trata como default, el nivel estándar.

Opciones disponibles:
standard,
default,
fast,
ultrafast,
priority,
flex,
batch,
auto,
scale
store
boolean
stream
boolean
temperature
number
Rango requerido: 0 <= x <= 2
text
object
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.

tool_choice

Estrategia de selección de herramientas. Se aceptan los tipos de herramientas de servidor de Phaseo y se transforman en destinos de funciones o herramientas del proveedor de origen. Un objeto allowed_tools se envía tal cual a OpenAI, junto con todas las herramientas. Los demás proveedores reciben solo las herramientas permitidas y su modo (auto o required), o una llamada forzada cuando required permite exactamente una herramienta. Si allowed_tools incluye una herramienta que tools no define, solo OpenAI puede atender la solicitud; de lo contrario, se devuelve un error 400.

Opciones disponibles:
auto,
none,
required,
phaseo:datetime,
phaseo:web_search,
phaseo:web_fetch,
phaseo:subagent,
phaseo:fusion,
phaseo:search_models,
gateway:datetime,
gateway:web_search,
gateway:web_fetch
tools
object[]

Definiciones de herramientas para llamadas a funciones del modelo y herramientas de servidor del gateway. Las herramientas de servidor integradas del gateway son gateway:datetime, gateway:web_search y gateway:web_fetch.

top_p
number
Rango requerido: 0 <= x <= 1
truncation
enum<string>
Opciones disponibles:
auto,
disabled
user
string
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.

prompt_cache_retention
enum<string>

Retención de la caché de prompts para los modelos de OpenAI y Azure OpenAI anteriores a GPT-5.6. Prevalece sobre provider_options.openai.prompt_cache_retention.

Opciones disponibles:
in_memory,
24h
prompt_cache_options
object

Modo y TTL de la caché de prompts para OpenAI y Azure OpenAI desde GPT-5.6 (ttl 30m, o 12h en OpenAI) y para DeepInfra (ttl 5m o 1h). Se elimina para los demás proveedores.

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.

safety_identifier
string | null
modalities
enum<string>[]
Opciones disponibles:
text,
image,
audio
image_config
object
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

id
string
object
string
created
integer
model
string
provider
string
provider_id
string
nativeResponseId
string | null
status
enum<string>
Opciones disponibles:
completed,
failed,
incomplete
finish_reason
string | null
meta
object
cost_nanos
number
cost_cents
integer
currency
string
pricing_lines
object[]
output
object[]
output_items
object[]
content
object[]
role
string
stop_reason
string
type
string
usage
object
Última modificación el 12 de noviembre de 2026