OpenRouter — IA per parsing de metadades

Què és i per a què serveix

OpenRouter és un gateway d'API que dona accés a múltiples models d'IA (Gemma, Llama, GPT, DeepSeek...) amb una sola clau. A LDP s'utilitza per:

• Parsing de descripcions YouTube: Extreure automàticament nom del ball, coreògraf, cançó, counts, parets, nivell i data de premiere des de descripcions de vídeos
• Fallback intel·ligent: Quan el parser de regex (DanceDescriptionParser) no pot extreure totes les dades, la IA complementa

El backend usa OpenRouter (via GeminiAiService). L'importador bulk de YouTube (youtube-importer/) suporta OpenRouter o OpenAI directament.

Crear compte

1. Entra a OpenRouter
2. Registra't (email o OAuth)
3. Ves a API Keys
4. Clica Create Key
5. Copia la clau generada

Variables d'entorn

Al fitxer .env:

OPENROUTER_API_KEY=<la teva clau>
AI_MODEL=google/gemma-3-27b-it:free
AI_ENABLED=true

Models disponibles

Model	Preu	Qualitat	Ús recomanat
google/gemma-3-27b-it:free	Gratuït (50 req/dia)	Bona	Desenvolupament, proves
openai/gpt-3.5-turbo	~$0.002/req	Bona	Ús moderat
openai/gpt-4o-mini	~$0.001/req	Molt bona	Importació bulk
openai/gpt-4o	~$0.01/req	Excel·lent	Casos difícils

Per canviar el model, modifica AI_MODEL al .env. No cal canviar codi.

Alternativa: OpenAI directament

L'importador bulk de YouTube (youtube-importer/) també suporta OpenAI directament:

# Al youtube-importer/.env
OPENAI_API_KEY=<la teva clau OpenAI>
OPENAI_MODEL=gpt-4o-mini

Això NO afecta el backend — el backend sempre usa OpenRouter.

Verificació

1. Arrenca el backend amb el perfil local
2. Importa un ball des d'una URL YouTube amb una descripció rica
3. El sistema hauria d'extreure automàticament: nom, coreògraf, cançó, counts, parets, nivell
4. Als logs, busca GeminiAiService per veure les crides a l'API

Sense la clau configurada, la importació YouTube segueix funcionant amb el parser de regex (DanceDescriptionParser), però amb menys precisió.

Limitacions i quotes

Pla	Límit	Cost
Gratuït (models :free)	50 req/dia	$0
Amb crèdits	Segons model	Variable

Per importació massiva (milers de vídeos), el model gratuït no és suficient. Carrega crèdits o usa OpenAI directament amb gpt-4o-mini (~$1 per 1.000 vídeos).

Resolució de problemes

Error 401 (Invalid API key)

• Verifica que OPENROUTER_API_KEY és correcte
• Les claus d'OpenRouter comencen per sk-or-

Error 429 (Rate limit)

• Has superat el límit del model gratuït (50/dia)
• Opcions: esperar fins demà, canviar a un model de pagament, o carregar crèdits

La IA no s'usa (parsing per regex)

• Verifica que AI_ENABLED=true
• Verifica que OPENROUTER_API_KEY té valor
• Si la clau és invàlida, el sistema fa fallback silenciós al parser de regex