ogacai

Convierte videos en artículos de blog mediante IA.

Video → IA → Artículo

ogacai automatiza la creación de un artículo estructurado en Markdown, listo para integrarse o publicarse en un blog, manteniendo la fidelidad al contenido original sin depender de un proceso manual de transcripción.

Inicio rápido

Requisitos: Python 3.9 o superior.

1. Instalación

pip install ogacai

(Opcional: Para descargar subtítulos directamente desde YouTube, instale la dependencia de obtención)

pip install "ogacai[fetch]"

2. Configuración de API (DeepSeek por defecto) Las credenciales pueden configurarse de forma persistente o mediante variables de entorno:

export DEEPSEEK_API_KEY="su-api-key"

3. Ejecución

# Descargar los subtítulos automáticos
ogacai fetch "https://youtu.be/ID" --salida-dir /tmp/output

# Generar el artículo validado y su portada
ogacai run /tmp/output/<video_id>.es.json3 --output-dir ./mi-blog

Características principales

• Procesamiento determinista: Reconstruye el texto hablado y elimina anotaciones de audio (ej. [música]) sin depender de llamadas a APIs externas.

• Múltiples proveedores de IA: Soporte integrado para DeepSeek (predeterminado), Cloudflare Workers AI y Gemini.

• Validación estructural: Verifica automáticamente la integridad del front matter (title, description, date, image, imageAlt, tags) y el balance de los bloques de código.

• Generación de OpenGraph: Crea automáticamente la imagen de portada del artículo en formato PNG (desactivable con --sin-portada).

• Inspección de limpieza: Permite visualizar un diff exacto de las palabras descartadas durante el procesamiento mediante el subcomando preview.

• Ejecución modular: Cada etapa del pipeline puede ejecutarse de forma independiente para facilitar su integración o depuración.

• Contexto enriquecido de YouTube: Si se configura una API key de YouTube (YOUTUBE_COMMENTS o youtube.api_key), run enriquece el input del LLM con el título, la descripción y los comentarios más relevantes del video (opcional, desactivable con --sin-contexto-youtube; un fallo ahí nunca aborta la generación).

• Presupuesto de salida ampliable: --escala N multiplica los tokens de salida (y el umbral de aviso de entrada) para artículos más extensos, clampeando contra el techo técnico de cada proveedor.

• Fallback entre proveedores: Si el proveedor elegido en run falla, se ofrece interactivamente pasar a otro proveedor configurado, sin repetir la transcripción ni el contexto ya construidos.

Arquitectura interna

El comando run coordina una serie de etapas independientes. Esta separación permite depurar el parseo de datos y calibrar la limpieza del texto sin consumir cuota de API.

YouTube → subtítulos (.json3) → texto limpio → IA → Markdown validado

Responsabilidades por etapa:

1. fetch: Descarga el archivo .json3 de subtítulos automáticos vía yt-dlp, omitiendo la descarga del video.

2. procesar: Lee el .json3, reconstruye el texto, deduplica el solapamiento de los "rolling captions" y genera dos versiones en texto plano (raw y clean).

3. generar: Envía el texto limpio al proveedor de IA utilizando un system prompt estricto, el cual recibe texto y devuelve únicamente texto estructurado.

4. validar: Verifica la estructura del archivo generado.

Interfaz de línea de comandos (CLI)

Puede consultar todas las opciones ejecutando ogacai --help.

| | fetch | Descarga el archivo .json3 de subtítulos a partir de una URL de YouTube.

| | procesar | Convierte un archivo .json3 en transcripcion_raw.txt y transcripcion_clean.txt.

| | preview | Procesa los datos en memoria y muestra las diferencias exactas eliminadas en la limpieza.

| | generar | Invoca al proveedor de IA proporcionando un archivo .txt limpio y devuelve el artículo.

| | validar | Valida estructuralmente un artículo Markdown generado previamente.

| | config | Administra la configuración persistente de la herramienta.

|

Configuración avanzada de proveedores

Las credenciales pueden definirse temporalmente mediante variables de entorno o de forma persistente utilizando el CLI. El comando ogacai config show muestra la configuración activa; por motivos de seguridad, las claves y tokens se enmascaran mostrando únicamente los últimos 4 caracteres.

Elegir el proveedor y el modelo por defecto

Sin --proveedor, generar/run usan el proveedor definido en default_proveedor (o deepseek si no está seteado). El modelo de cada proveedor también es configurable:

# Proveedor por defecto (persistente, evita pasar --proveedor cada vez)
ogacai config set default_proveedor gemini

# Modelo por proveedor (opcional; si no se setea, se usa el default del cliente)
ogacai config set deepseek.model deepseek-v4-flash
ogacai config set workers_ai.model "@cf/google/gemma-4-26b-a4b-it"
ogacai config set gemini.model gemini-3.5-flash-lite

# Override por corrida (sin tocar la config): el flag gana sobre config.toml
ogacai run <video> --proveedor workers-ai --model "@cf/google/gemma-4-26b-a4b-it"

DeepSeek (Predeterminado)

ogacai config set api_key "su-api-key"
# Alternativa: export DEEPSEEK_API_KEY="su-api-key"

Cloudflare Workers AI Requiere dos credenciales. Para utilizarlo, configúrelo una vez como predeterminado (ogacai config set default_proveedor workers-ai) o asígnelo por corrida con --proveedor workers-ai al invocar run o generar.

ogacai config set workers_ai.account_id "su-account-id"
ogacai config set workers_ai.api_token "su-api-token"

Gemini Para utilizarlo, configúrelo una vez como predeterminado (ogacai config set default_proveedor gemini) o asígnelo por corrida con --proveedor gemini. Puede especificar la versión del modelo a utilizar; si se omite, el sistema emplea gemini-3.5-flash-lite por defecto.

ogacai config set gemini.api_key "su-api-key"
ogacai config set gemini.model "gemini-3.5-flash-lite"

Contexto de YouTube (enriquecimiento del input)

Por defecto run agrega al input del LLM el título, la descripción y los top_n comentarios más relevantes del video (solo como apoyo de tono/énfasis; la transcripción sigue siendo la única fuente de hechos). Requiere una API key de la YouTube Data API v3 y que el argumento sea una URL (o un .json3 nombrado <video_id>.<lang>.json3):

# Variable de entorno (gana sobre config.toml) -- mismo nombre que en youtube_analyzer
export YOUTUBE_COMMENTS="su-api-key"
# o, de forma persistente:
ogacai config set youtube.api_key "su-api-key"
# Comentarios a considerar (default 10):
ogacai config set youtube.top_n 10

Para desactivar el enriquecimiento en una corrida puntual: ogacai run <video> --sin-contexto-youtube.

Artículos más extensos: --escala N

--escala N multiplica el presupuesto de tokens de salida (y el umbral de aviso de entrada) por N. Clampea contra el techo técnico del proveedor avisando por stderr:

ogacai run https://youtu.be/ID --escala 2

Fallback entre proveedores

Si el proveedor elegido falla durante run, se ofrece interactivamente pasar a otro proveedor con credenciales completas (sin reconstruir el input). Sin terminal interactiva (cron/CI), o si no hay alternativas, el error original se propaga como antes. --model se descarta al cambiar de proveedor.

Licencia: MIT.