API de Keural

Llama a los modelos registrados en Keural con el formato OpenAI Chat Completions.

La URL base tiene el formato https://<su dominio público de API>/llm/v1. El dominio público de la API varía según el entorno; consulte con su administrador.

Las rutas de embeddings, generación de imágenes, voz y la API de Responses no se admiten, y devuelven 404.

Flujo de usoCopiar enlace de la sección

Requisitos previosCopiar enlace de la sección

Emitir una clave de APICopiar enlace de la sección

1. En el menú de cuenta, abra Configuración → API. En las aplicaciones de escritorio y móviles, está en el grupo Herramientas.
2. En la pestaña API keys, elija el espacio de trabajo al que pertenece la clave (personal u organización) y el Model ID.
3. Si lo necesita, establezca una New key expiration (optional, Korea time). Si lo deja vacío, la clave no caduca hasta que la revoque.
4. Pulse Issue key, copie la clave con Copy key y guárdela en un lugar seguro. La clave completa solo se muestra en ese momento y no se puede volver a ver al cerrar la pantalla.

• La clave está vinculada al espacio de trabajo elegido y a un modelo. El uso se atribuye a la persona que emitió la clave.
• Cada combinación de espacio de trabajo y modelo solo puede tener una clave utilizable. Si ya existe una, no se emite otra nueva: vuelva a emitirla (Rotate) o revóquela (Revoke).
• Si pierde la clave, no hay forma de volver a verla. Vuelva a emitirla; al hacerlo, la clave anterior deja de funcionar de inmediato.
• Si aparece el mensaje de que no hay modelos disponibles, revise la configuración de visibilidad de los modelos, su plan y el permiso de API de la organización con su administrador.

Permiso de API de los miembros de la organizaciónCopiar enlace de la sección

Solo lo gestionan los propietarios y administradores de la organización. Para que un miembro pueda emitir claves en un espacio de trabajo de organización, el administrador debe permitírselo antes. Tanto los miembros nuevos como los existentes tienen el acceso bloqueado de forma predeterminada.

Gestión de la organización → Organization API tiene tres secciones. Si no aparece el menú, la función de API está desactivada o su cuenta no tiene permisos de administración de la organización.

Cuando un miembro sale de la organización o es eliminado de ella, las claves que recibió en la organización se revocan automáticamente.

Conectar con un clienteCopiar enlace de la sección

Introduzca estos tres valores en las aplicaciones compatibles con OpenAI API (clientes de chat, extensiones de IDE, herramientas de automatización, etc.).

1. En la configuración de la aplicación, añada una conexión compatible con OpenAI (Connection).
2. Introduzca la Base URL y la API Key, y guarde.
3. Elija un modelo en la lista de modelos. La lista muestra solo el modelo conectado a la clave.
4. Envíe un mensaje corto para comprobar que recibe respuesta.

El formato de las solicitudes es el siguiente.

Primera solicitudCopiar enlace de la sección

export KEURAL_API_KEY='su_clave_emitida'
export KEURAL_BASE_URL='https://<su-dominio-de-api>/llm/v1'
export MODEL_ID='ID_del_modelo_en_la_pantalla_de_emisión'

curl "$KEURAL_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $KEURAL_API_KEY" \
  -H 'Content-Type: application/json' \
  -d "{\"model\":\"$MODEL_ID\",\"messages\":[{\"role\":\"user\",\"content\":\"Hola.\"}]}"

El model del cuerpo de la solicitud debe coincidir con el modelo conectado a la clave. Si lleva un prefijo de ruta, como provider/ID_del_modelo, se compara lo que viene después de la última /. Si no coincide, la API devuelve 403. La respuesta siempre incluye en model el ID del modelo de la clave.

from openai import OpenAI
import os

client = OpenAI(
    api_key=os.environ["KEURAL_API_KEY"],
    base_url=os.environ["KEURAL_BASE_URL"],
)
res = client.chat.completions.create(
    model=os.environ["MODEL_ID"],
    messages=[{"role": "user", "content": "Hola."}],
)
print(res.choices[0].message.content)

Campos de solicitud admitidosCopiar enlace de la sección

La API solo acepta estos 18 campos de nivel superior. Si envía otros, devuelve 400. Los campos opcionales con valor null se tratan como no enviados.

MensajesCopiar enlace de la sección

• Un mensaje tool responde una sola vez a cada id de los tool_calls anteriores.
• Las partes de imagen (image_url) solo se incluyen en los mensajes user de modelos que admiten imágenes. Use una dirección http o https, o un data URI base64 de PNG, JPEG, GIF o WebP. detail puede ser auto, low o high.

CuerpoCopiar enlace de la sección

Si incumple las reglas del cuerpo, se devuelve 400 con param igual a body.

StreamingCopiar enlace de la sección

Si incluye "stream": true en la solicitud, la respuesta llega por SSE. Cada fragmento se envía como un evento data: ..., y al final se envía data: [DONE]. Si incluye "stream_options": {"include_usage": true}, se envía un fragmento adicional con el uso de tokens justo antes de [DONE].

Con include_usage, todos los fragmentos contienen usage: null, y el último fragmento de uso tiene choices como matriz vacía. Las respuestas sin streaming solo incluyen usage cuando se han confirmado los tokens de entrada y de salida.

El id de la respuesta tiene el formato chatcmpl-<x-request-id>. Todas las respuestas incluyen el encabezado x-request-id.

Si se produce un error durante el streaming, se envía un evento data: con el JSON del error y la conexión se cierra sin [DONE]. Si un fragmento supera 1 MiB o la respuesta supera 16 MiB, la conexión termina con 503.

curl -N "$KEURAL_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $KEURAL_API_KEY" \
  -H 'Content-Type: application/json' \
  -d "{\"model\":\"$MODEL_ID\",\"messages\":[{\"role\":\"user\",\"content\":\"Hola.\"}],\"stream\":true,\"stream_options\":{\"include_usage\":true}}"

Límites de usoCopiar enlace de la sección

Las solicitudes tienen límites por usuario, organización y modelo: número de solicitudes simultáneas, solicitudes por minuto (RPM) y tokens por minuto (TPM). Los valores reales varían según el entorno.

Los tokens por minuto se descuentan al recibir la solicitud. La entrada se cuenta como 1 token por cada 4 caracteres en inglés, y el resto de caracteres como 1 token por carácter; cada imagen cuenta como 2.000 tokens. La salida se descuenta según max_tokens (máximo 4.096), así que si limita la salida a lo necesario, tendrá más margen dentro del límite.

Gestión de clavesCopiar enlace de la sección

En la pestaña API keys de Configuración → API puede consultar el estado de las claves emitidas (válida, caducada o revocada), volver a emitirlas o revocarlas.

Las claves son cadenas de 51 caracteres que empiezan por krl_llm_. Cada cuenta de emisión solo puede tener una clave; si ya existe una, se vuelve a emitir. La fecha de caducidad solo puede fijarse a partir de hoy.

Consulta de usoCopiar enlace de la sección

Puede consultar las solicitudes de API y el consumo de tokens en los dos lugares siguientes.

Condiciones de consultaCopiar enlace de la sección

Defina las condiciones y pulse Consultar. Para incluir una solicitud que acaba de enviar, pulse Actualizar.

Valores que aparecen en pantallaCopiar enlace de la sección

• Período de consulta aplicado: el período que se consultó realmente. Si dejó vacías la hora de inicio o de fin, o superó los 90 días, aparece el período que ajustó el servidor.
• Número de solicitudes y totales de tokens de entrada · tokens de salida · tokens totales: solo suman los valores confirmados. Los tokens que aún no se han confirmado aparecen como Sin confirmar.
• Lista de solicitudes: cada solicitud ocupa una fila con la hora, el Model ID, el estado y los tokens de entrada, salida y totales. Se muestran 20 por página; use Anterior y Siguiente para navegar.

Al pulsar Detalles de la solicitud de una fila, se despliegan los siguientes valores.

Las solicitudes en streaming registran el uso aunque no incluya stream_options.include_usage. Si una solicitud se interrumpe a mitad, puede quedar como Parcialmente confirmado o Sin confirmar.

Formato de errorCopiar enlace de la sección

Los errores se devuelven en formato compatible con OpenAI.

{
  "error": {
    "message": "Descripción del error legible para las personas",
    "type": "authentication_error",
    "code": "invalid_api_key",
    "param": null
  }
}

type depende del código de estado, y code indica la causa concreta.

Solución de problemasCopiar enlace de la sección

Si el problema persiste, contacte con su administrador e incluya la siguiente información. No envíe el texto de la clave ni el contenido de los prompts.

• Hora de la incidencia
• ID del modelo usado
• Nombre y versión de la aplicación cliente
• Valor de x-request-id del encabezado de respuesta
• Mensaje de error que aparece en pantalla