API Documentation

v1.0
Acessar App

Nivia.ai API

Integre correções automáticas de redação ENEM em sua aplicação. Correções em até 60 segundos com IA avançada e feedback detalhado.

99.9% Uptime
RESTful API

Início Rápido

1. Obtenha sua API Key

Entre em contato com a equipe do Redação Online para obter sua API key de acesso.

Base URL
https://api.nivia.ai/v1
2. Faça sua primeira requisição
cURL
curl -X POST https://api.nivia.ai/v1/essays \
  -H "apikey: sua-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "enem",
    "text": "Sua redação aqui...",
    "theme": "Preconceito linguístico no Brasil",
    "title": "Valorização da diversidade linguística"
  }'

Autenticação

A API Nivia.ai usa autenticação por API key. Inclua sua API key no header "apikey" de todas as requisições.

Header de Autenticação
apikey: nva_sk_live_1234567890abcdef

Rate Limits

Para garantir um serviço estável para todos os usuários, aplicamos limite de taxa de requisições:

Limite de Requisições

  • • 100 requisições por minuto
  • • 20 MB máximo por imagem (recomendado: até 4 MB)

Comportamento em caso de limite excedido

Quando o limite de 100 requisições por minuto for excedido, a API retornará status HTTP 429 (Too Many Requests). Aguarde 1 minuto antes de fazer novas requisições.

Tratamento de Erros

A API Nivia.ai usa códigos de status HTTP convencionais para indicar o sucesso ou falha de uma requisição.

400
Bad Request

Parâmetros inválidos ou ausentes

{
  "code": "common-0001",
  "message": "Validation error",
  "details": {
    "description": "Missing required field",
    "field": "theme_id",
    "required": true
  }
}
401
Unauthorized

API key inválida

{
  "code": "common-0002",
  "message": "Invalid api key"
}
403
Forbidden

Credenciais ausentes

{
  "code": "common-0007",
  "message": "Missing credentials"
}
429
Rate Limited

Limite de requisições excedido

{
  "code": "rate-limit-0000",
  "message": "Rate limit exceeded",
  "details": {
    "retryAfter": 3600
  }
}

Listar Essays

GET
/v1/essays

Lista todos os essays com filtros opcionais por status, paginação e outros critérios.

Parâmetros da Requisição

ParâmetroTipoObrigatórioDescrição
pagenumber
Não
Número da página (>= 1)
sizenumber
Não
Tamanho da página (>= 1)
statusenum
Não
failed | ocr_failed | ocr_running | ocr_success | pending | processing | success

Exemplo de Resposta

JSON Response
{
  "data": [
    {
      "createdAt": "2025-06-27T01:18:05.618Z",
      "id": "EXAMPLE12345",
      "status": "success",
      "updatedAt": "2025-06-27T01:31:00.622Z"
    }
  ],
  "totalItems": 1,
  "totalPages": 1
}

Criar Essay

POST
/v1/essays

Cria um novo essay para correção. Aceita texto direto, URL de imagem ou upload de arquivo.

Parâmetros da Requisição

ParâmetroTipoObrigatórioDescrição
typeenum
Sim
enem | fuvest | mirror | us
textstring
Sim
Texto da redação
themestring
Não
Tema da redação
titlestring
Não
Título da redação
genrestring
Não
Gênero textual
motivationalTextsstring[]
Não
Textos motivadores
mirrorIdstring
Não
ID do espelho (obrigatório somente quando type = 'mirror')
urlstring
Não
URL da imagem (alternativa ao campo text)
fileattachment
Não
Arquivo de imagem (form-data, alternativa aos campos text/url)

Exemplo de Requisição

JSON
{
  "type": "enem",
  "text": "A questão do preconceito linguístico no Brasil é um problema que afeta milhões de pessoas...",
  "theme": "Preconceito linguístico no Brasil",
  "title": "Valorização da diversidade linguística",
  "genre": "dissertativo-argumentativo",
  "motivationalTexts": [
    "Texto motivador sobre diversidade linguística..."
  ]
}

Exemplo de Resposta

JSON Response
{
  "id": "EXAMPLE12345",
  "type": "enem", 
  "status": "pending",
  "createdAt": "2024-01-15T10:30:00Z"
}

Obter Essay

GET
/v1/essays/{id}

Recupera os detalhes completos de um essay específico, incluindo correção e feedback.

Parâmetros de Path

id (string): ID único do essay

Exemplo de Resposta

JSON Response
{
    "accountId": "3X4MPL3",
    "text": "EM UMA FLORESTA, HAVIA VÁRIOS ANIMAIS, VIVIA UMA ONÇA E UM FORTE TIGRE.\nOS DOIS ERAM RIVAIS, POIS SEMPRE DISCUTIAM PARA REINAR NESSA FLORESTA. A POBRE ONÇA ERA CEGA E HAVIAM VÁRIOS ARRANHÕES EM SEU ROSTO CAUSADO POR OUTROS ANIMAIS.\nO TIGRE, DIFERENTE DA ONÇA ERA SAUDÁVEL E FORTE.\nCERTO DIA O FALSO TIGRE DECIDIU ACABAR DE VEZ COM A ONÇA, APRISIONANDO- A.\nEM UMA CAVERNA ESCURA DISTANTE DA FLORESTA. DESTA FORMA O TIGRE TEVE TODO SUCESSO DE REI DA FLORESTA.\n-FICARÁ NESSA CAVERNA PARA SEMPRE. AGORA, O TRONO SERÁ MEU! DISSE ORGULHOSO.\n-ME TIRE DAQUI, POR FAVOR! FALOU A ONÇA DESESPERADA.\nO TIGRE FOI EMBORA SEM DAR OUVIDOS.\nDEPOIS DE MUITO ESFORÇO, A ONÇA CONSEGUIU SAIR DA CAVERNA EM DISPARADA EM BUSCA DO TIGRE.\nCHEGANDO LÁ, ENCONTROU O MALDOSO ANIMAL E DISSE:\n-PARE COM ISSO, ANIMAL MISERÁVEL , SEMPRE FUI A RAINHA E NUNCA PRECISEI MALTRATAR MEU POVO. DISSE FURIOSA.\n-NUNCA! VENHA LUTAR SE TIVER CORAGEM!\nDITO E FEITO.\nCOMEÇARAM A TERRÍVEL BRIGA, O TIGRE DERRUBOU A ONÇA NO CHÃO OS ANIMAIS FICARAM DESESPERADOS POIS PERTO DELA HAVIA FOGO. QUANDO TUDO PARECIA PERDIDO, A ONÇA, COMO ESTRATÉGIA, CONSEGUIU DAR UM EMPURRÃO NO TIGRE, QUE O DERRUBOU DENTRO DO FOGARÉU.\nOS ANIMAIS FICARAM FELIZES E CONSTRANGIDOS, POIS ANTES DE SALVÁ-LOS NINGUÉM AMAVA A ONÇA, POR CAUSA DE SUA APARÊNCIA, NUNCA PENSARAM NA GRANDE CAPACIDADE E BONDADE DAQUELA FEIA ONÇA\nMORAL: NUNCA JULGUE NINGUÉM PELA APARÊNCIA.",
    "type": "mirror",
    "mirrorId": "3X4MPL3",
    "id": "EXAMPLE12345",
    "createdAt": "2025-06-27T01:18:05.618Z",
    "score": {
        "score": 8,
        "requirements": [
            {
                "justification": "A narrativa apresenta elementos básicos como personagens (a onça e o tigre), cenário (a floresta e a caverna), conflito (a rivalidade entre a onça e o tigre) e resolução (a onça consegue derrotar o tigre). No entanto, esses elementos são desenvolvidos de forma simples e direta, sem muita profundidade ou detalhamento.",
                "score": 3,
                "title": "Elementos narrativos e construção do enredo"
            },
            {
                "justification": "A sequência dos eventos é clara, com um início, meio e fim bem definidos. No entanto, a narrativa carece de criatividade e originalidade, apresentando uma história bastante comum e previsível. Os marcadores de tempo e espaço são utilizados de forma básica, sem enriquecer a narrativa.",
                "score": 3,
                "title": "Clareza, sequência lógica e criatividade"
            },
            {
                "justification": "O texto apresenta diversos erros de pontuação e alguns de concordância, como o uso inadequado de vírgulas e a falta de concordância verbal em algumas partes. Esses erros comprometem a fluência da leitura e a clareza do texto.",
                "score": 2,
                "title": "Correção linguística "
            }
        ],
        "justification": "A redação apresenta uma narrativa com elementos básicos, mas desenvolvidos de forma simples e direta. A sequência lógica é clara, mas a criatividade é limitada. A correção linguística precisa de melhorias, especialmente na pontuação e concordância, para atender melhor aos critérios esperados para a faixa etária.",
        "matches": [
            {
                "message": "Parece haver uma confusão de palavras. Considere aplicar a sugestão.",
                "shortMessage": "Possível erro gramatical",
                "replacements": [
                    {
                        "value": "festa"
                    }
                ],
                "offset": 7,
                "length": 8,
                "context": {
                    "text": "EM UMA FLORESTA, HAVIA VÁRIOS ANIMAIS, VIVIA UMA ONÇA E...",
                    "offset": 7,
                    "length": 8
                },
                "sentence": "EM UMA FLORESTA, HAVIA VÁRIOS ANIMAIS, VIVIA UMA ONÇA E UM FORTE TIGRE.",
                "type": {
                    "typeName": "Other"
                },
                "rule": {
                    "id": "AI_PT_GGEC_REPLACEMENT_CONFUSION",
                    "description": "This rule detects incorrect word usages due to confusion pairs.",
                    "issueType": "uncategorized",
                    "category": {
                        "id": "MISC",
                        "name": "Miscellaneous"
                    },
                    "isPremium": false
                },
                "ignoreForIncompleteSentence": false,
                "contextForSureMatch": 0
            }
        ]
    },
    "status": "success",
    "updatedAt": "2025-06-27T01:31:00.622Z"
}

Reprocessar Essay

POST
/v1/essays/{id}/retry

Reinicia o processamento de um essay que falhou ou precisa ser reprocessado.

Parâmetros de Path

id (string): ID único do essay

Exemplo de Resposta

JSON Response
{
  "id": "EXAMPLE12345",
  "type": "enem", 
  "status": "pending",
  "createdAt": "2024-01-15T10:30:00Z"
}

Reenviar Webhook Essay

POST
/v1/essays/{id}/webhook

Reenvia o webhook de um essay no estado atual para o endpoint configurado.

Parâmetros de Path

id (string): ID único do essay

Resposta

Status 204: Webhook reenviado com sucesso

Listar OCR

GET
/v1/ocr

Lista todos os processamentos OCR com filtros opcionais por status e paginação.

Parâmetros da Requisição

ParâmetroTipoObrigatórioDescrição
pagenumber
Não
Número da página (>= 1)
sizenumber
Não
Tamanho da página (>= 1)
statusenum
Não
failed | pending | processing | success

Exemplo de Resposta

JSON Response
{
  "data": [
    {
      "createdAt": "2025-06-27T01:18:05.618Z",
      "id": "EXAMPLE12345",
      "status": "success",
      "updatedAt": "2025-06-27T01:31:00.622Z"
    }
  ],
  "totalItems": 1,
  "totalPages": 1
}

Criar OCR

POST
/v1/ocr

Inicia um novo processamento OCR para extração de texto de imagem. Aceita URL ou upload de arquivo.

Parâmetros da Requisição

ParâmetroTipoObrigatórioDescrição
urlstring
Não
URL da imagem (obrigatório se não houver arquivo)
fileattachment
Não
Arquivo de imagem (form-data, obrigatório se não houver URL)
config.improveLinesboolean
Não
Melhorar detecção de linhas

Exemplo de Requisição

JSON
{
  "url": "https://example.com/image.jpg",
  "config": {
    "improveLines": true
  }
}

Exemplo de Resposta

JSON Response
{
  "createdAt": "2025-06-27T01:18:05.618Z",
  "id": "EXAMPLE12345",
  "status": "pending",
  "updatedAt": "2025-06-27T01:31:00.622Z"
}

Obter OCR

GET
/v1/ocr/{id}

Recupera os detalhes completos de um processamento OCR específico, incluindo o texto extraído.

Parâmetros de Path

id (string): ID único do processamento OCR

Exemplo de Resposta

JSON Response
{
  "accountId": "3X4MPL3",
  "confidence": 0.71,
  "createdAt": "2025-06-27T01:18:05.618Z",
  "id": "EXAMPLE12345",
  "language": "pt-BR",
  "lines": [
    {
      "text": "No Brasil, muito tem-se discutido acerca da importância da divulgação de trabalhos científicos.",
      "words": [
        {
          "boundingBox": [
            1377,
            113,
            1528,
            114,
            1528,
            146,
            1378,
            146
          ],
          "confidence": 0.991,
          "height": 33,
          "text": "No",
          "width": 151,
          "x": 1377,
          "y": 113
        }
      ]
    }
  ],
  "originalUrl": "https://example.com",
  "status": "success",
  "text": "No Brasil, muito tem-se discutido acerca da importância da divulgação de trabalhos científicos. Segundo dados divulgados pela CNN, no ano de 2023, houveram cerca de 159 milhões de pesquisas voltadas ao meio científico. Levando esse dado como ponto de partida, a divulgação de pesquisas se mostrou imprescindível para a divulgação de conhecimento verdadeiro. Porém, as fake news e dados não comprovados dificultam a disseminação do meio científico no país.\nCom o avanço da tecnologia, a publicação de artigos acadêmicos em meios físicos como revistas e jornais perdeu visibilidade, e por isso foi obrigada a se adaptar no meio digital. Com isso, a distribuição do conteúdo científico se intensificou por todo o mundo, sendo incorporado no dia a dia. Para o sociólogo espanhol Manuel Castells, a sociedade contemporânea se comporta de acordo com as informações distribuídas nas redes sociais, assim tornando o ambiente digital extremamente importante para a formação do indivíduo. Sob esse ponto de vista, a divulgação de trabalhos acadêmicos com auxílio tecnológico é importante para o desenvolvimento de aprendizado, uma vez que a tecnologia, atualmente, desempenha um papel protagonista no dia a dia da sociedade brasileira.\nContudo, a desinformação presente na maioria dos principais meios digitais têm se transformado no principal obstáculo para a disseminação de divulgação científica no Brasil. A principal causa dessa publicação de informações falsas é o objetivo de manipular as massas e o pensamento coletivo. Para o sociólogo Émile Durkheim, o controle dos meios de comunicação se encaixam no conceito de fato social, em que a sociedade exerce pressão sobre o indivíduo para que acredite nas mesmas crenças e com no senso comum. Sob essa ótica, torna-se urgente a intervenção estatal para ajudar no controle de disseminação de desinformação e elevar a taxa de divulgações comprovadas no país.\nPortanto, visando expandir a taxa de acessos à divulgação científica no Brasil, cabe ao Governo, órgão máximo do poder, em parceria com as grandes empresas de tecnologia, desenvolver leis de restrição sobre publicações de informações sem comprovação científica. Assim, a longo prazo, o número de fake news será reduzido e o prestígio das divulgações científicas será elevado em todo o território nacional.",
  "theme": "tema 22",
  "type": "essay",
  "updatedAt": "2025-06-27T01:31:00.622Z"
  "url": "https://example.com"
}

Reprocessar OCR

POST
/v1/ocr/{id}/retry

Reinicia o processamento OCR que falhou ou precisa ser reprocessado.

Parâmetros de Path

id (string): ID único do processamento OCR

Resposta

Status 200: OCR reprocessamento iniciado com sucesso

Playground Interativo

Carregando playground...

Troubleshooting

Problemas Comuns

Correção demorada mais que 60 segundos

Em casos raros, o processamento pode demorar mais devido ao volume de requisições.

Solução: Use webhooks para receber notificações quando a correção estiver pronta.

Erro de OCR em imagens manuscritas

A qualidade da imagem pode afetar a precisão do reconhecimento de texto.

Solução: Use imagens com boa iluminação, texto legível e resolução mínima de 1080p.

Limite de requisições excedido

Você atingiu o limite de 100 requisições por minuto.

Solução: Aguarde 1 minuto antes de fazer novas requisições à API.

Precisa de Ajuda?

Nossa equipe está disponível 24/7 para ajudar com integração e problemas técnicos.