API di KaraokeCreator

1. La chiave API

Ogni richiesta deve avere l'intestazione X-KC-Key con la tua chiave personale. La chiave è legata al tuo account KaraDom: i brani creati con le API usano lo stesso abbonamento della pagina web (stessi brani disponibili, stesse regole: oltre 5 minuti o brano live contano di più).

Per avere la chiave serve un abbonamento KaraokeCreator attivo: scrivici dal modulo contatti indicando l'email del tuo account. La chiave ti viene mostrata una volta sola: conservala come una password e non metterla nel codice di una pagina web pubblica.

X-KC-Key: la_tua_chiave

Indirizzo base di tutte le chiamate: https://karaokecreator.karadom.it

2. Come funziona

1. Invii il brano: un file audio (/api/upload_file) oppure un link YouTube o "Artista - Titolo" (/api/search_or_fetch). Ricevi un job_id.
2. Controlli lo stato con /api/job/{job_id} ogni 5-10 secondi, finché diventa ready_to_edit.
3. Chiedi i file finali con /api/generate (puoi mandare anche il testo corretto).
4. Quando lo stato è completed scarichi lo ZIP con /api/download_zip/{job_id}: base karaoke MP3 con il testo sincronizzato dentro (tag SYLT/USLT), voce guida e file LRC.

3. Endpoint

POST/api/upload_file

Carica un file audio (mp3, flac, wav, m4a, aac, ogg, opus, webm, mp4). Formato multipart/form-data.

Campo	Obbligatorio	Descrizione
file	sì	Il file audio del brano.
title	consigliato	"Artista - Titolo": serve a trovare il testo giusto.
lyrics	no	Il testo del brano (una riga per verso) oppure un LRC con i tempi: se c'è, viene usato al posto della ricerca automatica.

Risposta: {"job_id": "audio_…", "artist": "…", "title": "…"}

POST/api/search_or_fetch

Crea la base partendo da un link YouTube o da "Artista - Titolo". Corpo JSON.

Campo	Obbligatorio	Descrizione
query	sì	Link YouTube oppure "Artista - Titolo".
title	no	"Artista - Titolo" se la query è un link.
lyrics	no	Testo o LRC, come sopra.

Risposta: {"job_id": "yt_…", "kind": "youtube_processing", "credits_reserved": 1}

GET/api/job/{job_id}

Stato del lavoro: {"job_id", "status", "progress", "message", …}. Quando è ready_to_edit contiene anche il testo con i tempi, che puoi correggere prima della generazione.

POST/api/generate

Crea i file finali. Corpo JSON: {"project_id": "<job_id>"}, più facoltativo "editor_text" con il testo corretto. Risposta: {"job_id", "status": "generating"}.

GET/api/download_zip/{job_id}

Scarica lo ZIP con base karaoke, voce guida e LRC (quando lo stato è completed).

4. Stati del lavoro

Stato	Cosa significa
uploading / processing	Separazione della voce e sincronizzazione del testo in corso.
ready_to_edit	Testo sincronizzato pronto: chiama /api/generate.
need_lyrics	Il testo del brano non è stato trovato: rimanda il brano con il campo lyrics.
generating	Creazione dei file finali.
completed	Pronto: scarica lo ZIP.
error / failed	Errore: il messaggio spiega il motivo.

5. Esempio completo (Python)

import time, requests

BASE = "https://karaokecreator.karadom.it"
H = {"X-KC-Key": "la_tua_chiave"}

# 1) invio del brano
with open("brano.mp3", "rb") as f:
    r = requests.post(BASE + "/api/upload_file", headers=H,
                      files={"file": f}, data={"title": "Artista - Titolo"})
job = r.json()["job_id"]

# 2) attesa del testo sincronizzato
while True:
    s = requests.get(BASE + "/api/job/" + job, headers=H).json()
    if s["status"] == "ready_to_edit":
        break
    if s["status"] in ("need_lyrics", "error", "failed"):
        raise SystemExit(s.get("message"))
    time.sleep(8)

# 3) file finali
requests.post(BASE + "/api/generate", headers=H, json={"project_id": job})
while requests.get(BASE + "/api/job/" + job, headers=H).json()["status"] != "completed":
    time.sleep(5)

# 4) download
zip_bytes = requests.get(BASE + "/api/download_zip/" + job, headers=H).content
open("base_karaoke.zip", "wb").write(zip_bytes)

Con curl

curl -H "X-KC-Key: la_tua_chiave" -F "file=@brano.mp3" -F "title=Artista - Titolo" \
     https://karaokecreator.karadom.it/api/upload_file

curl -H "X-KC-Key: la_tua_chiave" https://karaokecreator.karadom.it/api/job/JOB_ID

6. Errori

Codice	Significato
401	Chiave mancante o non valida.
402	Nessun brano disponibile nel tuo abbonamento.
400 / 422	Richiesta incompleta (file, query o project_id mancanti).
404	Lavoro non trovato o file non ancora pronti.

7. In arrivo