Perguntas Frequentes

Perguntas frequentes sobre o IPFS Ninja.

Geral

O que é o IPFS Ninja?

O IPFS Ninja é um serviço gerido de fixação em IPFS. Carregas qualquer ficheiro através de uma API REST simples, ou fixas CIDs existentes da rede IPFS. Cada ficheiro recebe um identificador de conteúdo permanente (CID) 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 só serve CIDs que tenham sido carregados ou fixados por um utilizador do IPFS Ninja. Os pedidos para CIDs desconhecidos devolvem HTTP 410 Gone com um apontador para gateways IPFS públicos (ipfs.io, dweb.link). Para servir um CID de terceiros através do nosso gateway, faz primeiro POST /pin para a tua conta — uma vez fixado, o CID fica acessível tanto no gateway apex como no teu gateway dedicado.

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

Aspeto	Apex ipfs.ninja/ipfs/<CID>	Dedicado <slug>.gw.ipfs.ninja/ipfs/<CID>
Âmbito	Partilhado entre todos os utilizadores	Apenas os teus CIDs
Autenticação	Nenhuma	Token opcional / lista de IPs / lista de origens
SLA	Melhor esforço	SLA completo
Recomendado para	Ligações casuais	Incorporação em produção (NFT, vídeo, sites)
Limites de taxa	Partilhado por IP + por CID	Por plano, configurável

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

Que tipos de ficheiro são suportados?

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

Existe um limite de tamanho de ficheiro?

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

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

Sim. Usa POST /pin com qualquer CID válido. O nosso cluster vai obter o conteúdo na rede IPFS e fixá-lo na tua conta. Consulta a documentação da API de Fixação para detalhes.

Quanto tempo demora a fixação?

Depende do tamanho do ficheiro e de quantos nós IPFS têm o conteúdo. Ficheiros pequenos e bem distribuídos ficam fixados em segundos. Conteúdo grande ou raramente fixado pode demorar alguns minutos. O endpoint de fixação devolve resposta imediatamente com o estado pinning — consulta GET /pin/:cid para verificar o progresso.

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

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

Os dados carregados para o IPFS são públicos?

Sim. Todo o conteúdo fixado no IPFS é publicamente acessível através do seu CID em qualquer gateway IPFS. Se precisares de acesso privado, usa um gateway dedicado com modo de token obrigatório — isto restringe o acesso através do teu gateway, embora o conteúdo continue disponível na rede IPFS mais ampla.

Porque é que os meus novos CIDs mudaram de Qm... para bafy...?

Os novos carregamentos e fixações devolvem CIDv1 moderno (bafk… para conteúdo pequeno de bloco único, bafy… para ficheiros e diretórios maiores) segundo o perfil IPIP-0499 unixfs-v1-2025: codificação CIDv1 em base32, blocos de 1 MiB, raw leaves. Isto corresponde ao que as ferramentas modernas (Helia, o Kubo mais recente, ipfs-car) produzem para o mesmo conteúdo, pelo que um ficheiro carregado através de nós obtém o mesmo CID que qualquer cliente moderno calcularia para os mesmos bytes.

Os CIDs legados Qm… de carregamentos anteriores continuam totalmente resolúveis — o gateway, POST /pin, GET /file, o IPNS, e todos os outros endpoints aceitam ambos os formatos indefinidamente. Nada do que já tens deixa de funcionar.

Como fixo conteúdo que vive num nó privado / fora da DHT?

POST /pin aceita multiaddresses[] opcionais (até 5). Se fornecidos, o nosso cluster faz ipfs swarm connect <multiaddr> para cada pista antes de a fixação começar, para que o conteúdo em peers que não estão a anunciar-se na DHT pública (nós privados, ambientes de staging, máquinas locais em VPN) fique acessível. Consulta o guia Fixar a partir de um nó IPFS privado.

Os meus ficheiros permanecem no IPFS se cancelar a minha conta?

Desfixamos os teus ficheiros dos nossos nós quando cancelas. Se outros nós IPFS tiverem o teu conteúdo em cache, pode continuar acessível. No entanto, sem fixação ativa, os ficheiros acabarão por ser removidos pela recolha de lixo em toda a rede.

Autenticação e API

Como autentico pedidos à API?

Passa a tua chave de API através do cabeçalho X-Api-Key. Gera chaves na página Chaves de API do teu painel.

Existem limites de taxa na API?

Não. O IPFS Ninja não impõe limites de taxa nos pedidos à API. Podes fazer quantos pedidos precisares em qualquer plano.

As chaves de API expiram?

Não. As chaves de API são válidas até as eliminares. Podes criar várias chaves e revogá-las individualmente.

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

As chaves de API (bws_) têm acesso total — carregar, eliminar, listar ficheiros. Os tokens de gateway (gwt_) são só de leitura e só conseguem aceder a ficheiros através do teu gateway dedicado. Os tokens de gateway são seguros para incorporar em aplicações frontend.

Gateways Dedicados

O que é um gateway dedicado?

Um gateway IPFS privado no teu próprio subdomínio (ex.: abc123.gw.ipfs.ninja) que só serve ficheiros fixados na tua conta. Ao contrário do gateway público, não vai resolver CIDs de outros utilizadores.

Que planos incluem um gateway dedicado?

Os gateways dedicados estão disponíveis em todos os planos pagos (Bodhi 5 $/mês, Karma 19 $/mês, Nirvana 59 $/mês). A quota mensal de largura de banda de cada plano cobre o tráfego tanto do gateway apex como do dedicado. Consulta "Há taxas de largura de banda?" abaixo para as quotas por plano.

Posso restringir quem acede ao meu gateway?

Sim. Podes ativar o modo de token obrigatório (exige um token gwt_ em cada pedido) e/ou definir uma lista de IPs permitidos (até 100 endereços).

Posso restringir o meu gateway por origem/domínio?

Sim. Configura allowedOrigins nas definições do teu gateway com uma lista de origens HTTPS. Só os pedidos de browser dessas origens serão permitidos. Pedidos que não sejam de browser (sem cabeçalho Origin) passam sem restrição. Uma lista vazia permite todas as origens.

O que são tokens de carregamento assinados?

Os tokens de carregamento assinados são credenciais com tempo limitado para carregamentos do lado do cliente. Geras-os no teu servidor usando POST /upload/signed-url e passas-os para browsers ou aplicações móveis. O cliente autentica-se com Authorization: Signed <token> em vez de expor a tua chave de API. Cada token regista a utilização e expira automaticamente. Consulta a documentação de Tokens Assinados para detalhes.

Posso otimizar imagens servidas a partir do IPFS?

Sim. Usa 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 guardadas em cache com base no CID endereçado por conteúdo. Isto funciona em todos os planos. Consulta Otimização de Imagens.

Posso anexar metadados a ficheiros?

Sim. Inclui um objeto metadata com até 10 pares chave-valor ao carregar via POST /upload/new ou ao fixar via POST /pin. Os metadados são devolvidos nas listagens de ficheiros e no endpoint de detalhes do ficheiro. Consulta a documentação de Ficheiros e Fixação.

Faturação e Planos

Existe um plano gratuito?

Sim. O plano Dharma é gratuito para sempre — 1 GB de armazenamento, pedidos de API ilimitados, sem necessidade de cartão de crédito.

Há taxas de largura de banda?

Não há taxas de largura de banda medida em nenhum plano. Cada plano inclui uma quota mensal de largura de banda de gateway que é um limite rígido — o teu conteúdo deixa de ser servido nos gateways apex e dedicado assim que a quota é atingida, e retoma 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

Vais receber e-mails de aviso aos 80% e aos 100% da tua quota.

O armazenamento reinicia?

O armazenamento não reinicia. O teu plano inclui uma capacidade total de armazenamento (Dharma 1 GB / Bodhi 10 GB / Karma 100 GB / Nirvana 1 TB). Para libertares espaço, elimina ficheiros de que já não precisas. Fazer upgrade do teu plano aumenta a tua capacidade total.

Posso cancelar a qualquer momento?

Sim. Cancela a tua subscrição através do portal de faturação — sem fidelização. A tua conta reverte para o nível gratuito, e os ficheiros já fixados continuam acessíveis.

O que acontece aos meus ficheiros se eu fizer downgrade?

Os teus ficheiros continuam fixados no IPFS, mas não podes carregar mais se a tua utilização atual exceder o limite de armazenamento do novo plano. Elimina ficheiros para voltares a ficar dentro do limite.

Segurança

Os meus dados estão encriptados?

Todos os dados são encriptados em trânsito via TLS/HTTPS. A autenticação usa tokens JWT (Cognito) e chaves de API guardadas com segurança. O conteúdo dos ficheiros no IPFS não está encriptado 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 concebidas para uso do lado do servidor. Nunca as exponhas em código do lado do cliente. Para acesso a ficheiros do lado do cliente, usa tokens de gateway (gwt_), que são só de leitura.

Suporte

Como obtenho ajuda?

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

Existe um SLA?

Esforçamo-nos por uma elevada disponibilidade, mas não oferecemos atualmente um SLA formal. O serviço é fornecido "tal como está".