Parámetros - Phaseo Docs

Esta página es la referencia campo por campo de los parámetros de solicitud que ofrece Phaseo. Úsala si quieres saber:

qué hace un parámetro
qué tipo espera
el rango habitual o los valores aceptados
si afecta a la calidad, el coste, la latencia o el enrutamiento

Si buscas consejos de ajuste en lugar de definiciones de campos, consulta Parámetros de inferencia y Muestreo y decodificación. La compatibilidad de los parámetros sigue variando según el endpoint, el modelo y el proveedor. La tabla de inicio rápido del modelo reúne la compatibilidad de los proveedores activos para una ruta específica.

Consulta rápida

Parámetro	Tipo	Úsalo para
`model`	`string`	Seleccionar el ID del modelo del gateway que se ejecutará.
`stream`	`boolean`	Devolver la salida SSE progresivamente en lugar de un único resultado final.
`temperature`	`number`	Aumentar o reducir la aleatoriedad.
`top_p`	`number`	Ampliar o reducir el conjunto de nucleus sampling.
`top_k`	`integer`	Limitar el muestreo a los k tokens candidatos principales.
`max_tokens`	`integer`	Limitar la longitud de salida en las rutas que aún usan este nombre de campo.
`max_output_tokens`	`integer`	Limitar la longitud de salida en las rutas que usan el nombre de campo más reciente.
`max_completion_tokens`	`integer`	Limitar la longitud de salida en las API de texto más recientes al estilo OpenAI.
`frequency_penalty`	`number`	Desalentar la repetición de tokens y frases.
`presence_penalty`	`number`	Fomentar cambios de tema o vocabulario.
`repetition_penalty`	`number`	Control de repetición específico del proveedor.
`seed`	`integer`	Mejorar la reproducibilidad cuando el proveedor ascendente lo admite.
`stop`	`string` or `string[]`	Definir secuencias de parada explícitas.
`logprobs` / `top_logprobs`	`boolean` / `integer`	Solicitar datos de probabilidad de tokens.
`tools`, `tool_choice`	`array`, `string`, `object`	Control de llamadas a herramientas y ejecución de funciones.
`parallel_tool_calls`	`boolean`	Permitir o forzar la ejecución secuencial de herramientas.
`response_format`	`string` or `object`	Salida de texto sin formato, JSON o restringida por esquema.
`json_schema`	`object`	Definir el esquema para flujos de salida estructurada.
`structured_outputs`	`boolean`	Indicador de capacidad para generar salidas fiables restringidas por esquema.
`reasoning`	`object`	Configuración de razonamiento específica del proveedor.
`reasoning_effort`	`string`	Reducir o aumentar el presupuesto de razonamiento.
`reasoning_tokens`	`integer`	Límite de tokens o campo de contabilización específico del razonamiento.
`include_reasoning`	`boolean`	Devolver el contenido o resúmenes del razonamiento cuando sea compatible.
`service_tier`	`string`	Elegir un nivel de solicitud compatible como `fast`, `ultrafast` o `flex`.
`prompt_cache_key`	`string`	Mantener fijo el enrutamiento con caché para solicitudes relacionadas.
`prompt_cache_options`	`object`	Configurar el modo de caché de prompts y los controles de TTL de OpenAI.
`cache_control`	`object`	Aplicar indicaciones o puntos de ruptura de caché de prompt independientes del proveedor.
`prompt_cache_retention`	`string`	Configurar la retención de caché de prompt compatible con OpenAI.
`provider`	`object`	Influir en el enrutamiento y la selección del proveedor.
`provider_options`	`object`	Pasar ajustes nativos del proveedor a través del gateway.
`meta` / `usage`	`boolean`	Devolver metadatos adicionales o el uso contabilizado en la respuesta.
`debug`	`object`	Solicitar trazas de enrutamiento y datos de diagnóstico.

Notas sobre endpoints

service_tier es compatible con las principales interfaces de solicitud de texto:

Usa ultrafast, fast (o priority donde sea compatible) y flex solo si la combinación de modelo y proveedor seleccionada los admite. Ultrafast selecciona el nivel compatible más rápido; fast y priority usan el mismo enrutamiento y precio Fast. standard es el valor predeterminado si se omite service_tier. Batch no es un valor de service_tier. Las solicitudes por lotes usan la API Batch independiente. En las solicitudes Messages compatibles con Anthropic, los valores nativos de Anthropic son auto y standard_only. Phaseo puede normalizarlos o asignarlos entre proveedores y conservar el comportamiento compatible con Anthropic en /v1/messages. Si usas un SDK oficial de Anthropic con una URL base personalizada que apunta a Phaseo, usa preferentemente los valores nativos de Anthropic en /v1/messages. Para controles de nivel normalizados entre proveedores como ultrafast, priority y flex, o el alias fast de OpenAI, es preferible usar solicitudes HTTP directas o las API de texto nativas del gateway o de estilo OpenAI.

Referencia de parámetros

`model`

Selecciona el ID del modelo del gateway para la solicitud.

Campo	Valor
Tipo	`string`
Obligatorio	Sí
Ejemplo	`openai/gpt-5-nano`

Salvo que quieras usar intencionalmente un alias aceptado, utiliza el ID canónico que aparece en el inicio rápido de cada página de modelo. Los ID canónicos son la opción más segura para ejemplos, automatizaciones e integraciones duraderas.

`stream`

Devuelve la salida progresivamente mediante Server-Sent Events, en lugar de esperar al cuerpo de una respuesta final.

Campo	Valor
Tipo	`boolean`
Predeterminado	`false`
Valores habituales	`true`, `false`

Actívalo para interfaces de chat, para mostrar tokens a medida que llegan o para respuestas largas en las que recibir contenido antes mejora la experiencia. Desactívalo si quieres una única respuesta JSON completa, reintentos más sencillos o un análisis estructurado más simple. Notas:

La compatibilidad con la transmisión varía según el endpoint.
El streaming suele ser una opción de transporte, no un control de calidad.
Los flujos con llamadas a herramientas o salidas estructuradas pueden transmitirse de forma distinta según el proveedor.

`temperature`

Controla el grado de aleatoriedad al seleccionar tokens.

Campo	Valor
Tipo	`number`
Rango habitual	De `0.0` a `2.0` cuando sea compatible
Predeterminado	Específico del proveedor y del modelo
Buen punto de partida	`0.2` to `0.7`

Los valores bajos producen resultados más conservadores y repetibles. Los valores altos aumentan la variedad, lo que puede ayudar con la lluvia de ideas o la escritura creativa, pero también reducir la coherencia y el cumplimiento del esquema. Usos adecuados:

extracción
clasificación
salida JSON o con esquema
generación creativa

Consejos prácticos:

Empieza con un valor bajo para tareas estructuradas.
Cambia primero temperature o top_p, pero no ambos a la vez.
Una temperatura alta combinada con una cuantización agresiva puede aumentar la inestabilidad.

`top_p`

Aplica nucleus sampling y limita los candidatos al conjunto más pequeño de tokens cuya probabilidad acumulada alcanza top_p.

Campo	Valor
Tipo	`number`
Rango habitual	De `0.0` a `1.0` cuando sea compatible
Predeterminado	Específico del proveedor y del modelo
Buen punto de partida	`0.9` to `1.0`

Los valores bajos hacen que el modelo elija de una masa de probabilidad más estrecha y suelen generar resultados más seguros y enfocados. Los valores altos permiten considerar más tokens. Notas:

Ajusta top_p si quieres ampliar o reducir el espacio de búsqueda sin cambiar directamente la temperatura.
Para la mayoría de las aplicaciones, una temperature moderada y un top_p cercano a 1,0 son un punto de partida razonable.

`top_k`

En los proveedores que lo admiten, limita el muestreo a los k tokens candidatos principales en cada paso.

Campo	Valor
Tipo	`integer`
Rango habitual	`>= 1` cuando sea compatible
Predeterminado	Específico del proveedor y del modelo

Los valores bajos de top_k limitan las opciones del modelo y pueden hacer que la salida sea más predecible. Los valores altos amplían el conjunto de candidatos. Notas:

top_k no está disponible con todos los proveedores.
Considéralo un limitador del conjunto de tokens más explícito que top_p.

`max_tokens`

Limita la longitud de salida en los endpoints y proveedores que aún usan el campo max_tokens.

Campo	Valor
Tipo	`integer`
Rango habitual	`>= 1`
Predeterminado	Específico del proveedor y del modelo

Úsalo para controlar el coste, la latencia y el riesgo de truncamiento. Si el valor es demasiado bajo, la salida puede parecer incompleta aunque el modelo haya funcionado correctamente.

`max_output_tokens`

Limita la longitud de salida en las rutas que usan max_output_tokens en lugar de max_tokens.

Campo	Valor
Tipo	`integer`
Rango habitual	`>= 1`
Predeterminado	Específico del proveedor y del modelo

Tiene el mismo significado que max_tokens, pero debes enviar el nombre de campo que espera el endpoint o la interfaz del SDK seleccionados.

`max_completion_tokens`

Limita la longitud de salida en las API de texto más recientes al estilo OpenAI que usan max_completion_tokens.

Campo	Valor
Tipo	`integer`
Rango habitual	`>= 1`
Predeterminado	Específico del proveedor y del modelo

Es otro campo de límite de tokens de salida. Usa el nombre esperado por el endpoint en lugar de mezclar alias de longitud de salida en una misma solicitud.

`frequency_penalty`

Desalienta la repetición de tokens en proporción a la frecuencia con la que ya han aparecido.

Campo	Valor
Tipo	`number`
Rango habitual	Normalmente de `-2.0` a `2.0` cuando sea compatible
Predeterminado	Normalmente `0`

Aumenta este valor si el modelo entra en bucles, repite frases o abusa de las mismas expresiones.

`presence_penalty`

Desalienta reutilizar tokens desde su primera aparición, lo que puede ayudar al modelo a explorar temas o expresiones nuevos.

Campo	Valor
Tipo	`number`
Rango habitual	Normalmente de `-2.0` a `2.0` cuando sea compatible
Predeterminado	Normalmente `0`

En comparación con frequency_penalty, suele ser un control de novedad más amplio y no un control de la cantidad de repeticiones.

`repetition_penalty`

Aplica un comportamiento de control de repeticiones específico del proveedor, distinto de los campos clásicos de penalización al estilo OpenAI.

Campo	Valor
Tipo	`number`
Rango habitual	Específico del proveedor y del modelo; a menudo, entre `0.0` y `2.0`
Predeterminado	Específico del proveedor y del modelo

Su propósito es similar al de frequency_penalty y presence_penalty, pero su significado varía más según el proveedor. Considéralo un comportamiento nativo del proveedor, no un control universalmente idéntico.

`seed`

Solicita un muestreo determinista cuando el proveedor ascendente admite la generación con semilla.

Campo	Valor
Tipo	`integer`
Predeterminado	Sin establecer

Úsalo para depurar, hacer pruebas de regresión y reproducir el comportamiento con la mayor fidelidad que permita la plataforma ascendente. La generación con semilla mejora la reproducibilidad, pero no garantiza un determinismo exacto en todos los proveedores ni ante cambios de infraestructura.

`stop`

Define una o más secuencias que detienen la generación antes de tiempo.

Campo	Valor
Tipo	`string` or `string[]`
Predeterminado	Sin establecer
Uso habitual	Límites del analizador, finales de plantilla e indicadores de protocolo

Es útil cuando necesitas límites estrictos para la salida, por ejemplo, detenerla antes de un pie de página, un delimitador de herramienta o la siguiente sección generada.

`logprobs`

Solicita metadatos de probabilidad por token cuando están disponibles.

Campo	Valor
Tipo	`boolean`
Predeterminado	`false`

Es principalmente útil para análisis, evaluación, clasificación, depuración y flujos de trabajo relacionados con la confianza. Normalmente no se necesita en respuestas de producto estándar.

`top_logprobs`

Solicita los principales tokens candidatos alternativos para cada posición de salida junto con sus probabilidades logarítmicas.

Campo	Valor
Tipo	`integer`
Rango habitual	Específico del proveedor, normalmente de `0` a `20`
Requiere	`logprobs: true`

Úsalo cuando necesites inspeccionar las alternativas de tokens, además del token de salida seleccionado.

`tools`

Declara herramientas o funciones invocables para flujos de trabajo con modelos que usan herramientas.

Campo	Valor
Tipo	`array`
Predeterminado	Sin establecer

Salvo que la documentación del endpoint indique otra cosa, usa el esquema de herramientas al estilo OpenAI. Las declaraciones describen qué puede invocar el modelo, no si debe hacerlo.

`tool_choice`

Controla si el modelo puede llamar herramientas automáticamente, no debe llamarlas o debe usar una herramienta específica.

Campo	Valor
Tipo	`string` or `object`
Valores habituales	`none`, `auto`, `required`

Usa none si solo quieres contenido, auto si el modelo puede decidir y valores más estrictos si la orquestación posterior requiere una llamada a herramienta.

`parallel_tool_calls`

Permite o impide llamadas concurrentes a herramientas en las API compatibles.

Campo	Valor
Tipo	`boolean`
Predeterminado	Específico del endpoint y del proveedor

Desactívalo si los sistemas posteriores requieren una ejecución estrictamente secuencial, efectos secundarios ordenados o trazas de agente más sencillas.

`response_format`

Solicita un formato de salida concreto, como texto sin formato, JSON o respuestas restringidas por esquema.

Campo	Valor
Tipo	`string` or `object`
Predeterminado	Específico del endpoint y del proveedor

Las estructuras exactas aceptadas dependen del endpoint y del adaptador del proveedor. Úsalo si necesitas algo más que texto libre, sobre todo para respuestas JSON y flujos de extracción estructurada.

`structured_outputs`

Indica la compatibilidad con respuestas estructuradas fiables o restringidas por esquema en la ruta y el conjunto de proveedores seleccionados.

Campo	Valor
Tipo	`boolean`
Significado	Indicador de capacidad, no un control de ajuste directo

En las tablas de inicio rápido, indica si el endpoint seleccionado y los proveedores activos admiten flujos de salida estructurada de forma fiable. Debe interpretarse como metadatos de compatibilidad.

`json_schema`

Proporciona el esquema JSON que se usa para exigir una salida estructurada en modelos y endpoints compatibles.

Campo	Valor
Tipo	`object`
Se usa con	Flujos de salida estructurada o respuestas restringidas por esquema

Úsalo si tu aplicación necesita campos garantizados, extracción tipada o un contrato de respuesta estricto. Mantén los esquemas acotados y específicos para cada tarea para mejorar su cumplimiento.

`reasoning`

Contiene la configuración de razonamiento específica del proveedor para las API compatibles con razonamiento.

Campo	Valor
Tipo	`object`
Predeterminado	Sin establecer

Según la ruta, puede indicar si está habilitada, el nivel de razonamiento, el presupuesto de tokens, el nivel de detalle o si se devuelve contenido de razonamiento.

`reasoning_effort`

Solicita un presupuesto de razonamiento menor o mayor cuando el endpoint y el modelo ofrecen este control.

Campo	Valor
Tipo	`string`
Valores habituales	Específico del proveedor; suele aceptar valores como `minimal`, `low`, `medium`, `high` y `none`
Predeterminado	Específico del proveedor y del modelo

Un mayor esfuerzo puede mejorar tareas de razonamiento difíciles a costa de la latencia y el uso de tokens. Un esfuerzo menor suele ser más adecuado para solicitudes rápidas y económicas.

`reasoning_tokens`

Representa un campo de tokens específico del razonamiento cuando está disponible.

Campo	Valor
Tipo	`integer`
Predeterminado	Específico del proveedor y del modelo

Según la ruta, puede ser un control de solicitud, un límite o un campo de contabilización de la respuesta, y no un parámetro de solicitud universalmente compatible.

`include_reasoning`

Solicita contenido o resúmenes del razonamiento en las respuestas cuando están disponibles.

Campo	Valor
Tipo	`boolean`
Predeterminado	`false`

Úsalo con cuidado. Los datos de razonamiento pueden ser más grandes, no estar disponibles en todos los modelos y no ser adecuados para respuestas de producción que no necesiten detalles de diagnóstico adicionales.

`service_tier`

Selecciona un nivel de enrutamiento o precio compatible en las API de texto correspondientes.

Campo	Valor
Tipo	`string`
Valores admitidos	`standard`, `fast`, `ultrafast`, `priority`, `flex`
Predeterminado	`standard`

Usa ultrafast, fast (o priority donde sea compatible) y flex solo si la combinación de modelo y proveedor elegida los admite. Ultrafast selecciona el nivel compatible más rápido; fast y priority usan el mismo enrutamiento y precio Fast. Omite el campo para mantener el nivel estándar predeterminado. Phaseo convierte internamente los valores de nivel unificados de la pasarela en controles nativos del proveedor, de modo que los clientes pueden usar los mismos valores de service_tier en todas las interfaces de texto compatibles. Notas:

Batch es un flujo de API independiente, no un valor del nivel de servicio.
La compatibilidad varía según el endpoint y el proveedor.

`prompt_cache_key`

Proporciona una clave de afinidad de caché estable para un enrutamiento que tiene en cuenta la caché de prompts.

Campo	Valor
Tipo	`string`
Uso	Enrutamiento persistente para prompts almacenados en caché que están relacionados

Úsalo cuando varias solicitudes compartan prefijos de prompt estables y convenga usar el mismo proveedor o región upstream. Phaseo también puede deducir la afinidad de caché del contexto de la solicitud, pero una clave explícita es mejor para conversaciones largas, sesiones de agente y flujos repetidos.

`prompt_cache_options`

Transmite los controles de caché de prompts de OpenAI en las rutas compatibles de OpenAI.

Campo	Valor
Tipo	`object`
Campos habituales	`mode`, `ttl`
Astra TTL	`30m`

Para GPT-6 Astra, usa {"mode":"explicit","ttl":"30m"} cuando quieras caché de prompts explícita. Phaseo conserva este objeto durante la normalización de la solicitud y lo envía a OpenAI sin cambios.

`cache_control`

Aplica una política de caché de prompts independiente del proveedor en las interfaces de solicitud de texto compatibles.

Campo	Valor
Tipo	`object`
Campos comunes	`type`, `ttl`, `scope`
Uso	Caché automático de prompts y puntos de ruptura explícitos

Usa cache_control en el nivel superior de las solicitudes Chat Completions, Responses y Anthropic Messages para enviar la misma indicación de caché mediante el esquema común del gateway. También puedes incluir cache_control en los bloques de contenido compatibles para definir puntos de ruptura explícitos de caché. Los valores TTL habituales son 5m y 1h, según la compatibilidad del proveedor y el modelo. Se siguen aceptando alias específicos del proveedor, como provider_options.anthropic.cache_control y provider_options.google.cache_control, para integraciones nativas.

`prompt_cache_retention`

Establece la política de retención de caché de prompts compatible con OpenAI en las solicitudes compatibles enrutadas a OpenAI.

Campo	Valor
Tipo	`string`
Ejemplo	`24h`
Uso	Retención de caché de prompts de OpenAI

Úsalo para enviar opciones de retención de caché de OpenAI sin anidarlas en las opciones específicas del proveedor. Se sigue aceptando el alias provider_options.openai.prompt_cache_retention. Si se especifican ambos, prevalece el valor de nivel superior prompt_cache_retention.

`provider`

Contiene restricciones de enrutamiento y preferencias de proveedor.

Campo	Valor
Tipo	`object`
Uso	Reglas de enrutamiento, selección de proveedor y requisitos de cumplimiento

Úsalo para indicar qué proveedores upstream pueden ejecutar la solicitud, cómo deben ordenarse o qué requisitos de cumplimiento deben satisfacer. Entre los campos habituales se incluyen:

Campo	Tipo	Propósito
`order`	`string[]`	Orden de preferencia de los proveedores.
`only`	`string[]`	Limita el enrutamiento a proveedores específicos.
`ignore`	`string[]`	Excluye proveedores específicos.
`include_alpha`	`boolean`	Permite proveedores alpha en las decisiones de enrutamiento.
`sort`	`string` or `object`	Ordena los proveedores, normalmente por `price`, `latency` o `throughput`.
`required_execution_region`	`string`	Limita la ejecución a una región obligatoria.
`required_data_region`	`string`	Limita el tratamiento de datos a una región obligatoria.
`require_zero_data_retention`	`boolean`	Exige proveedores que cumplan las condiciones de retención cero de datos.
`max_price`	`object`	Establece límites máximos para los costes de prompt, finalización, imagen, audio o solicitud.
`quantizations`	`string[]`	Exige una oferta válida cuya cuantización del catálogo coincida con uno de estos valores.

quantizations sigue el vocabulario de enrutamiento de proveedores compatible con OpenRouter y se acepta tanto en provider como en routing. La coincidencia no distingue mayúsculas, y omite espacios, guiones y guiones bajos; los nombres inequívocos como float8/FP8 y bfloat16/BF16 son alias. Si este filtro está presente, se excluyen las ofertas sin metadatos de cuantización. Si ninguna oferta válida coincide, el Gateway devuelve un error con las cuantizaciones solicitadas y disponibles, en lugar de enrutar silenciosamente a otra variante.

`provider_options`

Contiene ajustes de transferencia específicos del proveedor que no deben normalizarse en la estructura de solicitud común del gateway.

Campo	Valor
Tipo	`object`
Uso	Controles nativos del proveedor

Algunos ejemplos:

openai.context_management
openai.prompt_cache_retention
anthropic.cache_control
google.cache_control
google.cached_content

Úsalo cuando necesites una función nativa del proveedor y quieras mantener el resto de la solicitud en el esquema común del gateway. Para indicaciones de caché comunes, prefiere cache_control en el nivel superior; para la retención compatible con OpenAI, usa prompt_cache_retention en el nivel superior. Para ver ejemplos de caché de prompts por proveedor en Chat Completions, Responses y Anthropic Messages, consulta Caché de prompts.

`meta`

Solicita metadatos adicionales en la respuesta cuando están disponibles.

Campo	Valor
Tipo	`boolean`
Predeterminado	Específico del endpoint

Úsalo si necesitas metadatos adicionales no esenciales en la respuesta para depuración, análisis o inspección posterior.

`usage`

Solicita detalles de contabilización del uso cuando están disponibles.

Campo	Valor
Tipo	`boolean`
Predeterminado	Específico del endpoint

Es útil si quieres incluir explícitamente el recuento de tokens o del uso en el cuerpo de la respuesta, en lugar de depender solo de los encabezados o paneles.

`debug`

Activa diagnósticos controlados de solicitudes y enrutamiento.

Campo	Valor
Tipo	`object`
Uso	Solo para desarrollo y resolución de problemas

Entre los campos de depuración compatibles se incluyen:

Campo	Tipo	Propósito
`enabled`	`boolean`	Activa el modo de depuración para la solicitud.
`return_upstream_request`	`boolean`	Incluye el contenido transformado de la solicitud enviada al proveedor ascendente.
`return_upstream_response`	`boolean`	Incluye el contenido de la respuesta ascendente cuando está disponible.
`trace`	`boolean`	Devuelve trazas de enrutamiento o depuración.
`trace_level`	`summary` or `full`	Controla el nivel de detalle de las trazas.

Los datos de depuración pueden contener contexto confidencial de la solicitud. Úsalos solo durante el desarrollo o en entornos estrictamente controlados.

Ejemplo de solicitud

{
  "model": "openai/gpt-5-nano",
  "input": "Summarize this changelog.",
  "stream": false,
  "temperature": 0.3,
  "max_output_tokens": 300,
  "provider": {
    "order": ["openai", "anthropic"],
    "ignore": ["some-provider"],
    "sort": "latency",
    "required_execution_region": "eu",
    "require_zero_data_retention": true
  },
  "debug": {
    "enabled": true,
    "trace": true,
    "trace_level": "summary"
  }
}

Explicaciones detalladas

Si buscas una guía más detallada sobre cómo ajustar estos valores, en lugar de una referencia básica de los campos, consulta estas páginas:

Parámetros de inferencia para consejos prácticos sobre temperature, top_p, top_k, límites de tokens, secuencias de parada y flujos de ajuste
Muestreo y decodificación para entender cómo la aleatoriedad, las penalizaciones y los controles de decodificación cambian el comportamiento del modelo

​Consulta rápida

​Notas sobre endpoints

​Referencia de parámetros

​model

​stream

​temperature

​top_p

​top_k

​max_tokens

​max_output_tokens

​max_completion_tokens

​frequency_penalty

​presence_penalty

​repetition_penalty

​seed

​stop

​logprobs

​top_logprobs

​tools

​tool_choice

​parallel_tool_calls

​response_format

​structured_outputs

​json_schema

​reasoning

​reasoning_effort

​reasoning_tokens

​include_reasoning

​service_tier

​prompt_cache_key

​prompt_cache_options

​cache_control

​prompt_cache_retention

​provider

​provider_options

​meta

​usage

​debug

​Ejemplo de solicitud

​Explicaciones detalladas

​Páginas relacionadas