Como faço para baixar imagens via API?

Esclarecimento importante: A API não permite "baixar" no sentido tradicional. Em vez disso, ela fornece URLs permanentes para conteúdo otimizado para a web que sua aplicação entrega aos usuários finais. Isso é regido pelo nosso Contrato de Licença da API.

Você NÃO baixa arquivos

A API da Cathopic funciona de forma fundamentalmente diferente dos downloads tradicionais:

• Sem transferência de arquivos: você nunca recebe nem armazena os arquivos reais de imagem/vídeo

• Acesso baseado em URL: a API fornece URLs que apontam para conteúdo hospedado pela Cathopic

• Apenas otimizado para a web: o conteúdo é entregue em resolução adequada para exibição digital

• Sem arquivos originais: os originais em alta resolução nunca ficam acessíveis via API

• Sempre hospedado: o conteúdo permanece nos servidores da Cathopic ou em CDN autorizada

Resoluções disponíveis

A API fornece três tamanhos otimizados para a web:

• Pequeno: adequado para miniaturas e pequenos embeds (normalmente ~400px de largura)

• Médio: bom para conteúdo web padrão (normalmente ~800px de largura)

• Grande: melhor qualidade para exibição na web (normalmente ~1200px de largura)

Restrições críticas:

• Arquivos originais em alta resolução NUNCA são fornecidos

• As resoluções são otimizadas para exibição em tela, não para impressão

• Os tamanhos dos arquivos são compactados para entrega rápida na web

• Você não pode solicitar resoluções personalizadas nem qualidade original

Para os termos completos, leia o Contrato de Licença da API completo e consulte a documentação técnica em api.cathopic.com/docs.

Baixar imagens envolve duas etapas: licenciar o recurso com /confirm e depois usar as URLs retornadas.

Etapa 1: Licencie o recurso

Chame /confirm para licenciar um recurso para um usuário final específico:

POST https://api.cathopic.com/confirm
x-api-key: YOUR_API_KEY
{
  "media_id": 1234,
  "usage_type": "website",
  "client_identifier": "user_123"
}

Parâmetros:

• media_id - O ID do recurso nos seus resultados de busca

• usage_type - "website" ou "email"

• client_identifier - ID único do seu usuário final

Etapa 2: Use as URLs de download

A resposta contém URLs permanentes em vários formatos:

{
  "download_url": {
    "avif": {
      "320": "https://...",
      "640": "https://...",
      "1280": "https://...",
      "1920": "https://...",
      "2560": "https://..."
    },
    "jpeg": {
      "320": "https://...",
      "640": "https://...",
      "1280": "https://...",
      "1920": "https://...",
      "2560": "https://..."
    }
  }
}

Importante: armazene as URLs

As URLs retornadas são permanentes - armazene-as no seu banco de dados:

// Depois de chamar /confirm
const response = await api.confirm(mediaId, userId);
// Armazene no seu banco de dados
await db.save({
  userId: userId,
  mediaId: mediaId,
  avifUrls: response.download_url.avif,
  jpegUrls: response.download_url.jpeg,
  licensedAt: new Date()
});
// Na próxima vez, recupere do banco de dados em vez de chamar /confirm novamente

Escolhendo o formato certo

Formato AVIF:

• Tamanhos de arquivo menores (melhor desempenho)

• Melhor compressão

• Recomendado para navegadores modernos

• Não é compatível com navegadores mais antigos

Formato JPEG:

• Compatibilidade universal

• Tamanhos de arquivo maiores

• Use como alternativa para navegadores mais antigos

Lembrete crítico

⚠️ Verifique sempre seu banco de dados antes de chamar /confirm. Chamá-lo várias vezes para o mesmo usuário e recurso criará cobranças duplicadas.

Documentação completa em api.cathopic.com/docs.