Saltar al contenido principal
POST
/
api
/
v1
/
llm
/
responses
Python (SDK)
from mka1 import SDK


with SDK(
    bearer_auth="<YOUR_BEARER_TOKEN_HERE>",
) as sdk:

    res = sdk.llm.responses.create(model="meetkai:functionary-urdu-mini-pak", input="What is the capital of France?", stream=False, store=True, background=False, parallel_tool_calls=True, max_tool_calls=64, truncation="auto", service_tier="auto")

    with res as event_stream:
        for event in event_stream:
            # handle event
            print(event, flush=True)
{
  "id": "resp_abc123",
  "object": "response",
  "created_at": 1735689600,
  "completed_at": 1735689601,
  "status": "completed",
  "error": null,
  "incomplete_details": null,
  "background": false,
  "instructions": null,
  "max_output_tokens": null,
  "max_tool_calls": 30,
  "metadata": {},
  "model": "meetkai:functionary-urdu-mini-pak",
  "output": [
    {
      "type": "message",
      "id": "msg_abc123",
      "role": "assistant",
      "content": [
        {
          "type": "output_text",
          "text": "The capital of France is Paris.",
          "annotations": []
        }
      ],
      "status": "completed"
    }
  ],
  "output_text": "The capital of France is Paris.",
  "parallel_tool_calls": true,
  "previous_response_id": null,
  "reasoning": {
    "effort": null,
    "summary": null
  },
  "service_tier": "auto",
  "store": true,
  "text": {
    "format": {
      "type": "text"
    },
    "verbosity": "medium"
  },
  "tool_choice": "auto",
  "tools": [],
  "truncation": "auto",
  "usage": {
    "input_tokens": 8,
    "input_tokens_details": {
      "cached_tokens": 0
    },
    "output_tokens": 7,
    "output_tokens_details": {
      "reasoning_tokens": 0
    },
    "total_tokens": 15
  },
  "user": null
}

Documentation Index

Fetch the complete documentation index at: https://docs.mka1.com/llms.txt

Use this file to discover all available pages before exploring further.

Autorizaciones

​
Authorization
string
header
requerido

Gateway auth: send Authorization: Bearer <mka1-api-key>. For multi-user server-side integrations, you can also send X-On-Behalf-Of: <external-user-id>.

Encabezados

​
X-On-Behalf-Of
string

Optional external end-user identifier forwarded by the API gateway.

Cuerpo

application/json

Esquema de solicitud para crear una nueva respuesta de agente. Configura el modelo del agente, la entrada, las herramientas, el formato de salida y el comportamiento. Soporta tanto la ejecución en primer plano (bloqueante) como en segundo plano (asíncrona) con transmisión opcional.

​
model
string
requerido

La ID del modelo a utilizar para generar la respuesta.

​
input

La entrada del usuario que se enviará al agente. Puede ser una cadena de texto simple para consultas básicas, o un array de objetos de ítems que contienen texto, imágenes, archivos o audio para interacciones multimodales. Este es el contenido principal al que el agente responderá.

​
instructions
string

Instrucciones del sistema o del desarrollador insertadas en el contexto del modelo antes de la entrada del usuario. Utiliza esto para guiar el comportamiento del agente, establecer la personalidad, definir limitaciones o proporcionar conocimientos específicos del dominio. Actúa como un mensaje del sistema persistente para esta respuesta.

​
conversation

La conversación a la que pertenece esta respuesta. Puede ser una cadena de identificación de conversación o un objeto de conversación. Se utiliza para mantener el contexto y la historia a través de múltiples interacciones con agentes. Opcional: omitir para interacciones únicas.

​
previous_response_id
string

El ID único de una respuesta anterior para continuar. Se utiliza para conversaciones de múltiples turnos para mantener el contexto y el historial. El agente tendrá acceso a todas las interacciones anteriores en la cadena.

​
prompt
object

Referencia a una plantilla de aviso para usar en esta respuesta, junto con variables a sustituir. Permite utilizar plantillas de aviso predefinidas y versionadas en lugar de instrucciones en línea. El sistema de plantillas soporta la interpolación de variables.

​
include
enum<string>[]

Campos adicionales para incluir en la salida de respuesta. Permite solicitar datos anidados específicos como fuentes de búsqueda en la web, salidas del intérprete de código, capturas de pantalla de computadora, resultados de búsqueda de archivos, imágenes de entrada, logprobs de salida o contenido de razonamiento. Estos campos pueden tener implicaciones en el rendimiento o en el costo.

Opciones disponibles:
web_search_call.action.sources,
code_interpreter_call.outputs,
computer_call_output.output.image_url,
file_search_call.results,
message.input_image.image_url,
message.output_text.logprobs,
reasoning.encrypted_content
​
text
object

Opciones de configuración para la salida de texto del modelo. Incluye formato de respuesta (texto, objeto JSON, esquema JSON) y nivel de verbosidad (bajo, medio, alto). Utiliza esto para controlar la estructura de salida y el nivel de detalle.

​
stream
boolean
predeterminado:false

Si se establece en verdadero, los datos de la respuesta se transmitirán utilizando Eventos Enviados por el Servidor (SSE) para actualizaciones en tiempo real a medida que el agente genera la respuesta. Cuando es falso, la respuesta se devuelve como un único objeto completo. Por defecto es falso.

​
stream_options
object

Opciones adicionales para configurar el comportamiento de transmisión cuando el streaming está habilitado.

​
store
boolean
predeterminado:true

Si almacenar la respuesta generada para su recuperación posterior. Cuando es verdadero, la respuesta se guarda y se puede recuperar a través de GET /responses/{id}. Cuando es falso, la respuesta no se persiste después de la generación. Por defecto es verdadero.

​
background
boolean
predeterminado:false

Ya sea para ejecutar la respuesta del modelo en segundo plano de forma asíncrona. Cuando es verdadero, la solicitud devuelve inmediatamente un ID de respuesta mientras el agente procesa en segundo plano. Utilice GET /responses/{id} para recuperar resultados más tarde. Cuando es falso, la solicitud se bloquea hasta completarse. Por defecto es falso.

​
webhook_url
string<uri>

URL para recibir notificaciones de webhook sobre cambios de estado (en cola, en progreso, completado, fallido, incompleto). Solo es válido cuando background=true. Si se proporciona sin background=true, la solicitud será rechazada.

​
webhook_secret
string

Secreto opcional para la firma HMAC-SHA256 de las cargas útiles de webhook. Cuando se proporciona, los webhooks incluyen un encabezado X-Webhook-Signature con la firma. Requiere que se establezca webhook_url.

Required string length: 16 - 256
​
tools
(Function tool definition · object | File search tool definition · object | Computer use tool definition · object | Web search tool definition · object | MCP tool definition · object | Code interpreter tool definition · object | Image generation tool definition · object | Local shell tool definition · object | Shell tool definition · object | Custom tool definition · object | Web search preview tool definition · object | Hosted tool definition · object | Sleep tool definition · object | History tool definition · object)[]

Array de definiciones de herramientas que el agente puede utilizar durante la generación de respuestas. Soporta herramientas integradas (búsqueda web, búsqueda de archivos, intérprete de código, uso de computadora, generación de imágenes) y herramientas personalizadas (funciones, MCP, shell local). Cada definición de herramienta especifica su tipo y configuración.

Definición de herramienta de función: Define una herramienta de función que se puede llamar. Proporcione un nombre de herramienta y un esquema de parámetros, con una descripción opcional y carga diferida.

​
tool_choice

Controles cómo el agente selecciona qué herramientas usar. Puede ser 'ninguna' (sin herramientas), 'automático' (el modelo decide), 'requerido' (debe usar herramientas) o un objeto de selección de herramientas específico. Utilice esto para forzar o evitar el uso de herramientas.

Opciones disponibles:
none,
auto,
required
​
parallel_tool_calls
boolean
predeterminado:true

Si permitir que el agente ejecute múltiples llamadas a herramientas en paralelo. Cuando es verdadero, el agente puede hacer llamadas a herramientas de manera concurrente para mayor eficiencia. Cuando es falso, las herramientas se llaman de manera secuencial. Por defecto, es verdadero para un mejor rendimiento.

​
max_tool_calls
integer
predeterminado:64

El número total máximo de llamadas a herramientas que el agente puede hacer durante esta respuesta. Útil para controlar el tiempo de ejecución y prevenir bucles infinitos. Se aplica a todas las herramientas integradas como búsqueda web, búsqueda de archivos, intérprete de código, etc. Debe ser un entero positivo entre 1 y 300. Por defecto es 64.

Rango requerido: 1 <= x <= 300
​
reasoning
object

Opciones de configuración para modelos de razonamiento. Controla el nivel de esfuerzo de razonamiento (mínimo, bajo, medio, alto) y la verbosidad del resumen (automático, conciso, detallado). Solo aplicable a modelos específicos capaces de razonar.

​
auto_routing
boolean

Cuando es verdadero, el gateway inspecciona la complejidad de la solicitud y enruta automáticamente entre variantes cuantizadas, MoE y densas dentro de la familia de modelos solicitada.

​
auto_routing_debug
boolean

Extensión de puerta de enlace. Cuando es verdadero junto con auto_routing, los metadatos de respuesta incluyen una decisión de enrutamiento serializada compacta para que puedas inspeccionar el nivel objetivo inferido incluso cuando no hay una variante compatible disponible.

​
max_output_tokens
integer

El número máximo de tokens que el modelo puede generar en su salida. Establece un límite superior para controlar costos y la longitud de la respuesta. La salida real puede ser más corta si el modelo termina de manera natural. Debe ser un número entero positivo.

Rango requerido: 1 <= x <= 9007199254740991
​
temperature
number

Controla la aleatoriedad en la salida del modelo. Valores más altos (por ejemplo, 1.5-2.0) hacen que la salida sea más aleatoria y creativa, mientras que valores más bajos (por ejemplo, 0.0-0.5) la hacen más enfocada y determinista. Debe estar entre 0 y 2.

Rango requerido: 0 <= x <= 2
​
top_p
number

Parámetro de muestreo de núcleo. El modelo considera solo los tokens con una probabilidad acumulada top_p. Valores más bajos (por ejemplo, 0.1) hacen que la salida sea más enfocada, valores más altos (por ejemplo, 0.9) permiten más diversidad. Debe estar entre 0 y 1. Alternativa a la temperatura.

Rango requerido: 0 <= x <= 1
​
stop

Extensión de Gateway. Secuencia(s) de parada donde los proveedores ascendentes compatibles deben detener la generación. Las ejecuciones de evaluación también imponen esto como una protección de post-procesamiento.

​
top_k
integer

Extensión de puerta de enlace. Parámetro de muestreo top-k específico del proveedor.

Rango requerido: 0 <= x <= 9007199254740991
​
min_p
number

Extensión de puerta de enlace. Parámetro de muestreo min-p específico del proveedor.

Rango requerido: 0 <= x <= 1
​
repetition_penalty
number

Extensión de puerta de enlace. Penalización de repetición específica del proveedor.

Rango requerido: x >= 0
​
do_sample
boolean

Extensión de puerta de enlace. Alternar de muestreo específico del proveedor.

​
extra_body
object

Extensión de puerta de enlace. Passthrough de cuerpo de solicitud específico del proveedor controlado.

​
chat_template_kwargs
object

Extensión de puerta de enlace. Opciones de plantilla de chat específicas del proveedor, como enable_thinking=false.

​
prefill_think

Extensión de Gateway. Alternar la preconfiguración específica del proveedor o el texto de preconfiguración.

​
use_cache
boolean

Extensión de puerta de enlace. Interruptor de caché específico del proveedor donde sea compatible.

​
top_logprobs
integer

El número de tokens más probables para devolver en cada posición junto con sus probabilidades logarítmicas. Debe estar entre 0 y 20. Útil para comprender la confianza del modelo y explorar salidas alternativas.

Rango requerido: 0 <= x <= 20
​
truncation
enum<string>
predeterminado:auto

La estrategia de truncamiento para manejar entradas que exceden la ventana de contexto del modelo. 'auto' trunca automáticamente los mensajes antiguos para ajustarse, 'desactivado' devuelve un error si el contexto es demasiado largo. Por defecto, es 'auto'.

Opciones disponibles:
auto,
disabled
​
context_management
object[]

Estrategias de gestión del contexto para aplicar durante la generación de respuestas. Soporta la compresión, que resume el historial de conversación anterior cuando el contexto excede un umbral de tokens.

Maximum array length: 1
​
presence_penalty
number

Penaliza los nuevos tokens en función de si aparecen en el texto hasta ahora. Valores más altos aumentan la probabilidad de que el modelo hable sobre nuevos temas.

Rango requerido: -2 <= x <= 2
​
frequency_penalty
number

Penaliza los nuevos tokens según su frecuencia en el texto hasta ahora. Valores más altos disminuyen la probabilidad del modelo de repetir la misma línea al pie de la letra.

Rango requerido: -2 <= x <= 2
​
service_tier
enum<string>
predeterminado:auto

Especifica el nivel de procesamiento para atender la solicitud. 'auto' permite que el sistema elija, 'default' utiliza procesamiento estándar, 'flex' permite programación flexible para menor prioridad, 'priority' proporciona un procesamiento más rápido. Por defecto es 'auto'.

Opciones disponibles:
auto,
default,
flex,
priority
​
prompt_cache_key
string

Un identificador estable utilizado para almacenar en caché prompts y contexto. Ayuda a reducir costos y latencia al reutilizar el procesamiento de prompts almacenados en caché. Útil para prompts que se utilizan repetidamente con variaciones menores.

​
safety_identifier
string

Un identificador estable utilizado para ayudar a detectar y prevenir violaciones de políticas en múltiples solicitudes. Ayuda al sistema a identificar patrones de abuso o mal uso. Útil para el seguimiento de cumplimiento y la monitorización de la seguridad.

​
metadata
object
​
modalities
enum<string>[]

Tipos de salida que el modelo debe generar. Por defecto es ['text']. Incluye 'audio' para recibir una representación de audio de la respuesta de texto a través de TTS.

Opciones disponibles:
text,
audio
​
audio
object

Configuración de salida de audio. Opcional cuando las modalidades incluyen 'audio'; se aplican los valores predeterminados si se omite.

​
user
string

OBSOLETO: Un identificador único para el usuario final. Utilice safety_identifier para la detección de violaciones de políticas y prompt_cache_key para el almacenamiento en caché en su lugar. Este campo se mantiene para compatibilidad hacia atrás.

Respuesta

Respuesta exitosa: devuelve eventos de transmisión (SSE) o un objeto de respuesta completo (JSON) dependiendo del parámetro de transmisión.

​
id
string
requerido
​
object
any
requerido
​
created_at
number
requerido
​
completed_at
number | null
requerido
​
status
enum<string>
requerido

El estado general de la generación de respuestas. 'completado' significa finalizado con éxito, 'fallido' significa que ocurrió un error, 'en_proceso' significa que se está procesando actualmente, 'cancelado' significa cancelado por el usuario, 'en_cola' significa esperando a comenzar, 'incompleto' significa finalización parcial.

Opciones disponibles:
completed,
failed,
in_progress,
cancelled,
queued,
incomplete
​
error
object
requerido
​
incomplete_details
object
requerido
​
background
boolean
requerido
​
instructions
requerido
​
max_output_tokens
integer | null
requerido
Rango requerido: -9007199254740991 <= x <= 9007199254740991
Ejemplo:

null

​
max_tool_calls
integer | null
requerido
Rango requerido: -9007199254740991 <= x <= 9007199254740991
​
metadata
object
requerido
​
model
string
requerido
​
output
(Input message item · object | Output message item · object | Output audio item · object | File search call item · object | Computer call item · object | Computer call output item · object | Web search call item · object | Function call item · object | Function call output item · object | Reasoning item · object | Image generation call item · object | Code interpreter call item · object | Local shell call item · object | Local shell call output item · object | Shell call item · object | Shell call output item · object | MCP list tools item · object | MCP approval request item · object | MCP approval response item · object | MCP call item · object | Custom tool call item · object | Custom tool call output item · object | Item reference item · object | Compaction item · object)[]
requerido

Elemento del mensaje de entrada: Un mensaje con rol y contenido. Utiliza esto para turnos de usuario, asistente, sistema o desarrollador en entradas estructuradas.

​
parallel_tool_calls
boolean
requerido
​
previous_response_id
string | null
requerido
​
store
boolean
requerido
​
text
object
requerido
​
tool_choice
requerido

Modo de elección de herramientas: Selecciona cómo el modelo decide el uso de herramientas. Usa ninguno, automático o requerido.

Opciones disponibles:
none,
auto,
required
​
tools
(Function tool definition · object | File search tool definition · object | Computer use tool definition · object | Web search tool definition · object | any | Code interpreter tool definition · object | Image generation tool definition · object | Local shell tool definition · object | Shell tool definition · object | Custom tool definition · object | Web search preview tool definition · object | Hosted tool definition · object | Sleep tool definition · object | History tool definition · object | null)[]
requerido

Definición de herramienta de función: Define una herramienta de función que se puede llamar. Proporcione un nombre de herramienta y un esquema de parámetros, con una descripción opcional y carga diferida.

​
truncation
enum<string>
requerido
Opciones disponibles:
auto,
disabled
​
usage
object
requerido
​
user
string | null
requerido
​
conversation
object
​
output_text
string
​
prompt
object
​
prompt_cache_key
string
​
reasoning
object
​
safety_identifier
string
​
service_tier
enum<string>
Opciones disponibles:
auto,
default,
flex,
priority
​
temperature
number
Rango requerido: 0 <= x <= 2
​
presence_penalty
number
​
frequency_penalty
number
​
top_logprobs
integer
Rango requerido: 0 <= x <= 20
​
top_p
number
Rango requerido: 0 <= x <= 1
​
context_management
object[]