DUAS FORMAS DE USAR A MESMA IA

Leve a geração de texto ao seu sistema.

O chat usa seu login pessoal. Um sistema, site ou aplicativo pode chamar a API pelo próprio backend, com uma credencial de integração.

1. Obtenha um token

O backend deve enviar JSON para POST /api/v1/auth/login usando uma conta própria da aplicação:

Content-Type: application/json

{"username":"app-integracao","password":"SENHA_LIDA_DE_ARQUIVO_PROTEGIDO"}

Use o campo token retornado e respeite expiresIn. Guarde a senha somente no backend, fora do código e dos logs. Ao encerrar o consumidor, envie POST /api/v1/auth/logout com o mesmo Bearer para revogar a sessão.

2. Envie a pergunta

POST /api/v1/inference/text
Authorization: Bearer SEU_ACCESS_TOKEN
Content-Type: application/json

{
  "prompt": "Explique filas em duas frases.",
  "segment": "geral",
  "maxTokens": 80
}

A resposta contém text, model, outputTokens e selection. O limite síncrono padrão é 100 tokens; só o segmento geral está habilitado inicialmente.

3. Trate as respostas

1. 401: autentique novamente; 403: confira as permissões do cliente.
2. 429: respeite Retry-After; a IA atende uma geração por vez neste servidor.
3. 503: modelo ou serviço indisponível. Defina timeout de leitura de pelo menos 135 segundos.

Exemplo Node.js

Disponível na pasta examples/nodejs do projeto, sem dependências externas. Configure as variáveis de ambiente conforme docs/api-integracao.md:

import { GatewayClient } from './gateway-client.mjs';

const client = new GatewayClient({
  url: process.env.GATEWAY_URL,
  username: process.env.GATEWAY_USERNAME,
  credentialFile: process.env.GATEWAY_CREDENTIAL_FILE
});
const result = await client.generate('Explique filas em duas frases.');
console.log(result.text);
await client.logout();

Exemplo Spring Boot

Projeto executável em examples/springboot, com Java 21, RestClient, DTOs e testes HTTP simulados. Injete o GatewayClient no seu serviço:

var result = client.generate("Explique filas em duas frases.", "geral", 80);
System.out.println(result.text());

Jobs e compatibilidade

Para respostas extensas, envie targetLines de 1 a 10.000 em POST /api/v1/jobs/text, com maxTokens: 512 por etapa. O status informa completedLines. Acima de 500 linhas, obtenha o texto pelo download autenticado GET /api/v1/jobs/{id}/text. O prazo é de até 7 dias, sem garantia de conclusão ou qualidade; pode levar horas. Detalhes em docs/respostas-por-linhas.md.

Use POST /api/v1/jobs/text para texto assíncrono, com Idempotency-Key, consulte GET /api/v1/jobs/{id} e obtenha o resultado em GET /api/v1/jobs/{id}/result. Os exemplos incluem submissão, consulta, resultado e cancelamento, sem polling infinito nem repetição automática de inferências.

Integrações anteriores com client_credentials do Keycloak continuam compatíveis, inclusive o exemplo Python. Os clientes novos aceitam também esse modo. O chat e as contas próprias não exigem login pelo Keycloak.

Prompts e respostas não devem entrar nos logs do sistema consumidor. O histórico visual do chat não é automaticamente usado como contexto pelo modelo.

← Voltar ao chat