Skip to main content
Utiliza el recurso de Respuestas cuando quieras que la API MKA1 devuelva texto. Comienza con una cadena simple para prompts sencillos. Utiliza elementos de mensaje cuando necesites roles explícitos o estado de conversación. Las secciones posteriores tratan los límites de muestreo y longitud, el esfuerzo de razonamiento y los campos de la solicitud que descarta el gateway. Pausar una respuesta en segundo plano tiene su propia sección en respuestas en segundo plano.

​
Enviar un prompt simple

Pasa una cadena en input para una solicitud de un solo turno. La respuesta incluye el texto generado en output_text. Si un guardrail bloquea la solicitud, output_text no aparece y la salida contiene un rechazo; consulta Guardrails.
Si no estás actuando en nombre de un usuario final, omite X-On-Behalf-Of.

​
Agregar instrucciones

Utiliza instructions para definir el comportamiento antes de que el modelo vea la entrada del usuario. Mantén las instrucciones cortas y específicas.

​
Enviar mensajes estructurados

Utiliza un arreglo de elementos de mensaje en input cuando quieras roles explícitos. Cada elemento de mensaje utiliza type, role y content.
Este patrón es útil cuando quieres que el cuerpo de la solicitud lleve directamente el historial de mensajes.

​
Continuar un intercambio de varios turnos

Utiliza previous_response_id para continuar desde una respuesta anterior sin reenviar todo el historial.
Si necesitas un contenedor de conversación reutilizable, créalo con el recurso de Conversaciones y luego pasa el ID de la conversación en conversation.
Nota: eliminar una conversación no elimina sus elementos. Consulta las páginas de Conversaciones y Respuestas en la Referencia de la API para ver el flujo de trabajo completo del recurso.

​
Transmitir texto a medida que se genera

Establece stream en true para recibir eventos enviados por el servidor en lugar de esperar la respuesta completa.
Utiliza el streaming cuando quieras mostrar la salida parcial a medida que llega.

​
Ajustar el muestreo y la longitud

Los campos de muestreo cambian cómo elige el modelo cada token. Los campos de longitud limitan cuánto escribe. Todos son opcionales y van en el nivel superior de la solicitud, junto a model e input.
El gateway valida cada valor antes de llamar al modelo. Un valor fuera de su rango devuelve 400. En el ejemplo, revisa status: si el modelo llegó al límite de 400 tokens, la respuesta es incomplete en lugar de completed, y usage.output_tokens queda en el límite o por debajo. Algunos campos de la tabla son extensiones del gateway. No forman parte de la API Responses de OpenAI, y que lleguen al modelo depende de su upstream, la API del proveedor a la que el gateway reenvía tu solicitud, que usa el formato Responses o el formato Completions. Los campos marcados como extensiones del gateway no forman parte de la API Responses de OpenAI, así que los tipos del SDK de OpenAI no los conocen. Envíalos con el SDK de MKA1, la CLI o HTTP directo. Otras cuatro extensiones del gateway pasan opciones del proveedor sin cambios: chat_template_kwargs (por ejemplo {"enable_thinking": false}), prefill_think (un booleano o un texto de prellenado), use_cache y extra_body, un objeto que se combina con la solicitud upstream después de que el gateway elimina de él cualquier clave de autenticación, de URL base o de encabezados. No todos los campos llegan a todos los modelos. Campos que descarta el gateway enumera los casos.

​
Comprobar qué admite un modelo

No todos los modelos aceptan todos los campos. GET /api/v1/llm/models/{model_id} devuelve un objeto capabilities con cuatro booleanos: Los modelos que no son LLM (embeddings, imágenes, voz) indican false en los cuatro. El objeto del modelo también incluye input_modalities y output_modalities, los tipos de contenido que el modelo acepta y produce, como ["text", "image"].
Si envías un campo a un modelo que indica false para él, el gateway no rechaza la solicitud. Descarta ese campo antes de llamar al modelo, reenvía todo lo demás y el modelo usa su propio valor predeterminado para ese ajuste. Nada en la respuesta indica que el campo se descartó: devuelve temperature, top_p y reasoning tal como los enviaste. Comprueba primero las capacidades del modelo cuando el ajuste importe.

​
Controlar el razonamiento

Los modelos de razonamiento piensan antes de responder. El objeto reasoning define cuánto razonamiento quieres y si lo ves:
  • effort: none, minimal, low, medium, high o xhigh.
  • summary: auto, concise o detailed. Pide al modelo que devuelva un resumen legible de su razonamiento.
Ambas claves deben estar presentes siempre que envíes el objeto. Pon en null la que no uses. {"effort": "low"} por sí solo no pasa la validación. Cada clave llega al modelo solo cuando el modelo puede usarla:
  • effort solo se envía a modelos que indican supports_reasoning_effort: true. Un upstream con formato Completions lo recibe como reasoning_effort.
  • summary solo se envía a modelos que indican supports_reasoning: true y cuyo upstream usa el formato Responses.
El gateway descarta una clave que el modelo no puede usar, y la solicitud se completa igualmente.
El tipo ReasoningEffort del SDK de OpenAI no incluye none ni xhigh; envía esos valores con el SDK de MKA1, la CLI o HTTP directo. El razonamiento aparece en tres lugares:
  • output puede contener un elemento con type: "reasoning". Su arreglo summary contiene partes summary_text, y content (cuando existe) contiene las partes reasoning_text sin procesar. Agrega "reasoning.encrypted_content" a include para obtener también encrypted_content.
  • usage.output_tokens_details.reasoning_tokens es la parte de output_tokens que el modelo dedicó a razonar. Los tokens de razonamiento son tokens de salida, así que cuentan para max_output_tokens.
  • En un stream, los eventos response.reasoning_text.delta y response.reasoning_summary_text.delta suelen llegar antes que los eventos response.output_text.delta. La prueba de rendimiento de latencia de salida en streaming muestra este orden en un modelo real.
Para saber antes de la llamada si un modelo razona y si acepta effort, lee supports_reasoning y supports_reasoning_effort como se muestra en Comprobar qué admite un modelo. Después de la llamada, usage.output_tokens_details.reasoning_tokens muestra cuánto razonamiento hubo. Cuando envías model: "auto", el gateway aplica la política auto de la organización para Responses. La política predeterminada es un alias directo del registro de modelos. Un administrador de la organización puede configurar una política equilibrada que pide a un LLM juez elegir entre los modelos aptos según capacidad, precio, latencia del gateway, evaluaciones comparables, requisitos de la solicitud y continuidad de la conversación. El enrutamiento no cambia el reasoning.effort que envías, pero el gateway lo descarta igualmente cuando el modelo elegido indica supports_reasoning_effort: false. Enrutamiento automático explica la política y su comportamiento ante fallos y en materia de privacidad.

​
Campos que descarta el gateway

Cada campo de abajo pasa la validación, pero el gateway lo descarta antes de llamar al modelo en el caso indicado. Un campo descartado nunca hace fallar la solicitud, y nada en la respuesta indica que se descartó. Algunos casos dependen del upstream del modelo, la API del proveedor a la que el gateway reenvía tu solicitud. Como los campos desconocidos se eliminan en silencio, un nombre de campo mal escrito parece aceptado pero no tiene efecto. Si un ajuste parece no hacer nada, compara tu solicitud con la referencia de la API.

​
Pausar una respuesta en segundo plano

Una respuesta en segundo plano puede llamar a la herramienta sleep para esperar hasta 20 minutos un webhook o un trabajo externo, y puedes despertarla antes con una entrada de seguimiento. Consulta respuestas en segundo plano.

​
Próximos pasos