Uma chave para tudo que a Entelecy sabe fazer

Visão geral

A API da Entelecy é um gateway. Ela recebe requisições no formato de mercado, aplica autenticação, validação e medição, encaminha para o fornecedor certo e devolve a resposta praticamente intacta — inclusive o streaming, chunk a chunk. Na prática, se o seu código já fala com uma API de LLM, trocar a base URL e a chave costuma bastar.

O que o gateway acrescenta ao caminho:

• Uma credencial só. Nenhuma chave de fornecedor circula no cliente — elas ficam no servidor, e o que você guarda é uma chave kriou_live_… da Entelecy.
• Validação antes do gasto. Tamanho de imagem, duração de vídeo, teto de caracteres e modelo habilitado são conferidos no gateway; erro de envelope volta em milissegundos, sem custo.
• Medição no fim da chamada. O consumo real (tokens, segundos, caracteres, chamadas) vira débito em créditos na carteira da chave que fez a chamada.
• Troca de fornecedor sem quebrar contrato. O modelo por trás de cada capacidade pode mudar; o formato da requisição não muda com ele.

A raiz é pública e serve como sonda de saúde: responde sem autenticação e diz qual build está no ar.

curl https://api.entelecy.ai/ \
  -H "Accept: application/json"

# 200 OK
{
  "service": "Entelecy.Api",
  "environment": "Production",
  "timestamp": "2026-08-06T09:12:44.1180Z"
}

Autenticação

Toda chamada exige o header Authorization com uma chave da Entelecy no esquema Bearer. A chave nasce e vive na sua conta; o gateway a valida contra o Entelecy Account e mantém o resultado em cache curto, de modo que o custo dessa checagem é desprezível no caminho quente.

POST /v1/chat/completions HTTP/1.1
Host: api.entelecy.ai
Authorization: Bearer kriou_live_7Qb3xk9_M2pN-VtR4sLu8Z
Content-Type: application/json

Sobre as credenciais aceitas:

• kriou_live_… — chave de produção. É a forma normal de integrar.
• kriou_test_… — chave de teste, útil para ambientes de homologação. Endpoints podem ser configurados para recusá-la.

Convenções

Corpo e resposta em JSON UTF-8, salvo onde indicado (upload de áudio e mídia usa multipart/form-data; síntese de voz responde bytes de áudio; transcrição responde texto puro). Campos que o gateway não conhece são repassados ao fornecedor sem alteração — é o que permite usar recursos novos antes de eles aparecerem nesta página.

Headers

Streaming

Com "stream": true a resposta vira text/event-stream: linhas data: …, uma por evento, sem buffer intermediário. O último evento útil carrega o consumo da chamada; depois dele vem data: [DONE].

data: {"id":"...","object":"chat.completion.chunk","choices":[{"delta":{"content":"Ent"}}]}

data: {"id":"...","choices":[],"usage":{"prompt_tokens":812,"completion_tokens":214,"total_tokens":1026}}

data: [DONE]

Erros

Erros gerados pelo gateway têm sempre a mesma forma: um objeto error com type, message e, quando ajuda, code e param. Erros vindos do fornecedor são repassados com o status e o corpo originais.

{
  "error": {
    "type": "invalid_request_error",
    "message": "Campo 'model' e obrigatorio."
  }
}

Códigos do gateway

São as recusas decididas antes de chamar o fornecedor. Todas voltam em 400, custam zero crédito e trazem mensagem acionável — dá para corrigir o pedido e repetir sem adivinhação.

Corpo do 402

{
  "error": {
    "type": "insufficient_credits",
    "message": "Saldo insuficiente pra chamar a API.",
    "balance": 3,
    "required": 10,
    "missing": 7,
    "plan_id": "starter",
    "renews_at": "2026-09-01T00:00:00Z",
    "upgrade_url": "https://account.entelecy.ai/plans"
  }
}

Endpoints

Doze rotas, agrupadas por capacidade. A coluna da direita adianta a unidade de cobrança — o detalhe está em Cobrança.

Texto — Chat Completions

Formato compatível com Chat Completions: o mesmo corpo que você já manda para clientes OpenAI-compatíveis funciona aqui, incluindo ferramentas, saída estruturada e streaming. É o endpoint de uso geral — conversa, geração, extração, classificação, agentes.

curl -N https://api.entelecy.ai/v1/chat/completions \
  -H "Authorization: Bearer $ENTELECY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "loom-flash",
    "effort": "high",
    "stream": true,
    "messages": [
      { "role": "system", "content": "Responda em portugues do Brasil, direto ao ponto." },
      { "role": "user",   "content": "Resuma o conceito de entelequia em tres linhas." }
    ]
  }'

{
  "id": "bf1b8201-5085-455c-9556-8ebd39a0a34e",
  "object": "chat.completion",
  "created": 1786061432,
  "model": "loom-flash",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Entelequia e…",
        "reasoning": "(so quando o modelo pensa antes de responder)"
      },
      "logprobs": null,
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 812,
    "completion_tokens": 214,
    "total_tokens": 1026,
    "prompt_tokens_details": { "cached_tokens": 640 },
    "completion_tokens_details": { "reasoning_tokens": 159 }
  }
}

Imagem

Geração e edição de imagem no formato de mercado, com validação de envelope no gateway. O retorno traz a imagem em base64 e o consumo em tokens da chamada.

curl https://api.entelecy.ai/v1/images/generations \
  -H "Authorization: Bearer $ENTELECY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "loom-image",
    "prompt": "Fachada de uma padaria de bairro ao amanhecer, luz quente, fotografia",
    "size": "1536x1024",
    "quality": "high",
    "n": 1
  }'

{
  "created": 1785969142,
  "data": [{ "b64_json": "iVBORw0KGgoAAAANSUhEUg…" }],
  "usage": {
    "input_tokens": 42,
    "input_tokens_details": { "cached_tokens": 0 },
    "output_tokens": 1568,
    "total_tokens": 1610
  }
}

{
  "model": "loom-image",
  "prompt": "Troque o fundo por um ceu limpo no fim da tarde",
  "image": ["iVBORw0KGgo…"],
  "mask": "iVBORw0KGgo…",
  "size": "1024x1024"
}

Áudio

Dois caminhos: transcrever fala em texto e sintetizar texto em voz. A escolha do motor de transcrição é feita pelo campo model; sem ele, vale o padrão do servidor.

curl https://api.entelecy.ai/v1/audio/transcriptions \
  -H "Authorization: Bearer $ENTELECY_API_KEY" \
  -F "[email protected]" \
  -F "model=loom-audio" \
  -F "language=pt"

# 200 OK · text/plain
Bom dia. Comecando a reuniao de quinta…

curl https://api.entelecy.ai/v1/audio/speech \
  -H "Authorization: Bearer $ENTELECY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "loom-audio",
    "input": "A entrega de quinta esta confirmada. Qualquer mudanca, aviso por aqui.",
    "response_format": "mp3_44100_128"
  }' \
  --output aviso.mp3

Vídeo

Geração de vídeo é assíncrona: você submete o pedido, recebe um identificador e consulta até o estado ficar terminal. Vídeo a partir de imagem usa uma mídia de referência enviada antes.

# 1) submit — devolve o id da predicao
curl https://api.entelecy.ai/v1/videos/generations \
  -H "Authorization: Bearer $ENTELECY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "loom-video",
    "prompt": "Plano aereo de uma feira livre ao amanhecer, camera avancando devagar",
    "duration": 6,
    "resolution": "720p"
  }'

# { "data": { "id": "pred_01J8Z…", "status": "queued" } }

# 2) poll — ate status completed
curl https://api.entelecy.ai/v1/videos/generations/pred_01J8Z… \
  -H "Authorization: Bearer $ENTELECY_API_KEY"

# { "data": { "status": "completed", "outputs": [{ "url": "https://…/video.mp4" }] } }

Busca

Busca na web com resultados estruturados — pensado para dar contexto atual a um agente antes de ele responder. O corpo é repassado ao mecanismo, então parâmetros de região, idioma e quantidade funcionam como na origem.

curl https://api.entelecy.ai/v1/search \
  -H "Authorization: Bearer $ENTELECY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "q": "relatorio anual industria de embalagens brasil", "gl": "br", "hl": "pt-br", "num": 10 }'

Modelos

O campo model recebe um nome público da Entelecy. Ele descreve a capacidade que você quer; qual modelo atende àquilo é decisão nossa, revisada continuamente. A resolução é por (nome, rota) — nome fora da lista da rota é 400 antes de qualquer gasto.

Como escolhemos

Não somos fiéis a um fornecedor. Cada segmento é um campo em movimento — modelo novo todo mês, preço caindo, capacidade mudando — e o que faz sentido hoje pode não fazer no trimestre que vem. Acompanhamos as famílias relevantes de cada um, medimos no nosso próprio material e trocamos quando compensa.

O critério, em ordem:

• Qualidade no português do Brasil. Avaliamos em conteúdo real de clientes, não em benchmark traduzido.
• Custo por resultado aceito. Não o preço por token: o preço da resposta que passou na revisão.
• Latência previsível. Modelo bom que oscila de 3 a 40 segundos não serve para produto interativo.
• Estabilidade de contrato. Fornecedor que muda formato sem aviso custa caro no longo prazo.

Cobrança

Tudo é cobrado em créditos, na carteira do dono da credencial. Cada capacidade tem a unidade que corresponde ao trabalho real:

Antes de encaminhar, o gateway confere um saldo mínimo para a operação — maior em imagem e vídeo, que custam mais. Sem saldo, a resposta é 402 com quanto falta e o link para recarregar, e nada é gasto com o fornecedor.

O débito acontece depois da resposta, com o consumo real, e é idempotente por chamada: uma retentativa de rede não cobra duas vezes. Chamadas que falham no fornecedor não geram débito.

Exemplos de implementação

Código pronto para colar, com os mesmos modelos que o Loom — nosso próprio produto — roda em produção, e com o tratamento que costuma faltar: erro de saldo, chunk partido no meio do stream e leitura do consumo no fim da chamada.

const BASE = 'https://api.entelecy.ai';
const KEY  = process.env.ENTELECY_API_KEY;

/**
 * Chat com streaming. Devolve o texto completo e o usage do ultimo chunk.
 * O gateway sempre pede usage no fim do stream — nao e preciso configurar nada.
 */
export async function chatStream(messages, { effort = 'high', onDelta } = {}) {
  const res = await fetch(`${BASE}/v1/chat/completions`, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${KEY}`,
      'Content-Type': 'application/json',
    },
    // model e effort sao eixos separados: o nome escolhe a faixa, o effort a profundidade
    body: JSON.stringify({ model: 'loom-flash', effort, stream: true, messages }),
  });

  if (!res.ok) {
    // 402 = saldo insuficiente; o corpo traz balance/required/upgrade_url
    const err = await res.json().catch(() => ({}));
    throw new Error(`${res.status} ${err?.error?.type ?? 'erro'}: ${err?.error?.message ?? ''}`);
  }

  const reader  = res.body.getReader();
  const decoder = new TextDecoder();
  let buffer = '', text = '', usage = null;

  while (true) {
    const { value, done } = await reader.read();
    if (done) break;
    buffer += decoder.decode(value, { stream: true });

    // SSE: eventos separados por linha; so nos importam as linhas "data: "
    const lines = buffer.split('\n');
    buffer = lines.pop() ?? '';

    for (const line of lines) {
      if (!line.startsWith('data: ')) continue;
      const payload = line.slice(6).trim();
      if (payload === '[DONE]') continue;

      let chunk;
      try { chunk = JSON.parse(payload); } catch { continue; }   // chunk partido

      const delta = chunk.choices?.[0]?.delta?.content;
      if (delta) { text += delta; onDelta?.(delta); }
      if (chunk.usage) usage = chunk.usage;                      // ultimo chunk
    }
  }

  return { text, usage };
}

import { writeFile } from 'node:fs/promises';

export async function gerarImagem(prompt, { size = '1024x1024' } = {}) {
  const res = await fetch(`${BASE}/v1/images/generations`, {
    method: 'POST',
    headers: { 'Authorization': `Bearer ${KEY}`, 'Content-Type': 'application/json' },
    body: JSON.stringify({ model: 'loom-image', prompt, size, n: 1 }),
  });

  const body = await res.json();
  if (!res.ok) {
    // gateway_invalid_size chega aqui ANTES de custar credito
    throw new Error(`${body.error?.code ?? res.status}: ${body.error?.message}`);
  }

  await writeFile('saida.png', Buffer.from(body.data[0].b64_json, 'base64'));
  return body.usage;
}

import json, os, requests

BASE = "https://api.entelecy.ai"
KEY  = os.environ["ENTELECY_API_KEY"]


def chat_stream(messages, effort: str = "high"):
    """Chat com streaming. Retorna (texto, usage)."""
    with requests.post(
        f"{BASE}/v1/chat/completions",
        headers={
            "Authorization": f"Bearer {KEY}",
            "Content-Type": "application/json",
        },
        json={"model": "loom-flash", "effort": effort, "stream": True, "messages": messages},
        stream=True,
        timeout=(10, 600),          # conexao curta, leitura longa
    ) as res:
        if res.status_code == 402:
            raise RuntimeError(f"saldo insuficiente: {res.json()['error']}")
        res.raise_for_status()

        texto, usage = [], None
        for raw in res.iter_lines(decode_unicode=True):
            if not raw or not raw.startswith("data: "):
                continue
            payload = raw[6:].strip()
            if payload == "[DONE]":
                break
            chunk = json.loads(payload)
            if chunk.get("choices"):
                delta = chunk["choices"][0].get("delta", {}).get("content")
                if delta:
                    texto.append(delta)
                    print(delta, end="", flush=True)
            if chunk.get("usage"):
                usage = chunk["usage"]

        return "".join(texto), usage

def transcrever(caminho: str, language: str = "pt") -> str:
    with open(caminho, "rb") as f:
        res = requests.post(
            f"{BASE}/v1/audio/transcriptions",
            headers={"Authorization": f"Bearer {KEY}"},
            files={"file": (os.path.basename(caminho), f, "audio/m4a")},
            data={"model": "loom-audio", "language": language},
            timeout=(10, 300),
        )
    res.raise_for_status()
    return res.text          # o endpoint devolve texto puro, nao JSON

using System.Net.Http.Headers;
using System.Text;
using System.Text.Json;

public sealed class EntelecyClient(HttpClient http, string apiKey)
{
    private static readonly JsonSerializerOptions Json = new(JsonSerializerDefaults.Web);

    /// <summary>Chat com streaming: entrega cada delta no callback e devolve o usage final.</summary>
    public async Task<JsonElement?> ChatStreamAsync(
        object[] messages, Action<string> onDelta, string effort = "high", CancellationToken ct = default)
    {
        var body = JsonSerializer.Serialize(new { model = "loom-flash", effort, stream = true, messages });

        using var req = new HttpRequestMessage(HttpMethod.Post, "/v1/chat/completions")
        {
            Content = new StringContent(body, Encoding.UTF8, "application/json")
        };
        req.Headers.Authorization = new AuthenticationHeaderValue("Bearer", apiKey);

        using var res = await http.SendAsync(req, HttpCompletionOption.ResponseHeadersRead, ct);
        if (!res.IsSuccessStatusCode)
            throw new InvalidOperationException(
                $"{(int)res.StatusCode}: {await res.Content.ReadAsStringAsync(ct)}");

        await using var stream = await res.Content.ReadAsStreamAsync(ct);
        using var reader = new StreamReader(stream);

        JsonElement? usage = null;
        while (await reader.ReadLineAsync(ct) is { } line)
        {
            if (!line.StartsWith("data: ", StringComparison.Ordinal)) continue;
            var payload = line[6..].Trim();
            if (payload == "[DONE]") break;

            JsonDocument doc;
            try { doc = JsonDocument.Parse(payload); } catch (JsonException) { continue; }
            using (doc)
            {
                if (doc.RootElement.TryGetProperty("choices", out var choices)
                    && choices.GetArrayLength() > 0
                    && choices[0].TryGetProperty("delta", out var delta)
                    && delta.TryGetProperty("content", out var content))
                {
                    onDelta(content.GetString() ?? "");
                }
                if (doc.RootElement.TryGetProperty("usage", out var u))
                    usage = u.Clone();
            }
        }
        return usage;
    }
}

Limites e boas práticas

• Use streaming em resposta longa. Além da percepção de velocidade, evita timeout de proxy em geração demorada.
• Repita com recuo exponencial. Erros de limite de taxa e indisponibilidade do fornecedor são transitórios; erros 4xx do gateway não melhoram com retentativa.
• Marque o prefixo estável com cache. Em prompts com base de conhecimento repetida, é a economia mais fácil de conquistar.
• Valide tamanho de imagem no seu formulário. O gateway recusa de graça, mas a viagem até ele custa tempo do usuário.
• Divida texto longo antes da síntese de voz. Há teto por requisição, e trechos menores ficam melhores de ouvir.
• Guarde o identificador do vídeo. A consulta é a única forma de recuperar o resultado, e é ela que dispara a cobrança quando fica pronto.

Precisa de limite maior, endpoint dedicado ou modelo fora desta lista? Fale com a gente em [email protected].