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.
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.
iris_live_... pela sua chave.IRIS_API_KEY) no seu servidor. Nunca a coloque no aplicativo ou na página que o aluno abre."modo": "async": guarde o id e consulte GET /v1/respostas/{id} a cada poucos segundos até "concluida"./v1/respostas/{id}.Retry-After. 503 ou 500: tente de novo em instantes (nada é cobrado)./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.
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
tipo | texto | sim | questao ou caso |
area | texto | sim | a matéria: biologia, fisica, quimica, matematica, direito, medicina… (até 60 caracteres) |
nivel | texto | sim | ensino_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) |
semestre | inteiro | não | só 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 |
enunciado | texto | sim | a questão ou o caso, até 20.000 caracteres |
resposta_do_aluno | texto | não | o que o aluno respondeu (com ela, a resposta traz a nota de 0 a 10) |
idioma | texto | não | pt-BR, en, es (padrão pt-BR) |
modo | texto | não | sync (padrão) ou async |
{
"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.
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.
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.
| Perfil | Palavras (máx.) | Lacunas (máx.) | Falseadores | Vieses (máx.) | Dados-chave | Alternativas (máx.) | Síntese (frases) |
|---|---|---|---|---|---|---|---|
curtoRégua curta — ensino fundamental, médio e vestibular (qualquer área) | 200 | 2 | 1 | 1 | 1 | 1 | 2 |
graduacao_basicoGraduação · ciclo básico (1º ao 4º semestre) | 280 | 2 | 1 | 1 | 2 | 1 | 2 |
graduacao_clinicoGraduação · ciclo clínico (5º ao 8º semestre) | 350 | 3 | 1 | 2 | 3 | 2 | 3 |
interno_inicioGraduação (sem semestre informado — como sempre foi) | 350 | 3 | 1 | — | — | — | — |
internoInternato (9º ao 12º semestre, ou nível interno) | 350 | 3 | 1 | — | — | — | — |
formado_plantaoFormado / plantão | 400 | 5 | 2 | — | — | — | — |
R1Residente R1 | 400 | 5 | 2 | — | — | — | — |
R2Residente R2 | 400 | 5 | 2 | — | — | — | — |
R3+R3+ / especialista | 500 | 5 | 3 | — | — | — | — |
genericoFora da saúde (graduação, concurso, profissional) | 400 | 4 | 2 | — | — | — | — |
Tabela versão 2026-11-17.
/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.
/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.
/v1/status
Público, sem chave: { "status": "operacional", "versao": "v1" }. O histórico de 90 dias está em Status.
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.
Sempre no formato { "erro": { "tipo": "...", "mensagem": "..." } }.
| Código | Tipo | Significa | O que fazer |
|---|---|---|---|
400 | requisicao_invalida | Pedido inválido | Confira os campos; a mensagem diz qual |
401 | chave_invalida | Chave ausente, errada ou revogada | Gere uma chave nova em Chaves |
402 | saldo_insuficiente | Saldo insuficiente | Recarregue por PIX |
402 | uso_justo_atingido | Plano Escola: o uso justo do período acabou e não há saldo avulso | Recarregue por PIX ou aumente os alunos na renovação |
403 | acesso_negado | Organização bloqueada | Fale com o suporte da Íris |
404 | nao_encontrado | Resposta não encontrada | Confira o id |
422 | qualidade_nao_garantida | O auditor não aprovou a resposta | Reformule o enunciado. Nada é cobrado |
429 | limite_excedido, limite_gasto_diario, limite_gasto_mensal | Limite por minuto ou teto de gasto | Espere o tempo de Retry-After ou mude o teto em Limites |
503 | motor_indisponivel | Instabilidade nossa | Tente de novo. Nada é cobrado |
503 | fila_cheia | Todas as vagas de processamento ocupadas | Tente de novo em instantes. Nada é reservado nem cobrado |
500 | erro_interno | Erro nosso | Tente de novo. Nada é cobrado |
x-ratelimit-limit: 60 x-ratelimit-remaining: 57 x-ratelimit-reset: 31 retry-after: 12 (só no 429)
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"
}'
import os, requests
r = requests.post(
"https://irisai.com.br/v1/metacognicao",
headers={"Authorization": f"Bearer {os.environ['IRIS_API_KEY']}"},
json={
"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",
},
timeout=120,
)
r.raise_for_status()
for nome, texto in r.json()["etapas"].items():
print(nome, "→", texto)
const r = await fetch("https://irisai.com.br/v1/metacognicao", {
method: "POST",
headers: {
"Authorization": `Bearer ${process.env.IRIS_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
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",
}),
});
const j = await r.json();
if (!r.ok) throw new Error(j.erro.mensagem);
for (const [nome, texto] of Object.entries(j.etapas)) console.log(nome, texto);
Íris API · a IA da Íris, com tecnologia própria de metacognição · Status · Documentação