Perguntas Frequentes

Perguntas frequentes sobre o IPFS Ninja.

Geral

O que é o IPFS Ninja?

O IPFS Ninja é um serviço gerenciado de fixação em IPFS. Você envia qualquer arquivo através de uma API REST simples, ou fixa CIDs existentes da rede IPFS. Cada arquivo recebe um identificador de conteúdo (CID) permanente e fica acessível através do nosso gateway em ipfs.ninja/ipfs/<CID>.

O ipfs.ninja/ipfs/<CID> serve qualquer CID da rede IPFS?

Não. O gateway apex serve apenas CIDs que tenham sido enviados ou fixados por um usuário do IPFS Ninja. Requisições para CIDs desconhecidos retornam HTTP 410 Gone com um ponteiro para gateways IPFS públicos (ipfs.io, dweb.link). Para servir um CID de terceiros através do nosso gateway, faça primeiro POST /pin dele para sua conta — uma vez fixado, o CID fica acessível tanto na URL apex quanto na do seu gateway dedicado.

Qual é a diferença entre o gateway apex e o gateway dedicado?

Aspecto	Apex ipfs.ninja/ipfs/<CID>	Dedicado <slug>.gw.ipfs.ninja/ipfs/<CID>
Escopo	Compartilhado entre todos os usuários	Apenas seus CIDs
Autenticação	Nenhuma	Token opcional / lista de IPs / lista de origens
SLA	Melhor esforço	SLA completo
Recomendado para	Links casuais	Incorporação em produção (NFT, vídeo, sites)
Limites de taxa	Compartilhado por IP + por CID	Por plano, configurável

Ambos servem conteúdo idêntico. Para tráfego de produção, use o gateway dedicado.

Quais tipos de arquivo são suportados?

Todos os tipos de arquivo são suportados. Objetos e arrays JSON podem ser enviados diretamente. Todos os outros arquivos (imagens, PDFs, HTML, vídeo, áudio, binários) são enviados como conteúdo codificado em base64.

Existe um limite de tamanho de arquivo?

Os uploads individuais são limitados pela capacidade de armazenamento do seu plano. Não há limite de tamanho por arquivo além do seu armazenamento disponível.

Posso fixar conteúdo que já existe no IPFS?

Sim. Use POST /pin com qualquer CID válido. Nosso cluster vai buscar o conteúdo na rede IPFS e fixá-lo na sua conta. Consulte a documentação da API de Fixação para detalhes.

Quanto tempo leva a fixação?

Depende do tamanho do arquivo e de quantos nós IPFS têm o conteúdo. Arquivos pequenos e bem distribuídos são fixados em segundos. Conteúdo grande ou raramente fixado pode levar alguns minutos. O endpoint de fixação retorna imediatamente com status pinning — consulte GET /pin/:cid para verificar o progresso.

O que acontece se um CID não puder ser encontrado?

O status muda para failed. Isso significa que o CID é inválido ou o conteúdo não está mais disponível em nenhum nó IPFS alcançável.

Os dados enviados ao IPFS são públicos?

Sim. Todo conteúdo fixado no IPFS fica publicamente acessível pelo seu CID através de qualquer gateway IPFS. Se você precisa de acesso privado, use um gateway dedicado com o modo de token obrigatório — isso restringe o acesso pelo seu gateway, embora o conteúdo continue disponível na rede IPFS mais ampla.

Por que meus novos CIDs mudaram de Qm... para bafy...?

Novos uploads e fixações retornam CIDv1 moderno (bafk… para conteúdo pequeno de bloco único, bafy… para arquivos e diretórios maiores) conforme o perfil IPIP-0499 unixfs-v1-2025: codificação CIDv1 em base32, blocos de 1 MiB, raw leaves. Isso corresponde ao que ferramentas modernas (Helia, o Kubo mais recente, ipfs-car) produzem para o mesmo conteúdo, então um arquivo enviado através de nós recebe o mesmo CID que qualquer cliente moderno computaria para os mesmos bytes.

CIDs Qm… legados de uploads anteriores continuam totalmente resolvíveis — o gateway, POST /pin, GET /file, IPNS e todos os outros endpoints aceitam ambos os formatos indefinidamente. Nada do que você já tem deixa de funcionar.

Como fixo conteúdo que está em um nó privado / fora da DHT?

POST /pin aceita o parâmetro opcional multiaddresses[] (até 5). Se fornecido, nosso cluster executa ipfs swarm connect <multiaddr> para cada dica antes de rodar a fixação, para que conteúdo em peers que não estão sendo anunciados pela DHT pública (nós privados, ambientes de staging, máquinas locais em VPN) fique acessível. Veja o guia Fixar a partir de um nó IPFS privado.

Meus arquivos permanecem no IPFS se eu cancelar minha conta?

Nós desafixamos seus arquivos dos nossos nós quando você cancela. Se outros nós IPFS tiverem seu conteúdo em cache, ele pode permanecer acessível. Porém, sem fixação ativa, os arquivos serão eventualmente removidos pela coleta de lixo em toda a rede.

Autenticação e API

Como autentico requisições à API?

Passe sua chave de API pelo cabeçalho X-Api-Key. Gere chaves na página de Chaves de API no seu painel.

Existem limites de taxa na API?

Não. O IPFS Ninja não impõe limites de taxa nas requisições à API. Você pode fazer quantas requisições precisar em qualquer plano.

As chaves de API expiram?

Não. As chaves de API são válidas até que você as exclua. Você pode criar múltiplas chaves e revogá-las individualmente.

Qual é a diferença entre chaves de API e tokens de gateway?

Chaves de API (bws_) têm acesso total — enviar, excluir, listar arquivos. Tokens de gateway (gwt_) são somente leitura e só conseguem acessar arquivos através do seu gateway dedicado. Tokens de gateway são seguros para incorporar em aplicações frontend.

Gateways Dedicados

O que é um gateway dedicado?

Um gateway IPFS privado no seu próprio subdomínio (ex.: abc123.gw.ipfs.ninja) que serve apenas arquivos fixados na sua conta. Diferente do gateway público, ele não resolve CIDs de outros usuários.

Quais planos incluem um gateway dedicado?

Gateways dedicados estão disponíveis em todos os planos pagos (Bodhi $5/mês, Karma $19/mês, Nirvana $59/mês). A cota mensal de largura de banda de cada plano cobre o tráfego tanto do gateway apex quanto do dedicado. Veja "Existem taxas de largura de banda?" abaixo para as cotas de cada plano.

Posso restringir quem acessa meu gateway?

Sim. Você pode habilitar o modo de token obrigatório (exige um token gwt_ em cada requisição) e/ou configurar uma lista de IPs permitidos (até 100 endereços).

Posso restringir meu gateway por origem/domínio?

Sim. Configure allowedOrigins nas suas configurações de gateway com uma lista de origens HTTPS. Apenas requisições de navegador vindas dessas origens serão permitidas. Requisições que não vêm de navegador (sem cabeçalho Origin) passam sem restrição. Uma lista vazia permite todas as origens.

O que são tokens de upload assinados?

Tokens de upload assinados são credenciais com tempo limitado para uploads do lado do cliente. Você os gera no seu servidor usando POST /upload/signed-url e os passa para navegadores ou aplicativos móveis. O cliente se autentica com Authorization: Signed <token> em vez de expor sua chave de API. Cada token rastreia o uso e expira automaticamente. Consulte a documentação de Tokens Assinados para detalhes.

Posso otimizar imagens servidas pelo IPFS?

Sim. Use GET /image/:cid com parâmetros de consulta como w, h, format e quality para redimensionar, converter e comprimir imagens em tempo real. As respostas são armazenadas em cache com base no CID endereçado por conteúdo. Isso funciona em todos os planos. Veja Otimização de Imagens.

Posso anexar metadados aos arquivos?

Sim. Inclua um objeto metadata com até 10 pares chave-valor ao enviar via POST /upload/new ou ao fixar via POST /pin. Os metadados são retornados nas listagens de arquivos e no endpoint de detalhes do arquivo. Consulte a documentação de Arquivos e Fixação.

Faturamento e Planos

Existe um plano gratuito?

Sim. O plano Dharma é gratuito para sempre — 1 GB de armazenamento, requisições ilimitadas à API, sem necessidade de cartão de crédito.

Existem taxas de largura de banda?

Nenhuma taxa de largura de banda medida em nenhum plano. Cada plano inclui uma cota mensal de largura de banda do gateway que é um limite rígido — seu conteúdo para de ser servido nos gateways apex e dedicado assim que a cota é atingida, e volta a funcionar no dia 1º do mês seguinte ou após um upgrade:

Plano	Largura de banda mensal
Dharma	2 GB
Bodhi	20 GB
Karma	100 GB
Nirvana	500 GB

Você receberá e-mails de aviso ao atingir 80% e 100% da sua cota.

O armazenamento reseta?

O armazenamento não reseta. Seu plano inclui uma capacidade total de armazenamento (Dharma 1 GB / Bodhi 10 GB / Karma 100 GB / Nirvana 1 TB). Para liberar espaço, exclua arquivos que você não precisa mais. Fazer upgrade do seu plano aumenta sua capacidade total.

Posso cancelar a qualquer momento?

Sim. Cancele sua assinatura pelo portal de faturamento — sem fidelidade. Sua conta reverte para o nível gratuito, e os arquivos já fixados continuam acessíveis.

O que acontece com meus arquivos se eu fizer downgrade?

Seus arquivos continuam fixados no IPFS, mas você não poderá enviar mais arquivos se o seu uso atual exceder o limite de armazenamento do novo plano. Exclua arquivos para voltar a ficar dentro do limite.

Segurança

Meus dados são criptografados?

Todos os dados são criptografados em trânsito via TLS/HTTPS. A autenticação usa tokens JWT (Cognito) e chaves de API armazenadas com segurança. O conteúdo dos arquivos no IPFS não é criptografado em repouso — o IPFS é uma rede pública por natureza.

É seguro usar chaves de API no meu código do lado do servidor?

Sim. As chaves de API são projetadas para uso no lado do servidor. Nunca as exponha em código do lado do cliente. Para acesso a arquivos no lado do cliente, use tokens de gateway (gwt_), que são somente leitura.

Suporte

Como obtenho ajuda?

Envie um e-mail para info@ipfs.ninja ou consulte a documentação da Referência da API.

Existe um SLA?

Buscamos alta disponibilidade, mas não oferecemos um SLA formal no momento. O serviço é fornecido "como está".