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.
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:
- Acesse https://dashboard.orfeuai.com
- Faça login ou crie uma conta
- Vá em Configurações → API Keys
- Clique em Criar Nova API Key
- Copie a key (ela só será mostrada uma vez)
Usando a API Key
Inclua a key no header Authorization de todas as requisições:
Authorization: Bearer sk-orfeu-xxxxxxxxxxxxxxxxxx
Quick Start
Python (Recomendado)
Instale o SDK do OpenAI e configure para usar a base URL da OrfeuAI:
pip install openai
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
npm install openai
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
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
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
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
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
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ística | ARPA-1 Lite | ARPA-1 Mini | ARPA-1 Max |
|---|---|---|---|
| Backend | Qwen3 | Llama 4 Scout | GPT-OSS |
| Janela de Contexto | 32k tokens | 128k tokens | 128k tokens |
| Capacidade | Texto apenas | Texto + Imagens | Texto apenas (Reasoning) |
| Velocidade | Rápida | Muito rápida | Rápida |
| Infraestrutura | OrfeuAI | Groq | Groq |
| 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 |
| Custo | R$ 2,00/M in • R$ 4,00/M out | R$ 3,00/M in • R$ 6,00/M out | R$ 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ívelModelo econômico e rápido. Chat geral, análise de texto.
ARPA-1 Mini
DisponívelModelo balanceado multimodal. Análise avançada de imagens e documentos.
ARPA-1 Max
DisponívelModelo avançado com reasoning. Tarefas complexas, geração de código, análise lógica.
Chat Completions
Endpoint principal. Formato OpenAI.
Corpo da Requisição
{
"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)
{
"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 único da requisição. Formato: chatcmpl-[hash]
Tipo do objeto. Sempre chat.completion para requests não-streaming.
Timestamp Unix (segundos desde 1970-01-01).
Array com respostas geradas. Cada choice contém index, message e finish_reason.
Estatísticas de tokens. Inclui prompt_tokens, completion_tokens e total_tokens.
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
ID do modelo: arpa-1-lite, arpa-1-mini, ou arpa-1-max
Array de mensagens com role (system/user/assistant) e content
Aleatoriedade (0-2). Padrão: 0.7. Baixo = determinístico, alto = criativo.
Limite de tokens na resposta. Controla custo.
Se true, retorna tokens em tempo real (SSE). Padrão: false.
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
# 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
)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.
# 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.
StreamingEm Manutenção
Tokens em tempo real. Melhor UX em chats. Disponível em todos os modelos (ARPA-1 Lite, Mini e Max).
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
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ódigo | Tipo | Descrição | Solução |
|---|---|---|---|
| 400 | invalid_request_error | Parâmetros inválidos ou faltando | Verifique o corpo da requisição |
| 401 | authentication_error | API key ausente ou inválida | Verifique header Authorization |
| 402 | insufficient_credits | Créditos insuficientes | Adicione créditos no dashboard |
| 429 | rate_limit_error | Rate limit excedido | Aguarde ou faça upgrade do plano |
| 500 | server_error | Erro interno do servidor | Tente novamente em alguns segundos |
| 503 | service_unavailable | Serviço temporariamente indisponível | Aguarde manutenção programada |
Exemplos de Respostas de Erro
{
"error": {
"message": "Incorrect API key provided: sk-orfeu-****xyz",
"type": "invalid_request_error",
"param": null,
"code": "invalid_api_key"
}
}Tratamento de Erros (Python)
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.
| Plano | RPM | TPM | RPD |
|---|---|---|---|
| Free | 10 req/min | 100k tokens/min | 500 req/dia |
| Pro | 100 req/min | 1M tokens/min | 5k req/dia |
| Enterprise | Custom | Custom | Custom |
Headers de Resposta
Headers de rate limit em toda resposta:
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
Códigos de Erro HTTP
400 Bad RequestCausa: 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 UnauthorizedCausa: 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 RequiredCausa: Créditos insuficientes na conta.
Solução: Adicione créditos via dashboard ou Stripe.
429 Too Many RequestsCausa: Rate limit excedido (muito requisições por minuto).
Solução: Aguarde 60 segundos ou implemente backoff exponencial.
500 Internal Server ErrorCausa: 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 UnavailableCausa: 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.
# 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 200Erro: 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.
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álidoResposta 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.
# 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
{
"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
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
.envao.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)