Documentação da API

Use a IA do Intedge IA no seu sistema: texto, conversas com memória, agentes, transcrição e voz, com processamento local no Brasil. Autenticação por chave (Bearer), respostas em JSON.

Autenticação

Todas as chamadas usam sua chave no cabeçalho Authorization. Base: https://intedge.ia.br

A chave é gerada ao criar sua conta (gratuito) e fica no seu painel. Nos exemplos abaixo, troque SUA_CHAVE por ela.

Authorization: Bearer SUA_CHAVE

Como os Ints são contados

A cobrança é pelo total de tokens processados: entrada (prompt) + saída (resposta), retornados pela própria LLM. Toda resposta traz um objeto usage com o detalhamento e o balance (saldo restante). Valores em reais na página de preços; para estimar um prompt, use a calculadora de Ints.

Modo	Custo	Quando usar
Requisição única	Mais barato e previsível	Perguntas isoladas, sem memória.
Thread (memória)	Maior e crescente*	Conversas com contexto.
Transcrição	Por segundo de áudio	Converter áudio em texto.
Voz: texto em fala	3,8141 Ints por caractere	Gerar áudio a partir de texto.
Voz: fala em texto	25,43 Ints por segundo de áudio	Transcrição rápida de áudio.

* No modo Thread reenviamos o resumo + as mensagens recentes a cada turno, então o custo por chamada cresce com a conversa. Resumos periódicos (modelo menor) aparecem como linhas summary no seu histórico.

1. Requisição única POST

https://intedge.ia.br/api/ia/generate.php — sem memória.

curl -X POST https://intedge.ia.br/api/ia/generate.php \
  -H "Authorization: Bearer SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Explique o que é Pix em 1 frase"}'

Resposta:

{
  "success": true,
  "response": "Pix é um meio de pagamento instantâneo...",
  "model": "Ágil",
  "usage": { "tokens_in": 24, "tokens_out": 38, "tokens_charged": 62 },
  "balance": 999938
}

Para escolher a inteligência, envie "model" com o nome público. Sem isso, usa o padrão. Os nomes disponíveis também aparecem no Playground.

`model`	Perfil
`Ágil`	Respostas rápidas para o dia a dia.
`Avançado`	Mais inteligente e detalhado; pensa um pouco mais.

2. Conversa com memória (Thread) POST

Crie uma thread e mande mensagens nela — o contexto é mantido automaticamente.

Criar thread

curl -X POST https://intedge.ia.br/api/ia/threads.php \
  -H "Authorization: Bearer SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"title": "Suporte ao cliente"}'
→ { "success": true, "thread_id": 123, "title": "Suporte ao cliente" }

Enviar mensagem na thread

Se omitir thread_id, uma nova thread é criada e retornada.

curl -X POST https://intedge.ia.br/api/ia/chat.php \
  -H "Authorization: Bearer SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"thread_id": 123, "message": "Qual foi minha última pergunta?"}'

{
  "success": true,
  "response": "...",
  "thread_id": 123,
  "usage": {
    "tokens_in": 1840, "tokens_out": 210, "tokens_charged": 2050,
    "summary_generated": false, "summary_tokens_charged": 0
  },
  "balance": 997888
}

Listar / ver threads GET

GET https://intedge.ia.br/api/ia/threads.php                 # lista suas threads
GET https://intedge.ia.br/api/ia/threads.php?thread_id=123     # thread + mensagens

3. Transcrição de áudio POST

https://intedge.ia.br/api/ia/transcribe.php — envie o arquivo no campo audio (multipart).

curl -X POST https://intedge.ia.br/api/ia/transcribe.php \
  -H "Authorization: Bearer SUA_CHAVE" \
  -F "audio=@/caminho/audio.mp3"

{
  "success": true,
  "text": "transcrição completa...",
  "audio_seconds": 42,
  "usage": { "tokens_charged": 420 },
  "balance": 997468
}

4. Agentes GET / POST

Agentes são presets de comportamento (instruções + modelo preferido) que você cria em Agentes. São privados da sua conta — só a sua chave de API consegue usá-los.

Listar seus agentes GET

curl https://intedge.ia.br/api/ia/agents.php \
  -H "Authorization: Bearer SUA_CHAVE"

{
  "success": true,
  "agents": [
    { "id": 5, "name": "Atendimento", "description": "Atendente cordial", "icon": "bi-headset", "model": "Ágil" }
  ]
}

Usar um agente

Envie agent_id em generate.php (única) ou chat.php (thread). As instruções do agente são aplicadas automaticamente, antes da sua mensagem.

curl -X POST https://intedge.ia.br/api/ia/generate.php \
  -H "Authorization: Bearer SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"agent_id": 5, "prompt": "Bom dia, preciso de ajuda com meu pedido"}'

Se o agent_id não for da sua conta, ele é ignorado (a chamada segue sem agente). Numa thread, o agente informado na criação fica memorizado nela.

5. Compatível com a OpenAI POST

https://intedge.ia.br/v1/chat/completions segue o padrão Chat Completions da OpenAI: bibliotecas e ferramentas que já usam essa API funcionam trocando só o endereço (https://intedge.ia.br/v1) e a chave. A cobrança, os limites e o histórico são os mesmos da requisição única.

from openai import OpenAI

client = OpenAI(base_url="https://intedge.ia.br/v1", api_key="SUA_CHAVE")

resposta = client.chat.completions.create(
    model="Ágil",
    messages=[
        {"role": "system", "content": "Responda em português, de forma objetiva."},
        {"role": "user", "content": "Explique o que é Pix em 1 frase"},
    ],
)
print(resposta.choices[0].message.content)

curl https://intedge.ia.br/v1/chat/completions \
  -H "Authorization: Bearer SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"model": "Ágil", "messages": [{"role": "user", "content": "Explique o que é Pix em 1 frase"}]}'

Campo	Como funciona aqui
`model`	Nome público (veja a tabela de modelos acima ou `GET /v1/models`). Um nome desconhecido, como `gpt-4o-mini`, usa o modelo padrão.
`messages`	Papéis `system` (ou `developer`), `user` e `assistant`; conteúdo em texto. Até 200 mensagens.
`max_tokens` / `max_completion_tokens`	Teto de tokens da resposta (limitado pelo máximo do servidor).
`temperature`, `top_p`, `presence_penalty`, `frequency_penalty`, `seed`, `stop`	Aceitos.
`stream`	Aceito, no formato da OpenAI (SSE), mas a resposta chega inteira num só pedaço.
`agent_id`	Extra nosso: aplica um dos seus agentes. No SDK, envie em `extra_body={"agent_id": 5}`.
`n` > 1, `tools`, imagens, `response_format` JSON	Não suportados: a chamada responde 422 com a explicação.

A resposta traz choices[0].message.content e usage (prompt_tokens, completion_tokens, total_tokens e o extra ints_charged). O saldo vem no cabeçalho X-Ints-Balance. Erros seguem o formato da OpenAI: {"error": {"message": "...", "type": "..."}}.

curl https://intedge.ia.br/v1/models -H "Authorization: Bearer SUA_CHAVE"   # lista os modelos

Para conversas com memória guardada no servidor, use as threads; no padrão da OpenAI, o histórico vai inteiro em messages a cada chamada.

6. Voz: texto em fala e transcrição rápida

Dois serviços de voz que funcionam juntos ou separados:

Serviço	O que faz	Uso típico
Voz	Transforma texto em fala	Ler respostas para o cliente, URA, avisos, agentes de voz
Transcrição rápida	Transforma fala em texto	Transcrever áudios e ligações, entender o que o cliente falou

Os dois seguem o padrão da API de áudio da OpenAI: bibliotecas e sistemas que já usam essa API funcionam trocando apenas o endereço (https://intedge.ia.br/v1) e a chave.

Voz: texto em fala POST

https://intedge.ia.br/v1/audio/speech — leve e rápido; gera áudio natural em português em frações de segundo para frases curtas.

Campo (JSON)	Obrigatório	Descrição
`model`	sim	Sempre `"voz"` (bibliotecas da OpenAI que mandam `"tts-1"` também funcionam)
`input`	sim	O texto a ser falado (até 4.096 caracteres)
`voice`	sim	A voz (veja abaixo)
`response_format`	não	`mp3` (padrão), `wav`, `opus`, `flac`
`speed`	não	Velocidade da fala: `1.0` normal, `0.8` mais devagar, `1.2` mais rápido

`voice`	Voz	Como é
`int`	Int	Feminina, tom acolhedor
`int-neutro`	Int	Masculina, tom neutro
`int-grave`	Int	Masculina, tom grave

curl https://intedge.ia.br/v1/audio/speech \
  -H "Authorization: Bearer SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"model":"voz","input":"Olá! Seu chamado foi registrado e um técnico vai entrar em contato.","voice":"int","response_format":"mp3"}' \
  -o resposta.mp3

A resposta é o próprio arquivo de áudio, não um JSON. Os Ints cobrados e o saldo vêm nos cabeçalhos X-Ints-Charged e X-Ints-Balance. Em caso de erro, a resposta é o JSON de erro padrão.

Listar vozes GET

curl https://intedge.ia.br/v1/audio/voices \
  -H "Authorization: Bearer SUA_CHAVE"
→ {"success":true,"voices":["int","int-neutro","int-grave"]}

Dicas para uma fala mais natural:

Escreva números, datas e siglas por extenso quando a pronúncia importar ("dez e meia" em vez de "10:30").
Use pontuação para criar pausas: vírgula para pausa curta, ponto para pausa longa.
Palavras em inglês são lidas com pronúncia em português. Prefira o termo em português sempre que possível.

Transcrição rápida: fala em texto POST

https://intedge.ia.br/v1/audio/transcriptions — transcreve áudios em português com rapidez, indicada para transcrições simples e uso em tempo real.

Campo (multipart)	Obrigatório	Descrição
`file`	sim	O arquivo de áudio (mp3, wav, m4a, ogg, entre outros), até 100MB
`model`	sim	Sempre `"transcricao-rapida"` (bibliotecas da OpenAI que mandam outro nome também funcionam)
`language`	recomendado	`"pt"` para português. Informar o idioma melhora a precisão e a velocidade

curl https://intedge.ia.br/v1/audio/transcriptions \
  -H "Authorization: Bearer SUA_CHAVE" \
  -F "file=@ligacao.mp3" \
  -F "model=transcricao-rapida" \
  -F "language=pt"

{
  "success": true,
  "text": "Olá, eu gostaria de saber sobre a minha fatura.",
  "language": "pt",
  "duration": 3.4,
  "usage": { "type": "duration", "seconds": 4, "tokens_charged": 102 },
  "balance": 997468
}

Qual transcrição usar?

Serviço	Quando usar	Tempo
Transcrição rápida (`/v1/audio/transcriptions`)	Transcrição rápida e simples; agentes de voz; quando só o texto importa	Mais rápido
Transcrição completa (`/api/ia/transcribe.php`)	Áudios longos, quando quer a transcrição detalhada	Intermediário

Usando os dois juntos: agente de voz

O cliente fala, e o áudio é enviado à Transcrição rápida, que devolve o texto.
O texto vai para a IA de texto (generate.php ou chat.php), que gera a resposta.
A resposta vai para a Voz, que devolve o áudio.
O áudio é tocado para o cliente.

Operação	Tempo aproximado
Voz, frase curta	~0,2 s
Transcrição rápida, áudio curto (poucos segundos)	menos de 1 s
Transcrição rápida, ligação de 2 minutos	~7 s

Limites

Há limites por requisição, por janela de 5 horas e semanal (configuráveis). Ao estourar, a resposta vem com HTTP 429 (limite) ou 422 (mensagem grande demais). null = sem limite.

Ver seus limites e consumo GET

curl https://intedge.ia.br/api/ia/limits.php \
  -H "Authorization: Bearer SUA_CHAVE"

{
  "success": true,
  "balance": 987654,
  "limits": {
    "por_requisicao": { "max_tokens": 20000 },
    "janela_5h": {
      "tokens":      { "usados": 3200, "limite": 200000, "restante": 196800 },
      "requisicoes": { "usadas": 12,   "limite": 500,    "restante": 488 }
    },
    "semana": {
      "tokens":      { "usados": 45000, "limite": null, "restante": null },
      "requisicoes": { "usadas": 130,   "limite": null, "restante": null }
    }
  }
}

Toda resposta de geração/chat também traz o campo limits com esse mesmo resumo — assim você acompanha o consumo a cada chamada, sem precisar de outra requisição.

Erros

HTTP	Significado
401	Token inválido / não autenticado
402	Saldo de Ints insuficiente
422	Entrada inválida (vazia ou grande demais)
429	Limite de uso atingido
502 / 503	IA indisponível no momento

{ "success": false, "error": "mensagem do erro" }