Perguntas Frequentes

Perguntas frequentes sobre o IPFS Ninja.

Geral

O que é IPFS Ninja?

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

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, video, audio, binarios) 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 ha limite de tamanho por arquivo alem 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 buscara o conteúdo na rede IPFS é o fixara 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 possuem 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álidoinválido ou o conteúdo não está mais disponível em nenhum no IPFS alcançável.

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

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

Meus arquivos permanecem no IPFS se eu cancelar minha conta?

Nos desfixamos seus arquivos dos nossos nós quando você cancela. Se outros nós IPFS armazenaram em cache seu conteúdo, ele pode permanecer acessível. Porem, sem fixação ativa, os arquivos serão eventualmente removidos pela coleta de lixo na rede.

Autenticação e API

Como autentico requisições a API?

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

Existem limites de taxa na API?

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

As chaves API expiram?

Não. As chaves API são validas até que você as exclua. Você pode criar múltiplas chaves e revoga-las individualmente.

Qual é a diferenca entre chaves API e tokens de gateway?

As chaves API (bws_) tem acesso total — upload, exclusao, listagem de arquivos. Os tokens de gateway (gwt_) são somente leitura e só podem acessar arquivos pelo seu 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 seu próprio subdominio (ex.: abc123.gw.ipfs.ninja) que serve apenas arquivos fixados na sua conta. Diferente do gateway público, não resolvera CIDs de outros usuarios.

Quais planos incluem um gateway dedicado?

Gateways dedicados estão disponíveis no plano Nirvana ($29/mes), que inclui 50 GB/mes de largura de banda do gateway.

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/dominio?

Sim. Configure allowedOrigins nas configurações do seu gateway com uma lista de origens HTTPS. Apenas requisições de navegador dessas origens serão permitidas. Requisições que não são 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 API. Cada token rastreia o uso e expira automaticamente. Consulte a documentação de Tokens Assinados para detalhes.

Posso otimizar imagens servidas do 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. Consulte Otimização de Imagens.

Posso anexar metadados aos arquivos?

Sim. Inclua um objeto metadata com até 10 pares chave-valor ao fazer upload 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 é gratuitogratuito para sempre — 1 GB de armazenamento, requisições API ilimitadas, sem necessidade de cartao de crédito.

Existem taxas de largura de banda?

Sem taxas de largura de banda nas requisições API para qualquer plano. A largura de banda do gateway dedicado (plano Nirvana) inclui 50 GB/mes. Quando o limite é atingatingido, as requisições do gateway são bloqueadas até o próximo mes.

O armazenamento reseta?

O armazenamento não reseta. Seu plano inclui uma capacidade total de armazenamento (1 GB / 10 GB / 100 GB). 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 compromisso. Sua conta reverte para o nível gratuito, e os arquivos fixados existentes permanecem acessíveis.

O que acontece com meus arquivos se eu fizer downgrade?

Seus arquivos permanecem fixados no IPFS, mas você não poderá fazer mais uploads se 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 transito via TLS/HTTPS. A autenticação usa tokens JWT (Cognito) e chaves API armazenadas com segurança. O conteúdo dos arquivos no IPFS não e criptografado em repouso — o IPFS é uma rede pública por design.

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

Sim. As chaves API são projetadas para uso do lado do servidor. Nunca as exponha em código do lado do cliente. Para acesso a arquivos do 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?

Nos nós esforçamos para alta disponibilidade, mas não oferecemos um SLA formal neste momento. O serviço é fornecidfornecido "como está".