Documentação da API OrfeuAI

API REST compatível com OpenAI SDK. Três modelos disponíveis: ARPA-1 Lite (Qwen3 local), ARPA-1 Mini (Llama 4 Scout via Groq) e ARPA-1 Max (GPT-OSS via Groq). Function calling e MCP Memory funcionando. Streaming em manutenção, Web Search em breve.

Créditos de Teste: Primeira conta criada recebe R$ 25,00 em créditos para testar a API gratuitamente.

LGPD Compliance

ARPA-1 Lite (OrfeuAI) processa no Brasil. Mini e Max via Groq (internacional).

Performance

Powered by Groq. Latência ultra-baixa, 500 tokens/segundo.

Compatível OpenAI

Mesma interface. Troque base_url e API key, funciona.

Pay-as-you-go

Pague apenas pelo que usar. R$ 4/M input, R$ 8/M output.

Autenticação

Como Obter sua API Key

Crie uma conta e gere sua API key no painel OrfeuAI:

  1. Acesse https://dashboard.orfeuai.com
  2. Faça login ou crie uma conta
  3. Vá em Configurações → API Keys
  4. Clique em Criar Nova API Key
  5. Copie a key (ela só será mostrada uma vez)
Importante: Primeira conta criada recebe R$ 25,00 em créditos de teste automaticamente.

Usando a API Key

Inclua a key no header Authorization de todas as requisições:

HTTP
Authorization: Bearer sk-orfeu-xxxxxxxxxxxxxxxxxx
Segurança: Nunca exponha sua API key em código público, frontend ou repositórios Git. Use variáveis de ambiente.

Quick Start

Python (Recomendado)

Instale o SDK do OpenAI e configure para usar a base URL da OrfeuAI:

Bash
pip install openai
Python
from openai import OpenAI

client = OpenAI(
    api_key="sk-orfeu-xxxxx",
    base_url="https://api.orfeuai.com/v1"
)

response = client.chat.completions.create(
    model="arpa-1-lite",
    messages=[
        {"role": "user", "content": "Quanto é 2+2?"}
    ]
)

print(response.choices[0].message.content)
print(f"Tokens usados: {response.usage.total_tokens}")
print(f"Custo: R$ {response.x_orfeuai_billing['custo_brl']:.6f}")

Node.js

Bash
npm install openai
JavaScript
import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: 'sk-orfeu-xxxxx',
  baseURL: 'https://api.orfeuai.com/v1'
});

const response = await client.chat.completions.create({
  model: 'arpa-1-lite',
  messages: [
    { role: 'user', content: 'Quanto é 2+2?' }
  ]
});

console.log(response.choices[0].message.content);
console.log('Tokens:', response.usage.total_tokens);

cURL

Bash
curl -X POST https://api.orfeuai.com/v1/chat/completions \
  -H "Authorization: Bearer sk-orfeu-xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "arpa-1-lite",
    "messages": [
      {"role": "user", "content": "Quanto é 2+2?"}
    ]
  }'

Playground Interativo

Teste a API diretamente no navegador sem escrever código. Configure os parâmetros, envie a requisição e veja a resposta em tempo real.

API Playground

Teste a API diretamente no navegador

Obtenha em dashboard.orfeuai.com
0 = Deterministico, 2 = Criativo

Resposta

Configure os parametros e clique em "Enviar Request"

Precisa de uma API key? Crie aqui

ARPA-1 Lite

Modelo rápido e econômico. Suporta apenas texto. Processamento via OrfeuAI (llama.cpp local).

Especificações Técnicas

BackendQwen3
Janela de Contexto32k tokens
CapacidadeTexto apenas
Function Calling✓ Disponível
Tools/MCP✓ Disponível
InfraestruturaOrfeuAI

Casos de Uso

  • Chat geral e assistentes virtuais
  • Análise de texto e documentos
  • Classificação e sumarização
  • Prototipagem rápida
  • Desenvolvimento de aplicações

ARPA-1 Mini

Especificações Técnicas

BackendLlama 4 Scout
Janela de Contexto128k tokens
CapacidadeTexto + Imagens
Function Calling✓ Disponível
Tools/MCP✓ Disponível
InfraestruturaGroq

Casos de Uso

  • Tarefas complexas com imagens
  • Análise visual avançada
  • Processamento de documentos com gráficos
  • Extração de dados estruturados de imagens
  • Descrição detalhada de cenas visuais

ARPA-1 Max

Especificações Técnicas

BackendGPT-OSS
Janela de Contexto128k tokens
CapacidadeTexto apenas (Reasoning avançado)
Function Calling✓ Disponível
Tools/MCP✓ Disponível
InfraestruturaGroq

Casos de Uso

  • Raciocínio avançado e análises complexas
  • Geração de código
  • Problemas lógicos e matemática
  • Análise de documentos jurídicos
  • Tarefas que exigem máxima capacidade

Comparação de Modelos

CaracterísticaARPA-1 LiteARPA-1 MiniARPA-1 Max
BackendQwen3Llama 4 ScoutGPT-OSS
Janela de Contexto32k tokens128k tokens128k tokens
CapacidadeTexto apenasTexto + ImagensTexto apenas (Reasoning)
VelocidadeRápidaMuito rápidaRápida
InfraestruturaOrfeuAIGroqGroq
Chat Básico
Streaming⚠️ Em manutenção⚠️ Em manutenção⚠️ Em manutenção
Visão (Imagens)
Function Calling
MCP Memory
Web Search⚠️ Em breve⚠️ Em breve⚠️ Em breve
CustoR$ 2,00/M in • R$ 4,00/M outR$ 3,00/M in • R$ 6,00/M outR$ 4,00/M in • R$ 8,00/M out

Tabela de Preços

Pay-as-you-go. Preços em BRL. Três modelos disponíveis: ARPA-1 Lite, ARPA-1 Mini e ARPA-1 Max.

ARPA-1 Lite

Disponível
InputR$ 2,00 / 1M tokens
OutputR$ 4,00 / 1M tokens

Modelo econômico e rápido. Chat geral, análise de texto.

ARPA-1 Mini

Disponível
InputR$ 3,00 / 1M tokens
OutputR$ 6,00 / 1M tokens

Modelo balanceado multimodal. Análise avançada de imagens e documentos.

ARPA-1 Max

Disponível
InputR$ 4,00 / 1M tokens
OutputR$ 8,00 / 1M tokens

Modelo avançado com reasoning. Tarefas complexas, geração de código, análise lógica.

Chat Completions

Endpoint principal. Formato OpenAI.

POSThttps://api.orfeuai.com/v1/chat/completions

Corpo da Requisição

JSON
{
  "model": "arpa-1-lite",
  "messages": [
    {"role": "system", "content": "Você é um assistente útil."},
    {"role": "user", "content": "Olá!"}
  ],
  "temperature": 0.7,
  "max_tokens": 1000,
  "stream": false
}

Resposta (200 OK)

JSON
{
  "id": "chatcmpl-8xK2Jf9V3n1m2Z",
  "object": "chat.completion",
  "created": 1704118400,
  "model": "arpa-1-lite",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Olá! Como posso ajudar você hoje?"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 18,
    "completion_tokens": 12,
    "total_tokens": 30
  },
  "x_orfeuai_billing": {
    "custo_brl": 0.000168,
    "creditos_restantes": 24.832
  }
}

Campos da Resposta

id

ID único da requisição. Formato: chatcmpl-[hash]

object

Tipo do objeto. Sempre chat.completion para requests não-streaming.

created

Timestamp Unix (segundos desde 1970-01-01).

choices

Array com respostas geradas. Cada choice contém index, message e finish_reason.

usage

Estatísticas de tokens. Inclui prompt_tokens, completion_tokens e total_tokens.

x_orfeuai_billing

Informações de cobrança OrfeuAI. custo_brl é o custo total da requisição em reais, creditos_restantes mostra saldo atual da conta.

Parâmetros

modelobrigatório

ID do modelo: arpa-1-lite, arpa-1-mini, ou arpa-1-max

messagesobrigatório

Array de mensagens com role (system/user/assistant) e content

temperatureopcional

Aleatoriedade (0-2). Padrão: 0.7. Baixo = determinístico, alto = criativo.

max_tokensopcional

Limite de tokens na resposta. Controla custo.

streamopcional

Se true, retorna tokens em tempo real (SSE). Padrão: false.

top_popcional

Nucleus sampling (0-1). Alternativa a temperature. Padrão: 1.

Function CallingTodos os modelos

Modelo chama funções que você define. Útil para APIs externas, bancos de dados, cálculos. Disponível em todos os modelos ARPA-1 (Lite, Mini e Max).

Exemplo: Buscar Clima

Python
# 1. Definir função
tools = [{
    "type": "function",
    "function": {
        "name": "get_weather",
        "description": "Obtém o clima atual de uma cidade",
        "parameters": {
            "type": "object",
            "properties": {
                "city": {
                    "type": "string",
                    "description": "Nome da cidade"
                },
                "unit": {
                    "type": "string",
                    "enum": ["celsius", "fahrenheit"]
                }
            },
            "required": ["city"]
        }
    }
}]

# 2. Fazer requisição
response = client.chat.completions.create(
    model="arpa-1-lite",
    messages=[{"role": "user", "content": "Qual o clima em São Paulo?"}],
    tools=tools,
    tool_choice="auto"
)

# 3. Processar resposta
if response.choices[0].message.tool_calls:
    function_call = response.choices[0].message.tool_calls[0]

    if function_call.function.name == "get_weather":
        # Executar sua função
        weather = get_weather(city="São Paulo")

        # Enviar resultado de volta
        messages.append({
            "role": "function",
            "name": "get_weather",
            "content": str(weather)
        })

        final_response = client.chat.completions.create(
            model="arpa-1-lite",
            messages=messages
        )
Importante: Modelo decide quando chamar. Você executa a função e retorna o resultado.

ToolsTodos os modelos

Ferramentas integradas. MCP Memory e Web Search disponíveis em todos os modelos ARPA-1.

MCP Memory

Memória persistente do usuário. Salva preferências, contexto e informações entre conversas.

Python
# Salvar informação
tools = [{
    "type": "function",
    "function": {
        "name": "memory_save_user_info",
        "description": "Salva informação do usuário",
        "parameters": {
            "type": "object",
            "properties": {
                "category": {"type": "string"},
                "information": {"type": "string"}
            },
            "required": ["category", "information"]
        }
    }
}]

response = client.chat.completions.create(
    model="arpa-1-lite",
    messages=[{
        "role": "user",
        "content": "Meu nome é João e gosto de programar em Python"
    }],
    tools=tools
)

Web SearchEm Breve

Busca informações na web. Eventos recentes, dados atualizados.

Status: Feature em desenvolvimento. Implementação prevista para próxima versão da API.

StreamingEm Manutenção

Tokens em tempo real. Melhor UX em chats. Disponível em todos os modelos (ARPA-1 Lite, Mini e Max).

Status: Feature temporariamente indisponível devido a correções de bugs. Previsão de retorno: próximas horas.

Python

Python
stream = client.chat.completions.create(
    model="arpa-1-lite",
    messages=[{"role": "user", "content": "Escreva um poema"}],
    stream=True
)

for chunk in stream:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)

JavaScript

JavaScript
const stream = await client.chat.completions.create({
  model: 'arpa-1-lite',
  messages: [{ role: 'user', content: 'Escreva um poema' }],
  stream: true
});

for await (const chunk of stream) {
  const content = chunk.choices[0]?.delta?.content || '';
  process.stdout.write(content);
}

Códigos de Erro

A API retorna códigos HTTP padrão. Erros incluem mensagem detalhada no JSON.

CódigoTipoDescriçãoSolução
400invalid_request_errorParâmetros inválidos ou faltandoVerifique o corpo da requisição
401authentication_errorAPI key ausente ou inválidaVerifique header Authorization
402insufficient_creditsCréditos insuficientesAdicione créditos no dashboard
429rate_limit_errorRate limit excedidoAguarde ou faça upgrade do plano
500server_errorErro interno do servidorTente novamente em alguns segundos
503service_unavailableServiço temporariamente indisponívelAguarde manutenção programada

Exemplos de Respostas de Erro

json
{
  "error": {
    "message": "Incorrect API key provided: sk-orfeu-****xyz",
    "type": "invalid_request_error",
    "param": null,
    "code": "invalid_api_key"
  }
}

Tratamento de Erros (Python)

pythonerror_handling.py
from openai import OpenAI, OpenAIError
import time

client = OpenAI(
    api_key="sk-orfeu-xxxxx",
    base_url="https://api.orfeuai.com/v1"
)

def request_with_retry(max_retries=3):
    for attempt in range(max_retries):
        try:
            response = client.chat.completions.create(
                model="arpa-1-lite",
                messages=[{"role": "user", "content": "Hello"}]
            )
            return response

        except OpenAIError as e:
            if e.status_code == 401:
                print(f"Erro de autenticação: {e.message}")
                raise

            elif e.status_code == 429:
                wait_time = min(2 ** attempt, 60)
                print(f"Rate limit. Aguardando {wait_time}s...")
                time.sleep(wait_time)

            elif e.status_code == 402:
                print(f"Créditos insuficientes: {e.message}")
                raise

            elif e.status_code >= 500:
                wait_time = 2 ** attempt
                print(f"Erro do servidor. Tentativa {attempt+1}/{max_retries}")
                time.sleep(wait_time)

            else:
                raise

    raise Exception("Max retries atingido")

# Usar
try:
    response = request_with_retry()
    print(response.choices[0].message.content)
except Exception as e:
    print(f"Falha apos retries: {e}")

Limites e Erros

Rate Limits

Limites por plano.

PlanoRPMTPMRPD
Free10 req/min100k tokens/min500 req/dia
Pro100 req/min1M tokens/min5k req/dia
EnterpriseCustomCustomCustom

Headers de Resposta

Headers de rate limit em toda resposta:

HTTP Headers
X-RateLimit-Limit-Requests: 100
X-RateLimit-Remaining-Requests: 87
X-RateLimit-Reset-Requests: 2024-10-21T14:30:00Z

X-RateLimit-Limit-Tokens: 1000000
X-RateLimit-Remaining-Tokens: 456789
X-RateLimit-Reset-Tokens: 2024-10-21T14:30:00Z
Precisa de limites maiores? Entre em contato para planos Enterprise customizados.

Códigos de Erro HTTP

400 Bad Request

Causa: Requisição mal formatada. JSON inválido ou parâmetros faltando.
Solução: Verifique se o JSON está correto e se model e messages estão presentes.

401 Unauthorized

Causa: API key inválida, ausente ou expirada.
Solução: Verifique o header Authorization: Bearer sk-orfeu-... e obtenha nova key se necessário.

402 Payment Required

Causa: Créditos insuficientes na conta.
Solução: Adicione créditos via dashboard ou Stripe.

429 Too Many Requests

Causa: Rate limit excedido (muito requisições por minuto).
Solução: Aguarde 60 segundos ou implemente backoff exponencial.

500 Internal Server Error

Causa: Erro no servidor OrfeuAI ou Groq.
Solução: Verifique se GROQ_API_KEY está configurada. Tente novamente em alguns segundos. Se persistir, contate suporte.

503 Service Unavailable

Causa: API temporariamente indisponível (manutenção ou sobrecarga).
Solução: Aguarde alguns minutos e tente novamente. Implemente retry com backoff.

Problemas Comuns

Erro: Connection Refused / Network Error

Causa: URL incorreta, problemas de rede, ou firewall bloqueando.
Solução: Verifique se está usando a URL oficial da API. Confirme sua conexão de internet e configurações de firewall.

Python
# URL oficial da API OrfeuAI
BASE_URL = "https://api.orfeuai.com/v1"

# Teste de conexão
response = requests.get(f"{BASE_URL}/models")
print(response.status_code)  # Deve retornar 200

Erro: Invalid JSON

Causa: JSON mal formatado na requisição.
Solução: Valide o JSON antes de enviar. Comum esquecer vírgulas ou usar aspas simples.

Python
import json

# Valide antes de enviar
data = {
    "model": "arpa-1-lite",
    "messages": [{"role": "user", "content": "Olá"}]
}
json.dumps(data)  # Lança exceção se inválido

Resposta Vazia ou Timeout

Causa: Requisição muito longa, timeout de rede, ou servidor sobrecarregado.
Solução: Reduza o tamanho da mensagem, aumente timeout do cliente, ou tente novamente. Se persistir, entre em contato com suporte.

Python
# Aumente o timeout (padrão é 60s)
client = OpenAI(
    api_key="sk-orfeu-xxxxx",
    base_url="https://api.orfeuai.com/v1",
    timeout=120  # 2 minutos
)

Formato de Resposta de Erro

JSON
{
  "error": {
    "message": "Invalid API key provided",
    "type": "invalid_request_error",
    "code": "invalid_api_key"
  }
}

Segurança e Best Practices

Boas práticas para usar a API OrfeuAI de forma segura.

Proteção de API Keys

Importante: Nunca exponha sua API key no frontend (JavaScript no navegador). Sempre use servidor backend.

Suas API keys devem ser tratadas como senhas:

  • Armazene em variáveis de ambiente (arquivo .env)
  • Nunca faça commit de keys no Git (adicione .env ao .gitignore)
  • Use keys diferentes para desenvolvimento e produção
  • Rotacione keys periodicamente (delete antigas no dashboard)

HTTPS Obrigatório

Todas as requisições devem usar HTTPS (https://api.orfeuai.com). Nunca use HTTP puro.

Rate Limiting

A API tem limites de requisições por minuto (veja seção Rate Limits acima). Implemente retry logic com exponential backoff para lidar com erros 429.

LGPD Compliance

Processamento de dados: ARPA-1 Lite processa em território brasileiro (OrfeuAI). ARPA-1 Mini e Max processam via Groq (infraestrutura internacional).

Você é responsável por:

  • Obter consentimento dos usuários antes de processar dados pessoais
  • Não enviar dados sensíveis (CPF, cartão de crédito, senhas)
  • Implementar políticas de retenção de dados
  • Permitir que usuários solicitem exclusão de dados

Validação de Entrada

Valide e sanitize dados antes de enviar para a API:

  • Limite tamanho de mensagens (use max_tokens)
  • Valide formato de inputs (strings, números)
  • Sanitize outputs antes de exibir no frontend (evite XSS)