API do Keural

Chame os modelos cadastrados no Keural no formato OpenAI Chat Completions.

A URL base tem o formato https://<seu domínio público de API>/llm/v1. O domínio público da API varia de acordo com o ambiente; confirme com o seu administrador.

Embeddings, geração de imagens, voz e a API Responses não são suportados, e as requisições para esses caminhos retornam 404.

Fluxo de usoCopiar link da âncora

Pré-requisitosCopiar link da âncora

Emitir uma chave de APICopiar link da âncora

1. No menu da conta, abra Configurações → API. Nos apps de desktop e celular, o item fica na seção Ferramentas.
2. Na aba API keys, escolha o workspace ao qual a chave pertence (pessoal ou da organização) e o Model ID.
3. Se necessário, defina a New key expiration (optional, Korea time). Se deixar em branco, a chave não expira até ser revogada.
4. Clique em Issue key e use Copy key para copiar a chave e guardá-la. O texto completo da chave é exibido somente nesse momento.

• A chave fica vinculada ao workspace escolhido e a um modelo. O uso é atribuído a quem emitiu a chave.
• Cada combinação de workspace e modelo tem apenas uma chave. Para obter uma nova, reemita (Rotate) ou revogue (Revoke) a chave existente.
• Se perder a chave, reemita-a. Ao reemitir, a chave anterior deixa de funcionar imediatamente.
• Se não houver modelos disponíveis para emissão, verifique com o administrador a configuração de publicação dos modelos, o plano e a permissão de API da organização.

Permissão de API dos membros da organizaçãoCopiar link da âncora

Esta permissão é destinada a proprietários e administradores da organização. Para que um membro emita chaves em um workspace da organização, o administrador precisa liberá-la antes. Para todos os membros, o padrão é bloqueado.

Gerenciamento da organização → Organization API é composto pelas três seções a seguir. Se o menu não aparecer, a função de API está desativada ou a sua conta não tem permissão de administração da organização.

Quando um membro sai ou é removido da organização, as chaves que recebeu nela são revogadas automaticamente.

Conectar a um clienteCopiar link da âncora

Informe os três valores a seguir em aplicativos compatíveis com OpenAI API (clientes de chat, extensões de IDE, ferramentas de automação etc.).

1. Nas configurações do aplicativo, adicione uma conexão compatível com OpenAI (Connection).
2. Informe a Base URL e a API Key e salve.
3. Escolha um modelo na lista. A lista mostra somente o modelo conectado à chave.
4. Envie uma mensagem curta e confirme a resposta.

O formato das requisições é o seguinte.

Primeira requisiçãoCopiar link da âncora

export KEURAL_API_KEY='sua_chave_emitida'
export KEURAL_BASE_URL='https://<seu-domínio-de-api>/llm/v1'
export MODEL_ID='ID_do_modelo_na_tela_de_emissão'

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\":\"Olá.\"}]}"

O model do corpo da requisição deve ser o mesmo modelo conectado à chave. Se houver prefixo de caminho, como provider/ID_do_modelo, compara-se o trecho após a última /. Se for diferente, a API retorna 403. A resposta sempre traz no campo model o ID do modelo da chave.

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": "Olá."}],
)
print(res.choices[0].message.content)

Campos de requisição aceitosCopiar link da âncora

A API aceita somente os 18 campos de nível superior abaixo. Se você enviar outros campos, a resposta é 400. Campos opcionais com valor null são tratados como não enviados.

MensagensCopiar link da âncora

• Uma mensagem tool responde uma única vez a cada id dos tool_calls anteriores.
• Partes de imagem (image_url) só são incluídas em mensagens user de modelos que aceitam imagens. Use um endereço http ou https, ou um data URI base64 de PNG, JPEG, GIF ou WebP. O detail pode ser auto, low ou high.

CorpoCopiar link da âncora

Se você descumprir as regras do corpo, a resposta é 400 e param é body.

StreamingCopiar link da âncora

Com "stream": true na requisição, a resposta é enviada por SSE. Os fragmentos são enviados como eventos data: ..., e no final é enviado data: [DONE]. Com "stream_options": {"include_usage": true}, um fragmento com o uso de tokens é enviado adicionalmente logo antes de [DONE].

Com include_usage, todos os fragmentos trazem usage: null, e o último fragmento de uso tem choices como array vazio. Respostas sem streaming só trazem usage quando os tokens de entrada e de saída foram confirmados.

O id da resposta tem o formato chatcmpl-<x-request-id>. Todas as respostas incluem o cabeçalho x-request-id.

Se houver erro durante o streaming, um evento data: com o JSON do erro é enviado e a conexão é encerrada sem [DONE]. Se um fragmento ultrapassar 1 MiB ou a resposta ultrapassar 16 MiB, a conexão termina com 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\":\"Olá.\"}],\"stream\":true,\"stream_options\":{\"include_usage\":true}}"

Limites de usoCopiar link da âncora

As requisições têm limites por usuário, organização e modelo: número de requisições simultâneas, requisições por minuto (RPM) e tokens por minuto (TPM). Os valores reais variam conforme o ambiente.

Os tokens por minuto são descontados antecipadamente ao receber a requisição. A entrada é calculada em 1 token a cada 4 caracteres em inglês, 1 token por caractere nos demais casos, e 2.000 tokens por imagem. A saída é descontada conforme max_tokens (máximo de 4.096), então definir o limite de saída apenas no necessário aumenta a folga dentro do limite.

Gerenciamento de chavesCopiar link da âncora

Em Configurações → API → API keys, consulte o estado das chaves (válida · expirada · revogada) e reemita ou revogue.

As chaves são strings de 51 caracteres que começam com krl_llm_. Em cada workspace de emissão, só há uma chave; se já houver uma, ela é reemitida. A data de expiração só pode ser definida a partir de hoje.

Consulta de usoCopiar link da âncora

As requisições da API e o uso de tokens podem ser consultados nos dois locais a seguir.

Condições da consultaCopiar link da âncora

Defina as condições e clique em Consultar. Para incluir requisições recentes, clique em Atualizar.

Valores exibidos na telaCopiar link da âncora

• Período de consulta aplicado: o período que foi realmente consultado. Se a hora de início ou de fim ficou em branco, ou se o período passou de 90 dias, é exibido o período ajustado.
• Número de requisições e os totais de tokens de entrada · tokens de saída · tokens totais: somam apenas valores confirmados. Tokens não confirmados são exibidos como Não confirmado.
• Lista de requisições: cada requisição exibe horário, Model ID, status e tokens de entrada, saída e totais. São exibidas 20 por página, navegáveis com Anterior e Próximo.

Ao clicar em Detalhes da requisição em uma linha, são exibidos os valores a seguir.

Requisições em streaming registram o uso mesmo sem stream_options.include_usage. Se uma requisição for interrompida no meio, ela pode ficar como Parcialmente confirmado ou Não confirmado.

Formato de erroCopiar link da âncora

Os erros são retornados no formato compatível com OpenAI.

{
  "error": {
    "message": "Descrição do erro legível para pessoas",
    "type": "authentication_error",
    "code": "invalid_api_key",
    "param": null
  }
}

O type é definido pelo código de status, e o code indica a causa.

Solução de problemasCopiar link da âncora

Se o problema não for resolvido, entre em contato com o administrador e informe os dados a seguir. Não envie o texto da chave nem o conteúdo dos prompts.

• Horário da ocorrência
• ID do modelo usado
• Nome e versão do aplicativo cliente
• Valor de x-request-id do cabeçalho de resposta
• Mensagem de erro exibida na tela