Documentação da API

Autenticação

Toda chamada leva a sua credencial no cabecalho:

Authorization: Bearer <api_id>.<segredo>

O api_id comeca com ab_. O segredo aparece uma unica vez, no momento em que a credencial e' criada — nem o operador consegue recupera-lo depois, porque o que fica guardado e' um hash scrypt. Perdeu, gere outra credencial.

Clientes da versao anterior podem continuar usando os cabecalhos X-Customer-Api-Id e X-Secret; as duas formas valem.

Chamadas longas

Chamadas de GPU podem levar de segundos a minutos. Duas formas de esperar:

• Sincrona (padrao): a resposta so volta quando o trabalho termina. Simples,

e o que quase todo mundo quer. Use timeout de cliente de pelo menos 180 s — timeout curto faz voce desistir de um trabalho que a placa ja comecou.

• Assincrona: envie com "async": true, receba um job_id na hora e acompanhe

por GET /v1/jobs/{job_id} ou pelo fluxo de eventos em GET /v1/jobs/{job_id}/stream. E' o caminho certo para lote e para transcricao de audio longo.

Reenvio seguro

Um pedido de GPU pode levar minutos. Se o seu cliente estourar o proprio timeout e reenviar, sem cuidado voce paga duas vezes e ocupa a placa duas vezes.

Mande um cabecalho Idempotency-Key com um valor unico por pedido — um UUID serve:

Idempotency-Key: 4f9c2a1e-7b3d-4c8a-9e21-0a5f6d8b3c74

O que acontece no reenvio com a mesma chave:

• se o primeiro pedido ainda esta rodando, voce recebe 409 com o job_id

para acompanhar, em vez de disparar um segundo trabalho;

• se ele ja terminou, voce recebe a mesma resposta, com o cabecalho

Idempotency-Replayed: true. Nao consome cota e nao toca a placa.

A chave vale por 24 horas e considera o corpo do pedido: reusar a mesma chave com um conteudo diferente executa normalmente, em vez de devolver a resposta antiga — esse e' o erro mais comum de quem usa idempotencia pela primeira vez.

Resposta muito grande (imagem em base64, por exemplo) nao e' guardada para repeticao; nesse caso o reenvio devolve o job_id para voce buscar o resultado.

Erros e limites

Erros vem sempre no mesmo formato, com um codigo estavel para o seu codigo tratar e uma mensagem para pessoas lerem:

{"erro": {"codigo": "cota_mensal_esgotada", "mensagem": "..."}}

HTTP	codigo	o que fazer
401	credencial_invalida	conferir api_id e segredo
403	rota_nao_permitida	a rota nao esta no seu plano; fale conosco
403	credencial_inativa	credencial desativada no painel
429	limite_por_minuto	esperar o Retry-After e tentar de novo
429	limite_simultaneas	reduzir chamadas em paralelo
429	cota_mensal_esgotada	subir de plano ou esperar o proximo mes
404	nao_encontrado	o job ou arquivo nao e' seu, ou nao existe
409	em_andamento	mesmo Idempotency-Key ainda em execucao
502	upstream_indisponivel	falha nossa; tente de novo com espera

Todo 429 traz Retry-After em segundos. Respeite-o: tentar em laco transforma o seu proprio limite numa tempestade que atrasa as suas outras chamadas.

Texto e conversa

Geracao de texto com modelo instruido, servida por Tesla T4 dedicadas. Compativel com o formato da OpenAI: se o seu codigo ja fala com a OpenAI, troque a URL base e a chave e pronto.

POST /api/v1/ai/v1/chat/completions escopo llm
Conversa no formato OpenAI
O caminho padrao para quase tudo: perguntas, resumo, extracao, classificacao, reescrita.
parâmetro	tipo	padrão	descrição
model	string	padrao do servidor	Nome do modelo. Apelido desconhecido cai no modelo padrao do servidor em vez de dar erro.
messages	array	obrigatório	Lista de mensagens com `role` (system/user/assistant) e `content`.
max_tokens	inteiro	1024	Teto de tokens gerados. Menor e' mais rapido e mais barato.
temperature	numero	0.7	0 e' deterministico; 0.7 e' criativo.
stream	booleano	false	Devolve os tokens conforme saem, em SSE.
Exemplo
curl https://abintel.digital/api/v1/ai/v1/chat/completions \
  -H "Authorization: Bearer ab_1a2b3c4d5e6f7890.SEU_SEGREDO" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [
      {"role": "system", "content": "Voce responde em portugues, de forma direta."},
      {"role": "user", "content": "Resuma o que e' um laudo pericial em duas frases."}
    ],
    "max_tokens": 300,
    "temperature": 0.3
  }'
Resposta
{
  "id": "chatcmpl-8f2a...",
  "object": "chat.completion",
  "created": 1788694014,
  "model": "Qwen/Qwen2.5-7B-Instruct",
  "choices": [{
    "index": 0,
    "message": {"role": "assistant", "content": "Um laudo pericial e' um documento..."},
    "finish_reason": "stop"
  }],
  "usage": {"prompt_tokens": 48, "completion_tokens": 62, "total_tokens": 110}
}
`max_tokens` e' o que mais mexe no seu tempo de resposta e na sua cota: dobrar o teto costuma dobrar o tempo.
Com `stream: true` os tokens chegam em `text/event-stream`.
POST /api/v1/ai/v1/completions escopo llm

Completacao simples (formato legado)

Compatibilidade com codigo antigo que usa `prompt` em vez de `messages`.

parâmetro	tipo	padrão	descrição
prompt	string	obrigatório	O texto a completar.
max_tokens	inteiro	1024	Teto de tokens gerados.

POST /api/v1/ai/v1/llm/generate pode ser assíncronaescopo llm

Geracao nativa, com controle de job

Quando voce quer o `job_id` para acompanhar progresso ou cancelar.

parâmetro	tipo	padrão	descrição
prompt	string	obrigatório	O texto de entrada.
async	booleano	false	Retorna na hora com o job_id.
priority	inteiro	do plano	0 e' a maior. Seu plano define o padrao.

POST /api/v1/ai/api/generate escopo llm
Geracao no formato Ollama
Para quem ja tem cliente Ollama: nao muda uma linha de codigo.
parâmetro	tipo	padrão	descrição
model	string	obrigatório	Nome no estilo Ollama, ex.: `llama3.2`.
prompt	string	obrigatório	O texto de entrada.
Nomes de modelo do Ollama sao traduzidos para o modelo equivalente daqui; nao ha download de modelo pelo cliente.
POST /api/v1/ai/api/chat escopo llm

Conversa no formato Ollama

Mesmo caso acima, para o endpoint de chat do Ollama.

parâmetro	tipo	padrão	descrição
model	string	obrigatório	Nome no estilo Ollama.
messages	array	obrigatório	Mensagens da conversa.

Embeddings e busca semantica

Vetores para busca por significado, deduplicacao e RAG, mais reordenacao de resultados. Servidos por uma placa separada da de texto — nao disputam fila com a geracao.

POST /api/v1/ai/v1/embeddings escopo embeddings
Vetores no formato OpenAI
Indexar documentos e transformar a pergunta do usuario em vetor.
parâmetro	tipo	padrão	descrição
input	string ou array	obrigatório	Um texto ou uma lista deles. Lista e' muito mais eficiente.
model	string	BAAI/bge-m3	Apelido desconhecido cai no padrao.
Exemplo
curl https://abintel.digital/api/v1/ai/v1/embeddings \
  -H "Authorization: Bearer ab_1a2b3c4d5e6f7890.SEU_SEGREDO" \
  -H "Content-Type: application/json" \
  -d '{"input": ["primeiro documento", "segundo documento"]}'
Resposta
{
  "object": "list",
  "model": "BAAI/bge-m3",
  "data": [
    {"object": "embedding", "index": 0, "embedding": [-0.0224, -0.0373, ...]},
    {"object": "embedding", "index": 1, "embedding": [0.0238, -0.0105, ...]}
  ],
  "usage": {"prompt_tokens": 12, "total_tokens": 12}
}
1.024 dimensoes. Mande em lote: cem textos numa chamada custam uma unidade de cota, cem chamadas custam cem.
POST /api/v1/ai/v1/rerank escopo embeddings

Reordenar por relevancia

Depois de recuperar 50 candidatos por vetor, escolher os 5 melhores. Melhora RAG mais que trocar de modelo de embedding.

parâmetro	tipo	padrão	descrição
query	string	obrigatório	A pergunta.
documents	array	obrigatório	Os candidatos a reordenar.
top_n	inteiro	todos	Quantos devolver.

Audio e transcricao

Transcricao com Whisper large-v3, com marcacao de tempo e deteccao de idioma.

POST /api/v1/ai/v1/audio/transcriptions pode ser assíncronaescopo asr
Transcrever (formato OpenAI)
Envio direto do arquivo, em multipart. O caminho mais simples.
parâmetro	tipo	padrão	descrição
file	arquivo	obrigatório	mp3, wav, m4a, ogg, flac, mp4.
language	string	auto	Codigo ISO. Vazio detecta sozinho.
response_format	string	verbose_json	`json`, `verbose_json`, `text`, `srt`, `vtt`.
Exemplo
curl https://abintel.digital/api/v1/ai/v1/audio/transcriptions \
  -H "Authorization: Bearer ab_1a2b3c4d5e6f7890.SEU_SEGREDO" \
  -F file=@reuniao.mp3 \
  -F response_format=srt
Audio longo e' o caso classico para `async`: uma hora de gravacao nao cabe num timeout de cliente confortavel.
`srt` e `vtt` saem prontos para legenda.
POST /api/v1/ai/v1/asr/transcribe pode ser assíncronaescopo asr

Transcrever por file_id ou URL

Quando o audio ja esta no nosso armazenamento ou acessivel por URL.

parâmetro	tipo	padrão	descrição
file_id	string	opcional	Devolvido por `POST /v1/files`.
url	string	opcional	Alternativa ao file_id.

Geracao de imagem

SDXL-Turbo numa Tesla T4 dedicada a midia. Catalogo 1024x1024 em ~4 s.

POST /api/v1/ai/v1/images/generations escopo images
Gerar imagem a partir de texto
Foto de produto, banner, ilustracao.
parâmetro	tipo	padrão	descrição
prompt	string	obrigatório	A descricao do que gerar.
n	inteiro	1	Quantas imagens.
size	string	1024x1024	Ex.: `1024x1024`, `1216x640`.
response_format	string	url	`b64_json` devolve os bytes; `url` devolve um link.
seed	inteiro	opcional	Fixe para reproduzir a mesma imagem.
Exemplo
curl https://abintel.digital/api/v1/ai/v1/images/generations \
  -H "Authorization: Bearer ab_1a2b3c4d5e6f7890.SEU_SEGREDO" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "frasco de vitamina C em fundo branco, foto de catalogo",
    "n": 1, "size": "1024x1024", "response_format": "b64_json"
  }'
Resposta
{
  "created": 1788694014,
  "model": "stabilityai/sdxl-turbo",
  "seed": 1833471805,
  "job_id": "job_5b44d28084834da8",
  "data": [{"width": 1024, "height": 1024, "b64_json": "iVBORw0KGgoAAAANS..."}]
}
`b64_json` e' o caminho rapido: os bytes voltam na resposta e nada precisa ser buscado depois.
Medido: 1024x1024 em ~5,5 s ponta a ponta, ~1,6 MB de PNG.

Visao computacional

Descrever imagem, responder perguntas sobre ela e extrair texto.

POST /api/v1/ai/v1/vision/analyze escopo vision

Analisar uma imagem

Descricao, pergunta sobre a imagem, leitura de contexto visual.

parâmetro	tipo	padrão	descrição
file_id	string	opcional	Imagem ja enviada.
url	string	opcional	Alternativa ao file_id.
prompt	string	descreva a imagem	O que voce quer saber.

POST /api/v1/ai/v1/vision/ocr escopo vision

Extrair todo o texto de uma imagem

Documento fotografado, print de tela, placa, formulario.

parâmetro	tipo	padrão	descrição
file_id	string	opcional	Imagem ja enviada.
url	string	opcional	Alternativa ao file_id.

Arquivos

Envie uma vez, use em varias chamadas. Arquivos expiram sozinhos.

POST /api/v1/ai/v1/files escopo files

Enviar arquivo

Audio para transcrever, imagem para analisar.

parâmetro	tipo	padrão	descrição
file	arquivo	obrigatório	O conteudo, em multipart.

Exemplo

curl https://abintel.digital/api/v1/ai/v1/files \
  -H "Authorization: Bearer ab_1a2b3c4d5e6f7890.SEU_SEGREDO" \
  -F file=@entrevista.wav

Resposta

{"id": "file_9c1e...", "bytes": 20971520, "mime": "audio/wav"}

GET /api/v1/ai/v1/files/{file_id} escopo files

Baixar arquivo

Buscar um resultado que ficou guardado.

GET /api/v1/ai/v1/files/{file_id}/meta escopo files

Dados do arquivo

Tamanho, tipo e validade, sem baixar o conteudo.

DELETE /api/v1/ai/v1/files/{file_id} escopo files

Apagar agora

Nao esperar a expiracao — util para dado sensivel.

Acompanhamento de trabalho

Para chamadas assincronas: acompanhar, aguardar e cancelar.

GET /api/v1/ai/v1/jobs/{job_id} escopo jobs

Consultar um trabalho

Saber se terminou e pegar o resultado.

GET /api/v1/ai/v1/jobs/{job_id}/wait escopo jobs

Aguardar ate terminar

Long-poll: uma chamada so, sem laco de consulta do seu lado.

GET /api/v1/ai/v1/jobs/{job_id}/stream escopo jobs

Acompanhar em tempo real

Eventos SSE com progresso e, na geracao de texto, os tokens.

GET /api/v1/ai/v1/jobs escopo jobs
Listar seus trabalhos recentes
Auditoria e depuracao do seu lado.
A lista traz apenas os seus trabalhos.
DELETE /api/v1/ai/v1/jobs/{job_id} escopo jobs

Cancelar

Trabalho na fila sai na hora; em execucao para no proximo ponto seguro.

Modelos e estado

O que o servidor sabe fazer e como ele esta agora.

GET /api/v1/ai/v1/models

Modelos disponiveis

Descobrir o que da' para pedir, sem adivinhar nomes.

GET /api/v1/ai/v1/system/health

O servico esta de pe?

Sonda de monitoramento. Nao consome cota.