Bem-vindo à SnapID API v2.0

Armazenamento de arquivos: simples, rápido e seguro. A SnapID fornece uma API RESTful para upload, gerenciamento e entrega de arquivos (imagens, vídeos, áudios e documentos) com alta disponibilidade em Nuvem (HA) e suporte a envios de até 10 GB por arquivo.

🚀 Quickstart Guide

Comece a usar a API em menos de 2 minutos.

Passo 1: Obtenha sua API Key

Faça uma requisição de registro para gerar sua chave gratuitamente. Ela será exibida na resposta e enviada para seu e-mail.

import requests

response = requests.post(
    "https://snapid.com.br/api/register",
    json={"email": "dev@exemplo.com", "name": "Dev", "whatsapp": "11999999999"}
)
print(response.json())

const response = await fetch("https://snapid.com.br/api/register", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    email: "dev@exemplo.com", 
    name: "Dev", 
    whatsapp: "11999999999"
  })
});
const data = await response.json();
console.log(data);

curl -X POST https://snapid.com.br/api/register \
  -H "Content-Type: application/json" \
  -d '{"email": "dev@exemplo.com", "name": "Dev", "whatsapp": "11999999999"}'

Passo 2: Faça seu primeiro Upload

Use a api_key recebida no passo anterior para enviar um arquivo.

import requests

api_key = "sk_suachaveaqui"
with open("imagem.jpg", "rb") as file:
    response = requests.post(
        f"https://snapid.com.br/upload?key={api_key}",
        files={"file": file}
    )
print(response.json())

const apiKey = "sk_suachaveaqui";
const formData = new FormData();
// Supondo que 'fileInput' seja um elemento 
formData.append("file", fileInput.files[0]);

const response = await fetch(`https://snapid.com.br/upload?key=${apiKey}`, {
  method: "POST",
  body: formData
});
const result = await response.json();
console.log(result.data.url); // URL pública do arquivo

curl -X POST \
  -F "file=@/caminho/para/imagem.jpg" \
  "https://snapid.com.br/upload?key=sk_suachaveaqui"

Autenticação

O acesso às rotas protegidas requer uma API Key. Você pode passá-la via ?key=YOUR_KEY (query string), via Header X-API-Key: YOUR_KEY ou no Body JSON.

POST /api/recover Público

Recuperar API Key

Reenvia a chave de acesso para o e-mail cadastrado.

Body (JSON)

Campo	Tipo	Status
`email`	string	Required

import requests
requests.post("https://snapid.com.br/api/recover", json={"email": "dev@exemplo.com"})

curl -X POST https://snapid.com.br/api/recover \
  -H "Content-Type: application/json" \
  -d '{"email": "dev@exemplo.com"}'

Exemplo Prático: CRUD

Veja como integrar as 4 operações fundamentais (Create, Read, Update, Delete) em um único fluxo de aplicação com a SnapID API.

Ciclo de Vida de um Arquivo

Neste exemplo prático, fazemos o upload de um arquivo, consultamos os dados dele, atualizamos sua validade (ou metadados) e por fim o excluímos de forma sequencial.

import requests

BASE_URL = "https://snapid.com.br/api/files"
KEY = "sk_suachaveaqui"

# 1. CREATE (Upload)
with open("foto.jpg", "rb") as f:
    res = requests.post("https://snapid.com.br/upload", params={"key": KEY}, files={"file": f})
file_id = res.json()["data"]["id"]
print(f"Criado: {file_id}")

# 2. READ (Get Info)
info = requests.get(f"{BASE_URL}/{file_id}", params={"key": KEY})
print("Lido:", info.json()["data"]["url"])

# 3. UPDATE (Metadata)
update = requests.put(f"{BASE_URL}/{file_id}", params={"key": KEY}, json={"expiration": 3600})
print("Atualizado:", update.status_code)

# 4. DELETE
delete = requests.delete(f"{BASE_URL}/{file_id}", params={"key": KEY})
print("Deletado:", delete.status_code)

const BASE_URL = "https://snapid.com.br/api/files";
const KEY = "sk_suachaveaqui";

// 1. CREATE (Upload)
const formData = new FormData();
formData.append("file", fileInput.files[0]);
let res = await fetch(`https://snapid.com.br/upload?key=${KEY}`, { method: "POST", body: formData });
let data = await res.json();
const fileId = data.data.id;
console.log(`Criado: ${fileId}`);

// 2. READ (Get Info)
res = await fetch(`${BASE_URL}/${fileId}?key=${KEY}`);
data = await res.json();
console.log(`Lido: ${data.data.url}`);

// 3. UPDATE (Metadata)
res = await fetch(`${BASE_URL}/${fileId}?key=${KEY}`, {
  method: "PUT",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ expiration: 3600 })
});
console.log(`Atualizado: ${res.status}`);

// 4. DELETE
res = await fetch(`${BASE_URL}/${fileId}?key=${KEY}`, { method: "DELETE" });
console.log(`Deletado: ${res.status}`);

Arquivos

GET /api/files 🔑 Auth

Listar Arquivos

Retorna uma lista paginada dos seus arquivos enviados.

Query Params

Nome	Tipo	Descrição
`key`	string	Required - Sua API Key
`category`	string	Optional - image, video, audio, document
`limit`	number	Optional - Padrão 50
`offset`	number	Optional - Padrão 0

import requests
res = requests.get("https://snapid.com.br/api/files", params={"key": "sk_xyz", "category": "image", "limit": 10})
print(res.json())

const res = await fetch("https://snapid.com.br/api/files?key=sk_xyz&category=image&limit=10");
console.log(await res.json());

curl "https://snapid.com.br/api/files?key=sk_xyz&category=image&limit=10"

POST /api/upload/resumable/... 🔑 Auth

Resumable Uploads (Arquivos até 10GB)

Para o envio de arquivos muito grandes, recomendamos utilizar a nova API Direct-to-GCS. O fluxo contorna o servidor Node.js e consiste em três etapas para garantir estabilidade máxima e altíssima performance.

1. Inicialização (`/api/upload/resumable/init`)

Valida sua chave, checa sua cota de armazenamento e devolve uma URL assinada exclusiva do Storage.

// Request Body
{
  "filename": "video_gigante.mp4",
  "mime_type": "video/mp4",
  "file_size": 2147483648
}

2. Envio (Upload Direto - Navegador/App)

O cliente envia os bytes (fatiados ou não) via requisição PUT diretamente para a upload_url recebida no passo 1. O servidor Node.js nem sequer enxerga esse tráfego, evitando gargalos.

3. Finalização (`/api/upload/resumable/finalize`)

Confirma a conclusão, audita se os bytes realmente chegaram no GCS e consolida os dados finais no banco de dados.

// Request Body
{
  "uuid": "retornado_no_passo_1",
  "storage_path": "retornado_no_passo_1",
  "filename": "video_gigante.mp4",
  "mime_type": "video/mp4",
  "file_size": 2147483648
}

GET /file/:uuid.ext Público

Acessar / Visualizar

Rota pública de acesso direto ao arquivo. Pode ser usada em tags <img src="..."> ou <video src="...">.

<img src="https://snapid.com.br/file/a1b2c3d4.jpg" alt="Foto" />

DELETE /api/files/:uuid 🔑 Auth

Excluir Arquivo

Exclui o arquivo permanentemente do storage. Só o proprietário pode realizar esta ação.

curl -X DELETE "https://snapid.com.br/api/files/a1b2c3d4?key=sk_xyz"

Planos & Assinaturas

GET /api/plans Público

Listar Planos

Retorna os planos disponíveis, limites de armazenamento e preços.

curl https://snapid.com.br/api/plans

POST /api/subscribe 🔑 Auth

Assinar um Plano

Ativa a assinatura e retorna um link de checkout do Mercado Pago.

curl -X POST "https://snapid.com.br/api/subscribe?key=sk_xyz" \
  -H "Content-Type: application/json" \
  -d '{"plan_id": 2, "billing_cycle": "monthly"}'

Uso & Limites

GET /api/usage 🔑 Auth

Consultar Armazenamento

Retorna dados analíticos sobre seu armazenamento e limite do plano.

curl "https://snapid.com.br/api/usage?key=sk_xyz"

🤖 Integração Avançada: n8n

O SnapID é ideal para servir como backend de armazenamento temporário ou permanente para automações low-code/no-code no n8n. Um uso comum é receber imagens de um usuário, hospedá-las na SnapID, e enviar as URLs públicas para um modelo de Inteligência Artificial (ex: fal.ai, Grok) para gerar vídeos.

Gerador de Vídeo com IA

O fluxo de automação abaixo demonstra o processo:

Um formulário web envia múltiplas imagens para o Webhook do n8n via multipart/form-data.
O nó "Upload to SnapID" itera sobre os binários e faz requisições POST /upload para o SnapID.
O n8n coleta as URLs geradas (data.public_url) da resposta.
Um nó HTTP request envia essas URLs para a API de geração de vídeo.
Um loop aguarda a finalização e retorna o vídeo para o usuário.

Configuração do Nó HTTP Request (Upload para SnapID) no n8n:

⬇️ Baixar JSON Completo

{
  "nodes": [
    {
      "parameters": {
        "method": "POST",
        "url": "https://snapid.com.br/upload",
        "sendQuery": true,
        "queryParameters": {
          "parameters": [
            {
              "name": "key",
              "value": "SUA-KEY-AQUI"
            }
          ]
        },
        "sendBody": true,
        "contentType": "multipart-form-data",
        "bodyParameters": {
          "parameters": [
            {
              "name": "expiration",
              "value": "86400"
            },
            {
              "parameterType": "formBinaryData",
              "name": "file",
              "inputDataFieldName": "files"
            }
          ]
        },
        "options": {}
      },
      "name": "Upload to SnapID",
      "type": "n8n-nodes-base.httpRequest",
      "typeVersion": 4,
      "position": [
        -7744,
        -1216
      ],
      "id": "ac0850e2-4935-4776-8749-11e69f065fc6"
    }
  ],
  "connections": {
    "Upload to SnapID": {
      "main": [
        []
      ]
    }
  },
  "pinData": {},
  "meta": {
    "templateCredsSetupCompleted": true,
    "instanceId": "ea88013e5b7309b0c438c7b5879b0b0d92d2795380298c2786b7759d6ebb26dd"
  }
}

💻 Integração Web/Social

🖼️ Imagens Responsivas

<picture>
  <source srcset="https://snapid.com.br/file/UUID.webp" type="image/webp" />
  <img src="https://snapid.com.br/file/UUID.jpg" alt="Foto responsiva" style="max-width: 100%;" />
</picture>

🎬 Player de Vídeo

<video src="https://snapid.com.br/file/UUID.mp4" 
       controls poster="https://snapid.com.br/file/THUMB.jpg" 
       style="width: 100%; border-radius: 8px;">
</video>

🌐 Open Graph (Preview para Redes Sociais)

Adicione no <head> do seu site para preview no WhatsApp/Facebook/X.

<meta property="og:title" content="Meu Título" />
<meta property="og:description" content="Descrição" />
<meta property="og:image" content="https://snapid.com.br/file/UUID.jpg" />
<meta property="og:url" content="https://meusite.com" />
<meta name="twitter:card" content="summary_large_image" />

Códigos de Erro

HTTP Status	Código JSON	Descrição
`400`	`BAD_REQUEST`	Parâmetros faltando ou inválidos.
`401`	`API_KEY_MISSING`	API Key ausente.
`401`	`API_KEY_INVALID`	API Key inválida.
`403`	`QUOTA_EXCEEDED`	Limite de armazenamento atingido.
`404`	`NOT_FOUND`	Arquivo ou recurso não encontrado.