Íris API

Documentação

v1

Base: https://irisai.com.br/v1. Autenticação: Authorization: Bearer iris_live_... (crie a chave em Chaves). Corpo e respostas em JSON (UTF-8). Valores em centavos de real.

Primeiros passos

Não há nada a instalar: a API é HTTP comum e funciona em qualquer linguagem (curl, Python, JavaScript, PHP, Java…). Do cadastro à primeira resposta leva poucos minutos.

  1. Entre com a sua conta da Íris (ou crie uma, grátis).
  2. Crie a organização em Começar: pessoa física ou empresa/escola, e aceite os termos.
  3. Ponha saldo em Recarga (PIX, cai na hora) ou contrate o Plano Escola. Só é cobrada a resposta entregue e aprovada.
  4. Gere a chave em Chaves. Ela aparece uma vez só: copie e guarde num lugar seguro. Perdeu? Revogue e gere outra.
  5. Experimente sem programar em Testar: cole uma questão ou um caso e veja a resposta completa.
  6. Faça a primeira chamada do seu sistema com o exemplo de Exemplos, trocando iris_live_... pela sua chave.

Boas práticas

  • Guarde a chave numa variável de ambiente (ex.: IRIS_API_KEY) no seu servidor. Nunca a coloque no aplicativo ou na página que o aluno abre.
  • Para não deixar o aluno esperando, use "modo": "async": guarde o id e consulte GET /v1/respostas/{id} a cada poucos segundos até "concluida".
  • Se a conexão cair, a resposta não se perde: ela fica 24 horas em /v1/respostas/{id}.
  • 402: recarregue. 429: espere o Retry-After. 503 ou 500: tente de novo em instantes (nada é cobrado).
  • Acompanhe o gasto em Uso e defina tetos por dia e por mês em Limites.
POST /v1/metacognicao

Gera as 8 etapas da metacognição para uma questão ou um caso, conferidas por um auditor antes de sair. Síncrono (até cerca de 90 s; passou disso, devolve 202 com o id e a resposta continua sendo gerada). Com "modo": "async" devolve 202 na hora, com o id.

CampoTipoObrigatórioDescrição
tipotextosimquestao ou caso
areatextosima matéria: biologia, fisica, quimica, matematica, direito, medicina… (até 60 caracteres)
niveltextosimensino_fundamental, ensino_medio, vestibular, graduacao, interno, formado, residente_r1, residente_r2, especialista, concurso, profissional — calibra o tamanho e a profundidade da resposta (veja Calibração por nível)
semestreinteironãosó com "nivel": "graduacao": 1 a 12. 1–4 ciclo básico, 5–8 ciclo clínico, 9–12 internato (igual a interno). Sem ele, a graduação usa a régua de sempre
enunciadotextosima questão ou o caso, até 20.000 caracteres
resposta_do_alunotextonãoo que o aluno respondeu (com ela, a resposta traz a nota de 0 a 10)
idiomatextonãopt-BR, en, es (padrão pt-BR)
modotextonãosync (padrão) ou async

Resposta 200

{
  "id": "resp_3fK9...",
  "objeto": "metacognicao",
  "status": "concluida",
  "entrada": { "tipo": "caso", "area": "medicina", "nivel": "graduacao", "semestre": 3, "idioma": "pt-BR", "caracteres": 412,
    "perfil": { "id": "graduacao_basico", "nome": "Graduação · ciclo básico (1º ao 4º semestre)", "palavras_max": 280, "lacunas_max": 2,
                "falseadores": 1, "vieses_max": 1, "dados_chave": 2, "alternativas_max": 1, "sintese_frases_max": 2 } },
  "etapas": {
    "resumo": "...",
    "problema_central": "...",
    "hipoteses": "...",
    "perguntas_metacognitivas": "...",
    "lacunas_de_informacao": "...",
    "vieses_cognitivos": "...",
    "estrategias_de_seguranca": "...",
    "sintese_reflexiva": "..."
  },
  "lacunas": ["..."],
  "vieses": [{ "nome": "Ancoragem", "explicacao": "..." }],
  "nota": { "valor": 4, "justificativa": "..." },
  "veredito": "...",
  "fontes": [{ "n": 1, "titulo": "...", "link": "https://pubmed.ncbi.nlm.nih.gov/...", "tipo": "Systematic Review", "ano": 2021, "revista": "..." }],
  "fonte_aviso": null,
  "auditoria": { "aprovada": true, "tentativas": 1, "pendencias": [] },
  "custo": { "cobrado_centavos": 49, "moeda": "BRL", "saldo_centavos": 41275 },
  "latencia_ms": 41230
}

Com o Plano Escola vigente, a resposta dentro do uso justo sai com "cobrado_centavos": 0 e "plano_escola": { "uso_justo_usado": 8421, "uso_justo_total": 20000 } no custo. Passou do uso justo, sai do saldo avulso; sem saldo, 402 uso_justo_atingido.

Toda resposta entregue foi aprovada pelo auditor. Se o auditor não aprovar nem depois das refações, a resposta não é entregue nem cobrada: você recebe 422 qualidade_nao_garantida e pode reformular o enunciado.

Fontes

Antes de gerar, a Íris busca as fontes do enunciado na biblioteca verificada (artigos indexados no PubMed, diretrizes e protocolos clínicos; psicologia incluída). Essas fontes são a única base que a resposta pode citar, sempre pelo número entre colchetes, [1], [2]…, que aparece no texto das etapas. O campo fontes traz só as fontes citadas, com título e link, montado a partir da biblioteca (nunca escrito pelo motor). Link ou número que não venha da biblioteca é descartado, e a citação de fonte inexistente reprova a resposta no auditor.

Sem fonte verificada (área que a biblioteca não cobre, como exatas, humanas e direito; ou nada encontrado), a resposta sai normalmente com "fontes": [] e "fonte_aviso": "explicação geral, sem fonte verificada". O mesmo vale se a busca na biblioteca falhar: a resposta não deixa de sair por isso.

Calibração por nível

O nivel (e o semestre, na graduação) escolhe a régua da resposta, que volta em entrada.perfil. Ensino fundamental, médio e vestibular usam a régua curta em qualquer área. Os níveis clínicos (graduação com semestre, interno, formado, residentes, especialista) valem nas áreas da saúde; fora da saúde, a régua é a geral. Um traço (—) quer dizer que o número não é fixado à parte: segue o roteiro dos 8 passos.

PerfilPalavras (máx.)Lacunas (máx.)FalseadoresVieses (máx.)Dados-chaveAlternativas (máx.)Síntese (frases)
curto
Régua curta — ensino fundamental, médio e vestibular (qualquer área)
200211112
graduacao_basico
Graduação · ciclo básico (1º ao 4º semestre)
280211212
graduacao_clinico
Graduação · ciclo clínico (5º ao 8º semestre)
350312323
interno_inicio
Graduação (sem semestre informado — como sempre foi)
35031————
interno
Internato (9º ao 12º semestre, ou nível interno)
35031————
formado_plantao
Formado / plantão
40052————
R1
Residente R1
40052————
R2
Residente R2
40052————
R3+
R3+ / especialista
50053————
generico
Fora da saúde (graduação, concurso, profissional)
40042————

Tabela versão 2026-11-17.

GET /v1/respostas/{id}

Consulta uma resposta do modo assíncrono (ou a síncrona que passou dos 90 s). Devolve "status": "na_fila", "processando", "falhou" ou a resposta completa ("concluida"). Toda resposta pronta (também a síncrona já entregue) fica disponível por 24 horas para recuperação — se a sua conexão caiu antes de receber, busque por aqui o que foi cobrado — e depois é apagada; com "guardar 30 dias" ligado no projeto, por 30 dias.

GET /v1/saldo

O saldo da organização, o que está reservado em chamadas em andamento, o nível e os limites.

{ "objeto": "saldo", "moeda": "BRL", "saldo_centavos": 41275, "reservado_centavos": 0, "disponivel_centavos": 41275,
  "nivel": 2, "limites": { "requisicoes_por_minuto": 60, "gasto_dia_centavos": 100000, "teto_dia_chave_centavos": null },
  "preco_resposta_centavos": 49, "tokens_entrada_por_resposta": 2000,
  "plano_escola": { "alunos": 500, "uso_justo_total": 20000, "uso_justo_usado": 8421, "inicio": "2026-11-05T13:00:00Z", "fim": "2026-12-05T13:00:00Z" } }

Sem Plano Escola vigente, plano_escola vem null.

GET /v1/status

Público, sem chave: { "status": "operacional", "versao": "v1" }. O histórico de 90 dias está em Status.

Preço

R$ 0,49 por resposta entregue, até 2.000 tokens de entrada (enunciado + resposta do aluno; 1 token ≈ 4 caracteres). Acima disso, proporcional. O preço é reservado antes e só é cobrado quando a resposta sai aprovada. Falha do nosso lado, tempo esgotado e resposta reprovada pelo auditor não custam nada.

Erros

Sempre no formato { "erro": { "tipo": "...", "mensagem": "..." } }.

CódigoTipoSignificaO que fazer
400requisicao_invalidaPedido inválidoConfira os campos; a mensagem diz qual
401chave_invalidaChave ausente, errada ou revogadaGere uma chave nova em Chaves
402saldo_insuficienteSaldo insuficienteRecarregue por PIX
402uso_justo_atingidoPlano Escola: o uso justo do período acabou e não há saldo avulsoRecarregue por PIX ou aumente os alunos na renovação
403acesso_negadoOrganização bloqueadaFale com o suporte da Íris
404nao_encontradoResposta não encontradaConfira o id
422qualidade_nao_garantidaO auditor não aprovou a respostaReformule o enunciado. Nada é cobrado
429limite_excedido, limite_gasto_diario, limite_gasto_mensalLimite por minuto ou teto de gastoEspere o tempo de Retry-After ou mude o teto em Limites
503motor_indisponivelInstabilidade nossaTente de novo. Nada é cobrado
503fila_cheiaTodas as vagas de processamento ocupadasTente de novo em instantes. Nada é reservado nem cobrado
500erro_internoErro nossoTente de novo. Nada é cobrado

Cabeçalhos de limite

x-ratelimit-limit: 60
x-ratelimit-remaining: 57
x-ratelimit-reset: 31
retry-after: 12        (só no 429)

Exemplos

curl https://irisai.com.br/v1/metacognicao \
  -H "Authorization: Bearer $IRIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tipo": "questao",
    "area": "biologia",
    "nivel": "ensino_medio",
    "enunciado": "Casal normal tem filho albino. Qual a chance de o próximo ser albino e menino?",
    "resposta_do_aluno": "1/4",
    "idioma": "pt-BR"
  }'

Íris API · a IA da Íris, com tecnologia própria de metacognição · Status · Documentação