Referência de API

A API externa SecureAI fornece recursos de conclusão de chat de IA com recuperação de base de conhecimento, políticas de segurança e rastreamento de uso abrangente. Esta API foi projetada para desenvolvedores externos e integrações usando autenticação de chave de API.

Principais recursos

RAG (Geração Aumentada de Recuperação): Pesquise automaticamente bases de conhecimento para contexto relevante
Suporte a vários modelos: OpenAI, Anthropic, Google, Meta e outros modelos de IA
Redundância e failover de modelo: cadeias de failover definidas pelo chamador (primário + substitutos) com tempos limite por tentativa
Endpoint compatível com OpenAI: aponte qualquer SDK OpenAI para /api/external/v1 — sem alterações de código
Geração de imagens: gere e edite imagens usando o Google Gemini 2.5 Flash Image
Speech-to-Speech (S2S): conversas de voz em tempo real usando OpenAI Realtime API com WebRTC
Políticas de segurança: aplicação de políticas SMLTP, Prompt Shield por chamada e recibos de conformidade assinados
Webhooks: entrega assinada e em tempo real de eventos de segurança e de plataforma
Acompanhamento de uso: monitoramento abrangente de uso, cota de autoatendimento e limitação de taxa
Integração da base de conhecimento: acesso a bases de conhecimento pessoais e compartilhadas
Gerenciamento de usuários: recursos completos de gerenciamento de usuários, grupos e funções
Registro de auditoria: registros abrangentes de atividades e auditoria de segurança

Autenticação

Todos os endpoints (exceto verificação de integridade) exigem autenticação de chave de API usando token de portador:

Authorization: Bearer sk-your-api-key-here

##URL base

https://{customer.name}.hiperai.ai/api/external

Para a superfície compatível com OpenAI, aponte o URL base do seu SDK para:

https://{customer.name}.hiperai.ai/api/external/v1

Faturamento e uso

Por padrão, as solicitações de API são cobradas da conta do usuário que possui a chave de API. Você pode especificar um usuário diferente para faturar incluindo o parâmetro user_id em sua solicitação. Isso permite:

Aplicativos multilocatários com faturamento por usuário
Gerenciamento flexível de limites de conclusão
Configurações de “Uso por modelo” por usuário

Limites de taxa

Padrão: 60 solicitações por minuto, 1.000 solicitações por hora
Limites diários: 100 solicitações (configuráveis)
Limites mensais: 10.000 solicitações (configuráveis)

Início rápido

1. Exame de saúde

curl -X GET "https://{customer.name}.hiperai.ai/api/external/health"

2. Obtenha modelos disponíveis

curl -X GET "https://{customer.name}.hiperai.ai/api/external/models" \
  -H "Authorization: Bearer sk-your-api-key-here"

3. Obtenha bases de conhecimento disponíveis

curl -X GET "https://{customer.name}.hiperai.ai/api/external/indexes" \
  -H "Authorization: Bearer sk-your-api-key-here"

4. Crie uma conclusão de bate-papo

curl -X POST "https://{customer.name}.hiperai.ai/api/external/chat/completions" \
  -H "Authorization: Bearer sk-your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-5-nano",
    "index": "my-knowledge-base",
    "smltp_policy": "internal",
    "prompt": "What is the company policy on remote work?",
    "temperature": 0.7,
    "max_tokens": 1000,
    "stream": false
  }'

Terminais de API

Sistema

Verificação de integridade - Verifique o status da API

Descoberta

Obter modelos disponíveis - Listar modelos de IA disponíveis
Obter bases de conhecimento disponíveis - Listar bases de conhecimento acessíveis
Obter políticas de segurança - Listar políticas SMLTP disponíveis

Bate-papo

Conclusão do bate-papo - Endpoint principal do bate-papo da IA com RAG
Ponto final compatível com OpenAI - Drop-in /v1/chat/completions para SDKs OpenAI
Redundância e Failover - Modelar cadeias de failover
Policy Check - Execute o pipeline de segurança sem chamar um modelo
Uso - Cota de autoatendimento, orçamento e limites de taxa
Recibos - Buscar recibos de conformidade assinados SMLTP

Webhooks

Visão geral dos Webhooks - Entrega de eventos assinados em tempo real
Eventos Webhook - Catálogo de eventos e cargas úteis

Imagens

Gerar Imagens - Gerar imagens a partir de texto ou editar imagens existentes
Editar imagens - Edição imagem a imagem com instruções de texto

Fala/S2S

Iniciar sessão S2S WebRTC - Estabelecer conversas de voz em tempo real
Obter status de tempo S2S - Verifique a cota de tempo S2S restante
Registrar duração da sessão S2S - Registrar duração da sessão e deduzir o tempo

Gerenciamento de usuários

Obter todos os usuários - Recuperar usuários com paginação
Criar usuário - Criar nova conta de usuário
Atualizar usuário - Atualizar usuário existente
Obter disponibilidade de licença - Recuperar limites e uso do pool de licenças

Gerenciamento de índice

Obter todos os índices - Recuperar todas as bases de conhecimento
Criar Índice - Criar nova base de conhecimento
Atualizar índice - Atualizar índice existente
Treinar índice com documentos - Treinar índice enviando documentos
Índice de pesquisa de documentos - Pesquisa de documentos usando pesquisa semântica

Gerenciamento de Grupo

Obter todos os grupos - Recuperar todos os grupos
Criar Grupo - Criar novo grupo
Atualizar grupo - Atualizar grupo existente

SMLTP Segurança

Obter todas as políticas SMLTP - Listar todas as políticas de segurança
Obter política ativa - Obter política ativa atual
Criar política personalizada - Criar política personalizada SMLTP
Registros de auditoria - Recuperar registros de auditoria SMLTP

Gerenciamento de funções

Obter todas as funções - Recuperar todas as funções
Criar função - Criar nova função personalizada

Tratamento de erros

Formato de resposta de erro

{
  "success": false,
  "error": "Invalid API key",
  "message": "The provided API key is invalid or has been revoked",
  "request_id": "req-abc123"
}

Erro de limite de taxa

{
  "success": false,
  "error": "Rate limit exceeded",
  "message": "Please reduce your request rate",
  "reset_time": "2024-01-15T11:00:00.000Z"
}

Códigos de status HTTP comuns

Código	Descrição
`200`	Sucesso
`201`	Criado com sucesso
`400`	Solicitação incorreta - parâmetros inválidos
`401`	Não autorizado – chave de API inválida
`403`	Proibido - permissões insuficientes
`404`	Não encontrado
`409`	Conflito – o recurso já existe
`413`	Carga útil muito grande - tamanho do arquivo excedido
`429`	Limite de taxa excedido
`500`	Erro interno do servidor
`503`	Serviço indisponível - serviço não configurado

Exemplos de SDK

###JavaScript/Node.js

// Using fetch
const response = await fetch('https://{customer.name}.hiperai.ai/api/external/chat/completions', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer sk-your-api-key-here',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    model: 'openai/gpt-5-nano',
    index: 'my-knowledge-base',
    smltp_policy: 'internal',
    prompt: 'What is the company policy on remote work?',
    temperature: 0.7,
    max_tokens: 1000
  })
});

const data = await response.json();
console.log(data.choices[0].message.content);

###Píton

import requests

url = "https://{customer.name}.hiperai.ai/api/external/chat/completions"
headers = {
    "Authorization": "Bearer sk-your-api-key-here",
    "Content-Type": "application/json"
}
data = {
  "model": "openai/gpt-5-nano",
    "index": "my-knowledge-base",
    "smltp_policy": "internal",
    "prompt": "What is the company policy on remote work?",
    "temperature": 0.7,
    "max_tokens": 1000
}

response = requests.post(url, headers=headers, json=data)
result = response.json()
print(result['choices'][0]['message']['content'])

###cURL

curl -X POST "https://{customer.name}.hiperai.ai/api/external/chat/completions" \
  -H "Authorization: Bearer sk-your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-5-nano",
    "index": "my-knowledge-base",
    "smltp_policy": "internal",
    "prompt": "What is the company policy on remote work?",
    "temperature": 0.7,
    "max_tokens": 1000

2. Obtenha modelos disponíveis

curl -X GET "https://{customer.name}.hiperai.ai/api/external/models" \
  -H "Authorization: Bearer sk-your-api-key-here"

3. Obtenha bases de conhecimento disponíveis

curl -X GET "https://{customer.name}.hiperai.ai/api/external/indexes" \
  -H "Authorization: Bearer sk-your-api-key-here"

4. Crie uma conclusão de bate-papo

curl -X POST "https://{customer.name}.hiperai.ai/api/external/chat/completions" \
  -H "Authorization: Bearer sk-your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-5-nano",
    "index": "my-knowledge-base",
    "smltp_policy": "internal",
    "prompt": "What is the company policy on remote work?",
    "temperature": 0.7,
    "max_tokens": 1000,
    "stream": false
  }'

Terminais de API

Sistema

Verificação de integridade - Verifique o status da API

Descoberta

Obter modelos disponíveis - Listar modelos de IA disponíveis
Obter bases de conhecimento disponíveis - Listar bases de conhecimento acessíveis
Obter políticas de segurança - Listar políticas SMLTP disponíveis

Bate-papo

Conclusão do bate-papo - Endpoint principal do bate-papo da IA com RAG
Endpoint compatível com OpenAI - Drop-in /v1/chat/completions para SDKs OpenAI
Redundância e Failover - Modelar cadeias de failover
Policy Check - Execute o pipeline de segurança sem chamar um modelo
Uso - Cota de autoatendimento, orçamento e limites de taxa
Receipts - Buscar recibos de conformidade assinados SMLTP

Webhooks

Visão geral dos Webhooks - Entrega de eventos assinados em tempo real
Eventos Webhook - Catálogo de eventos e cargas úteis

Imagens

Gerar Imagens - Gerar imagens a partir de texto ou editar imagens existentes
Editar imagens - Edição imagem a imagem com instruções de texto

Fala/S2S

Iniciar sessão S2S WebRTC - Estabelecer conversas de voz em tempo real
Obter status de tempo S2S - Verifique a cota de tempo S2S restante
Registrar duração da sessão S2S - Registrar duração da sessão e deduzir o tempo

Gerenciamento de usuários

Obter todos os usuários - Recuperar usuários com paginação
Criar usuário - Criar nova conta de usuário
Atualizar usuário - Atualizar usuário existente
Obter disponibilidade de licença - Recuperar limites e uso do pool de licenças

Gerenciamento de índice

Obter todos os índices - Recuperar todas as bases de conhecimento
Criar Índice - Criar nova base de conhecimento
Atualizar índice - Atualizar índice existente
Treinar índice com documentos - Treinar índice enviando documentos
Índice de pesquisa de documentos - Pesquisa de documentos usando pesquisa semântica

Gerenciamento de Grupo

Obter todos os grupos - Recuperar todos os grupos
Criar Grupo - Criar novo grupo
Atualizar grupo - Atualizar grupo existente

SMLTP Segurança

Obter todas as políticas SMLTP - Listar todas as políticas de segurança
Obter política ativa - Obter política ativa atual
Criar política personalizada - Criar política personalizada SMLTP
Registros de auditoria - Recuperar registros de auditoria SMLTP

Gerenciamento de funções

Obter todas as funções - Recuperar todas as funções
Criar função - Criar nova função personalizada

Tratamento de erros

Formato de resposta de erro

{
  "success": false,
  "error": "Invalid API key",
  "message": "The provided API key is invalid or has been revoked",
  "request_id": "req-abc123"
}

Erro de limite de taxa

{
  "success": false,
  "error": "Rate limit exceeded",
  "message": "Please reduce your request rate",
  "reset_time": "2024-01-15T11:00:00.000Z"
}

Códigos de status HTTP comuns

Código	Descrição
`200`	Sucesso
`201`	Criado com sucesso
`400`	Solicitação incorreta - parâmetros inválidos
`401`	Não autorizado – chave de API inválida
`403`	Proibido - permissões insuficientes
`404`	Não encontrado
`409`	Conflito – o recurso já existe
`413`	Carga útil muito grande - tamanho do arquivo excedido
`429`	Limite de taxa excedido
`500`	Erro interno do servidor
`503`	Serviço indisponível - serviço não configurado

Exemplos de SDK

###JavaScript/Node.js

// Using fetch
const response = await fetch('https://{customer.name}.hiperai.ai/api/external/chat/completions', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer sk-your-api-key-here',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    model: 'openai/gpt-5-nano',
    index: 'my-knowledge-base',
    smltp_policy: 'internal',
    prompt: 'What is the company policy on remote work?',
    temperature: 0.7,
    max_tokens: 1000
  })
});

const data = await response.json();
console.log(data.choices[0].message.content);

###Píton

import requests

url = "https://{customer.name}.hiperai.ai/api/external/chat/completions"
headers = {
    "Authorization": "Bearer sk-your-api-key-here",
    "Content-Type": "application/json"
}
data = {
  "model": "openai/gpt-5-nano",
    "index": "my-knowledge-base",
    "smltp_policy": "internal",
    "prompt": "What is the company policy on remote work?",
    "temperature": 0.7,
    "max_tokens": 1000
}

response = requests.post(url, headers=headers, json=data)
result = response.json()
print(result['choices'][0]['message']['content'])

###cURL

curl -X POST "https://{customer.name}.hiperai.ai/api/external/chat/completions" \
  -H "Authorization: Bearer sk-your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-5-nano",
    "index": "my-knowledge-base",
    "smltp_policy": "internal",
    "prompt": "What is the company policy on remote work?",
    "temperature": 0.7,
    "max_tokens": 1000
  }'

Próximas etapas

Base de Conhecimento & RAG - Aprenda sobre Bases de Conhecimento e RAG

​Referência de API

​Principais recursos

​Autenticação

​Faturamento e uso

​Limites de taxa

​Início rápido

​1. Exame de saúde

​2. Obtenha modelos disponíveis

​3. Obtenha bases de conhecimento disponíveis

​4. Crie uma conclusão de bate-papo

​Terminais de API

​Sistema

​Descoberta

​Bate-papo

​Webhooks

​Imagens

​Fala/S2S

​Gerenciamento de usuários

​Gerenciamento de índice

​Gerenciamento de Grupo

​SMLTP Segurança

​Gerenciamento de funções

​Tratamento de erros

​Formato de resposta de erro

​Erro de limite de taxa

​Códigos de status HTTP comuns

​Exemplos de SDK

​2. Obtenha modelos disponíveis

​3. Obtenha bases de conhecimento disponíveis

​4. Crie uma conclusão de bate-papo

​Terminais de API

​Sistema

​Descoberta

​Bate-papo

​Webhooks

​Imagens

​Fala/S2S

​Gerenciamento de usuários

​Gerenciamento de índice

​Gerenciamento de Grupo

​SMLTP Segurança

​Gerenciamento de funções

​Tratamento de erros

​Formato de resposta de erro

​Erro de limite de taxa

​Códigos de status HTTP comuns

​Exemplos de SDK

​Próximas etapas

Referência de API

Principais recursos

Autenticação

Faturamento e uso

Limites de taxa

Início rápido

1. Exame de saúde

2. Obtenha modelos disponíveis

3. Obtenha bases de conhecimento disponíveis

4. Crie uma conclusão de bate-papo

Terminais de API

Sistema

Descoberta

Bate-papo

Webhooks

Imagens

Fala/S2S

Gerenciamento de usuários

Gerenciamento de índice

Gerenciamento de Grupo

SMLTP Segurança

Gerenciamento de funções

Tratamento de erros

Formato de resposta de erro

Erro de limite de taxa

Códigos de status HTTP comuns

Exemplos de SDK

2. Obtenha modelos disponíveis

3. Obtenha bases de conhecimento disponíveis

4. Crie uma conclusão de bate-papo

Terminais de API

Sistema

Descoberta

Bate-papo

Webhooks

Imagens

Fala/S2S

Gerenciamento de usuários

Gerenciamento de índice

Gerenciamento de Grupo

SMLTP Segurança

Gerenciamento de funções

Tratamento de erros

Formato de resposta de erro

Erro de limite de taxa

Códigos de status HTTP comuns

Exemplos de SDK

Próximas etapas