Análise de Sentimento¶

Este guia descreve como autenticar e consumir a API de análise de sentimento da AI Hub. Aqui você encontra os requisitos de integração, exemplos de requisição e resposta, principais erros e orientações de uso.

1. Visão Geral¶

• Base URL (produção): https://api.aihub.knew.in
• Endpoint: POST /v1/analysis/sentiment
• Formato: JSON
• Autenticação: Bearer token (OAuth2 Client Credentials)
• Documentação de autenticação: Autenticação (OAuth2 Client Credentials)

2. Chamada da API de Sentimento¶

URL da API¶

https://api.aihub.knew.in/v1/analysis/sentiment

Endpoint¶

POST https://api.aihub.knew.in/v1/analysis/sentiment

Headers obrigatórios¶

• Authorization: Bearer <ACCESS_TOKEN>
• Content-Type: application/json
• X-Tenant-External-Id: <tenant-external-id>

Observações:

• O tenant é resolvido pelo header X-Tenant-External-Id.

O que é X-Tenant-External-Id¶

X-Tenant-External-Id é o identificador único do cliente (tenant) na API.

Esse identificador define o contexto da requisição para:

• seleção de chave de provedor por escopo (quando aplicável);
• aplicação de rate limit/quota;
• rastreabilidade de uso por cliente.

Como fornecer esse valor¶

• A API consumidora define e envia esse identificador no header X-Tenant-External-Id.
• Para representar o mesmo tenant da integração, a API consumidora deve enviar sempre o mesmo valor.
• Quando o tenant ainda não existe, ele pode ser auto provisionado pela API (conforme configuração do ambiente).

Formato obrigatório¶

• somente letras minúsculas (a-z), números (0-9) e underscore (_);
• sem espaços;
• iniciar por letra (não pode iniciar por número);
• mínimo de 3 caracteres;
• tamanho até 191 caracteres.

Exemplos válidos (padrão recomendado):

• equatorial_alagoas
• ccr_motiva
• brasken

Body da requisição¶

Campos:

• text (string, obrigatório): texto a classificar.
• contextPrompt (string, opcional): contexto adicional para melhorar a classificação.
• provider (string, opcional): atualmente OPENAI (normalmente pode ser omitido).

Exemplo:

{
  "contextPrompt": "Classificar feedback de atendimento ao cliente",
  "text": "A equipe resolveu meu problema rapidamente e com educação."
}

Exemplo cURL¶

curl --location 'https://api.aihub.knew.in/v1/analysis/sentiment' \
  --header 'Authorization: Bearer <ACCESS_TOKEN>' \
  --header 'X-Tenant-External-Id: <tenant-external-id>' \
  --header 'Content-Type: application/json' \
  --data '{
    "contextPrompt": "Classificar feedback de atendimento ao cliente",
    "text": "A equipe resolveu meu problema rapidamente e com educação."
  }'

3. Resposta de Sucesso¶

{
  "sentiment": "positive",
  "metadata": {
    "requestId": "42f97e9e-93ea-4fc7-9af1-7b6489cd8204",
    "provider": "OPENAI",
    "modelName": "gpt-5-mini",
    "promptTokens": 24,
    "completionTokens": 1,
    "totalTokens": 25,
    "cachedInputTokens": 0,
    "cacheWriteInputTokens": 0,
    "reasoningTokens": 0,
    "finishReason": "STOP",
    "latencyMs": 216,
    "costMicros": 5300,
    "pricingRuleId": 7,
    "pricingApplied": true
  }
}

Valores possíveis para sentiment:

• positive
• negative
• neutral

4. Cache de checksum¶

A API usa cache de checksum para requisições idênticas (mesmo conteúdo lógico).

Quando há cache hit:

• metadata.finishReason = "CACHE_HIT"
• tokens e custo retornam 0
• não há nova chamada ao provedor

5. Erros e códigos HTTP¶

Formato padrão de erro:

{
  "timestamp": "2026-02-20T02:38:06.532968602Z",
  "status": 400,
  "code": "BAD_REQUEST",
  "message": "<detalhe>",
  "path": "/v1/analysis/sentiment"
}

Códigos comuns:

• 400 BAD_REQUEST
• payload inválido, provider não suportado, text vazio
• 401 UNAUTHORIZED
• token ausente/inválido
• header X-Tenant-External-Id ausente
• header X-Tenant-External-Id em formato inválido
• 403 FORBIDDEN
• sem role, caller app/tenant inválido ou inativo
• 429 RATE_LIMIT_EXCEEDED
• limite por minuto atingido
• 429 QUOTA_EXCEEDED
• quota mensal de tokens/custo atingida
• 429 PROVIDER_RATE_LIMIT_EXCEEDED
• limite no provedor LLM
• 502 PROVIDER_AUTHENTICATION_FAILED
• credencial de provedor inválida
• 502 PROVIDER_ERROR
• erro genérico do provedor
• 504 PROVIDER_TIMEOUT
• timeout no provedor

6. Rate limit e quota¶

A API pode aplicar limites por:

• requisições por minuto
• tokens por minuto
• tokens por mês
• custo por mês (em micros de USD)

Conversão de custo:

• 1 USD = 1.000.000 micros
• exemplo: 500000000 micros = USD 500,00

Por que usar micros em vez de USD decimal:

• evita erros de arredondamento de ponto flutuante em cálculos de custo;
• permite contabilização precisa e consistente em integrações e relatórios.

7. Boas práticas para clientes¶

• Renove token antes de expirar (o expires_in normalmente é curto).
• Em 429 e 504, implemente retry com backoff exponencial.
• Trate 502 como erro transitório de integração (observando limite de tentativas).
• Registre metadata.requestId para suporte/auditoria.