tools.mfeliz.com

API REST com utilitários YouTube (transcrição, listagem de vídeos de canais, análises persistentes) e armazenamento de memória persistente (ficheiros Markdown/texto). Pensada para ser consumida por modelos de IA — todas as respostas são JSON exceto a raiz HTML.

v1.4.0 base: https://tools.mfeliz.com JSON spec: ?format=json

🔑 Autenticação

Header X-API-Key: <chave> ou query param ?api_key=<chave>. A chave é definida pela variável de ambiente TOOLS_API_KEY no servidor.

Necessária para: POST /memoria, POST /memoria/append, PATCH /memoria, POST /youtube-analyses. Os restantes endpoints são públicos.

📡 Endpoints

GET /youtube

Transcrição completa + metadata de um vídeo do YouTube.

Parâmetros

url string obrigatório
URL completo do vídeo, shorts, youtu.be ou apenas o video_id (11 chars).
link string opcional
Alias para 'url' (compatibilidade).

Exemplo de pedido

GET /youtube?url=https://www.youtube.com/watch?v=XVO3zsHdvio

Exemplo de resposta

{
  "video_id": "XVO3zsHdvio",
  "title": "...",
  "channel": "...",
  "channel_id": "UC...",
  "publish_date": "2025-09-12T14:00:00+00:00",
  "publish_date_parts": {
    "year": 2025,
    "month": 9,
    "day": 12
  },
  "duration_seconds": 612,
  "view_count": 123456,
  "language": "en",
  "transcript": "texto completo concatenado...",
  "segments": [
    {
      "start": 0.0,
      "duration": 2.4,
      "text": "..."
    }
  ]
}

Erros

400 — Parâmetro 'url' em falta ou video_id inválido.
404 — Transcrição desativada, inexistente ou vídeo privado.
503 — Pedido bloqueado pelo YouTube (IP bloqueado).

GET /youtube-channel

Lista vídeos de um canal com filtros de período, keyword e estado de análise. Fonte: RSS feed oficial do YouTube (timestamps reais ISO 8601) + yt-dlp como fallback para listagens >15.

Parâmetros

channel string obrigatório
@handle (ex: @HormoziHighlight), channel_id (UC… com 24 chars) ou username.
period enum opcional · default all · valores: 1d, 1w, 1m, 3m, 6m, 1y, all
Janela temporal. '1d' = últimas 24h.
keyword string opcional
Filtra títulos que contenham este termo (case-insensitive).
status enum opcional · default all · valores: all, analyzed, pending
Filtra por estado em /youtube-analyses.
sort enum opcional · default newest · valores: newest, oldest, popular, relevant
'relevant' só faz efeito com 'keyword'. 'popular' ordena por view_count.
limit int opcional · default 50
Máx 1000. Usa paginação via continuation tokens do YouTube — cada página traz 30 vídeos com datas relativas. RSS feed dá os 15 primeiros com timestamps precisos.

Exemplo de pedido

GET /youtube-channel?channel=@HormoziHighlight&period=1d&sort=newest

Exemplo de resposta

{
  "channel": "@HormoziHighlight",
  "channel_id": "UCrvchO1h6lWZAuGaa1LqX9Q",
  "source": "rss",
  "total_videos_found": 15,
  "filtered_count": 15,
  "videos": [
    {
      "video_id": "sfaw7wmGfls",
      "title": "The Modern-Day Cigarette: Brain Meds...",
      "url": "https://youtu.be/sfaw7wmGfls",
      "published": "2026-05-10T10:00:00+00:00",
      "age_hours": 2.6,
      "view_count": 1234,
      "average_rating": 4.95,
      "thumbnail": "https://i.ytimg.com/...",
      "analyzed": false,
      "analysis_date": null
    }
  ]
}

ℹ Vídeos sem data (vindos só do fallback yt-dlp) são excluídos quando period != 'all'.

GET /youtube-analyses

Lista todas as análises guardadas (ordenadas por data desc) ou obtém uma análise específica.

Parâmetros

video_id string opcional
Se presente, devolve a análise completa desse vídeo.

Exemplo de pedido

GET /youtube-analyses?video_id=XVO3zsHdvio

GET /youtube-analyses/index

Alias para /youtube-analyses (lista cronológica do índice).

GET /youtube-analyses/search

Procura análises por título ou tópico.

Parâmetros

topic string obrigatório
Termo a procurar (case-insensitive).

Exemplo de pedido

GET /youtube-analyses/search?topic=pricing

GET /youtube-analyses/{channel}

Lista análises de um canal específico.

Exemplo de pedido

GET /youtube-analyses/HormoziHighlight

GET /youtube-analyses/{channel}/{year}/{month}

Lista análises de um canal num mês específico.

Exemplo de pedido

GET /youtube-analyses/HormoziHighlight/2026/05

POST /youtube-analyses 🔑 X-API-Key

Guarda uma análise. Cria estrutura yt_analyses/{channel}/{year}/{month}/ automaticamente.

Body JSON

video_id string obrigatório
title string opcional · default Sem título
topics string[] opcional
Tags para pesquisa.
channel string opcional · default unknown
Sanitizado para uso como nome de pasta.
content string opcional
Markdown ou texto da análise.

Exemplo de pedido

POST /youtube-analyses  (header X-API-Key: ...)

Exemplo de body

{
  "video_id": "XVO3zsHdvio",
  "title": "...",
  "topics": [
    "pricing",
    "offers"
  ],
  "channel": "HormoziHighlight",
  "content": "# Análise\n..."
}

GET /memoria

Lê o conteúdo de um ficheiro de memória (Markdown/texto).

Parâmetros

id string opcional · default default
Nome do ficheiro sem extensão. Procura .md → .txt → sem extensão.

Exemplo de pedido

GET /memoria?id=notas-projeto-x

Exemplo de resposta

{
  "id": "notas-projeto-x",
  "ficheiro": "notas-projeto-x.md",
  "conteudo": "...",
  "tamanho_bytes": 1234,
  "modificado": "2026-05-10T12:00:00"
}

GET /memoria/lista

Lista todos os ficheiros de memória com tamanho e data de modificação.

POST /memoria 🔑 X-API-Key

Cria ou substitui um ficheiro de memória. Corpo = conteúdo bruto OU JSON {conteudo}.

Parâmetros

id string obrigatório
Nome do ficheiro. Se incluir .md/.txt usa essa extensão, caso contrário .txt por defeito.

Exemplo de pedido

POST /memoria?id=notas-projeto-x  (header X-API-Key: ...) body: texto bruto

POST /memoria/append 🔑 X-API-Key

Acrescenta conteúdo ao fim de um ficheiro de memória (prefixa nova linha).

Parâmetros

id string obrigatório

PATCH /memoria 🔑 X-API-Key

Edição cirúrgica de um ficheiro de memória.

Parâmetros

id string obrigatório

Body JSON

operation enum obrigatório · valores: str_replace, replace_line, insert_at, remove_line, replace_between_markers

Operações suportadas (body.operation)

{
  "str_replace": {
    "old": "string",
    "new": "string",
    "desc": "Substitui a 1ª ocorrência de 'old' por 'new'."
  },
  "replace_line": {
    "line": "int (1-indexed)",
    "content": "string"
  },
  "insert_at": {
    "line": "int (1-indexed)",
    "content": "string"
  },
  "remove_line": {
    "line": "int (1-indexed)"
  },
  "replace_between_markers": {
    "start_marker": "string",
    "end_marker": "string",
    "content": "string"
  }
}

Exemplo de body

{
  "operation": "str_replace",
  "old": "Versão 1",
  "new": "Versão 2"
}

GET /link-do-yt

Alias legacy de /youtube (retrocompatibilidade).

Parâmetros

url string obrigatório

🤖 Para IAs / consumo programático

Faz GET /?format=json ou envia Accept: application/json para receber a especificação completa em JSON estruturado, com todos os parâmetros, exemplos e códigos de erro.

curl -s -H "Accept: application/json" https://tools.mfeliz.com/ | jq .