Nebula Developer

Documentação do Desenvolvedor

Tudo para integrar a Nebula API: guia rápido, limites, cache e referência interativa. Sem autenticação — gratuita para começar agora.

Início Rápido → Testar no Swagger

📘

Introdução

Bem-vindo ao Developer Hub da Nebula API. Aqui você encontra o mapa completo para usar nossos endpoints de Minecraft, Roblox e Discord em suas aplicações.

A API é aberta, sem chave. Recomendamos começar pelo Início Rápido (5 min) e depois explorar o Swagger interativo onde cada endpoint tem Try it out.

💡

Dica: adicione http://nebulaapi.squareweb.app/api/minecraft/server/java/mc.hypixel.net/status-text no navegador para testar sem código.

⚡

Início Rápido

Faça sua primeira chamada à API em menos de 5 minutos. Gratuita e sem autenticação — sem criar conta ou gerar tokens.

Primeira requisição

Vamos consultar o status de um servidor Minecraft. É um endpoint simples que retorna texto puro:

curl -s http://nebulaapi.squareweb.app/api/minecraft/server/java/mc.hypixel.net/status-text

Resposta: Online • mc.hypixel.net (java) • 1000/200000

import requests

url = "http://nebulaapi.squareweb.app/api/minecraft/server/java/mc.hypixel.net/status-text"
response = requests.get(url)
print(response.text)

const url = "http://nebulaapi.squareweb.app/api/minecraft/server/java/mc.hypixel.net/status-text";

fetch(url)
  .then(res => res.text())
  .then(data => console.log(data));

💡

Consulte os Limites de Uso para entender os rate limits aplicados.

Atalhos

🧪 Swagger UI

Teste todos os endpoints no navegador

📚 Índice de Rotas

Lista dinâmica por área (Minecraft/Outros)

⛏️ Render Minecraft

head/body/skin com crops full/bust/face

📊 Status & Widget

Texto + PNG 1440×360 com cor do ícone e dark/rounded

🎨 Composição

POST com até 10 nicks/URLs → PNG

⚡ Início Rápido

cURL / Python / JavaScript em PT-BR

Limites de Uso

Para estabilidade, aplicamos rate limit por IP. Plano gratuito já cobre a maioria dos casos.

Categoria	Endpoint	Limite	Janela
🌐 Global	`/api/*`	240 req	por minuto / IP
🔗 Discord Webhook	`POST /api/discord/webhook/*`	10 req	por minuto / IP

Limite global aplica-se a todas as rotas; webhook tem limite adicional mais restritivo. Configurável via RATE_LIMIT_MAX / WEBHOOK_PROXY_RATE_LIMIT_MAX.

💡 Os limites são aplicados por IP de origem. Se você usar proxy ou VPN, o limite é compartilhado com outros usuários do mesmo IP.

Headers de Rate Limit

X-RateLimit-Limit

Número máximo de requisições permitidas na janela atual.

X-RateLimit-Remaining

Número de requisições restantes na janela atual.

X-RateLimit-Reset

Timestamp Unix indicando quando a janela será resetada.

Retry-After

Presente apenas quando o limite é excedido (429). Indica segundos para aguardar.

Exemplo de Resposta

HTTP/1.1 200 OK
Content-Type: application/json
X-RateLimit-Limit: 240
X-RateLimit-Remaining: 237
X-RateLimit-Reset: 1702656000
Cache-Control: public, max-age=900
ETag: "a1b2c3d4e5f6"
X-Cache: HIT

Dica: envie If-None-Match: "a1b2c3d4e5f6" para receber 304 Not Modified e economizar cota — renders e widgets suportam ETag + Cache-Control.

Quando o Limite é Excedido

Se você exceder o limite, receberá um erro 429 Too Many Requests:

HTTP/1.1 429 Too Many Requests
Content-Type: application/json
Retry-After: 45

{"detail": "Rate limit exceeded. Retry after 45 seconds."}

Boas Práticas

✅ Implemente retry com backoff exponencial
✅ Monitore os headers X-RateLimit-*
✅ Cache respostas quando possível
✅ Distribua requisições ao longo do tempo

Cache & ETag

Renders e widgets retornam Cache-Control: public, max-age=900 e ETag.

curl -I http://nebulaapi.squareweb.app/api/minecraft/render/head/Notch/full
# → ETag: "abc123"  Cache-Control: public, max-age=900

curl -H "If-None-Match: \"abc123\"" http://nebulaapi.squareweb.app/api/minecraft/render/head/Notch/full
# → 304 Not Modified (não conta pro rate limit de origem)

Use X-Cache: HIT/MISS para saber se veio do cache da Nebula.

Erros

Códigos HTTP padrão. A API não usa autenticação — não há 401.

Código	Significado
`200 OK`	Sucesso
`304 Not Modified`	Cache válido (If-None-Match coincidiu)
`400 Bad Request`	Parâmetro inválido (ex.: render_type/crop)
`404 Not Found`	Recurso não encontrado
`429 Too Many Requests`	Rate limit excedido — aguarde `Retry-After`
`500` / `502`	Erro interno / upstream fora do ar

🔍

Todas as páginas de docs também estão em /api/templates com links diretos para testar.