openvoiceui 1.0.0

package/routes/suno.py

@@ -0,0 +1,664 @@
+"""
+routes/suno.py — Suno AI Song Generation Blueprint
+
+Provides endpoints for generating songs via Suno API (sunoapi.org).
+Generated songs land in generated_music/ and show up in the music player.
+
+Endpoints:
+  GET/POST  /api/suno              (action: generate|status|list|credits)
+  POST      /api/suno/callback     (webhook from sunoapi.org)
+  GET/POST  /api/suno/completed    (frontend polls for completed songs)
+
+Agent trigger:
+  Include [SUNO_GENERATE:prompt text here] in a response to kick off generation.
+  The frontend detects the tag, calls /api/suno?action=generate, and polls for completion.
+"""
+
+import hashlib
+import hmac
+import ipaddress
+import json
+import logging
+import os
+import socket
+import threading
+import time
+import uuid
+from datetime import datetime
+from pathlib import Path
+from urllib.parse import urlparse
+
+import requests as http_requests
+from flask import Blueprint, jsonify, request
+
+# ---------------------------------------------------------------------------
+# Paths & config
+# ---------------------------------------------------------------------------
+
+from services.paths import GENERATED_MUSIC_DIR
+
+GENERATED_MUSIC_DIR.mkdir(parents=True, exist_ok=True)
+GENERATED_METADATA_FILE = GENERATED_MUSIC_DIR / 'generated_metadata.json'
+
+SUNO_API_KEY = os.environ.get('SUNO_API_KEY', '')
+SUNO_API_BASE = 'https://api.sunoapi.org'
+SUNO_WEBHOOK_SECRET = os.environ.get('SUNO_WEBHOOK_SECRET', '')
+SUNO_MAX_DOWNLOAD_BYTES = 50 * 1024 * 1024  # 50 MB cap on audio downloads
+
+# Callback URL: explicit > auto-derived from DOMAIN > empty
+# sunoapi.org requires callBackUrl; auto-derive from DOMAIN if not set explicitly.
+_domain = os.environ.get('DOMAIN', '')
+SUNO_CALLBACK_URL = (
+    os.environ.get('SUNO_CALLBACK_URL')
+    or (f'https://{_domain}/api/suno/callback' if _domain else '')
+)
+
+# ---------------------------------------------------------------------------
+# In-memory job tracking (single-worker deployment)
+# ---------------------------------------------------------------------------
+
+suno_jobs: dict = {}  # job_id -> {status, prompt, title, style, created_at, task_id, ...}
+completed_songs_queue: list = []  # [{song_id, title, job_id, completed_at, url}, ...]
+_suno_lock = threading.Lock()
+
+logger = logging.getLogger(__name__)
+
+
+def _is_safe_download_url(url: str) -> bool:
+    """Reject URLs that point to private/reserved IP ranges (SSRF protection)."""
+    try:
+        parsed = urlparse(url)
+        hostname = parsed.hostname
+        if not hostname or parsed.scheme not in ('http', 'https'):
+            return False
+        # Resolve hostname to IP and check if private/reserved
+        for info in socket.getaddrinfo(hostname, parsed.port or 443, proto=socket.IPPROTO_TCP):
+            addr = info[4][0]
+            ip = ipaddress.ip_address(addr)
+            if ip.is_private or ip.is_reserved or ip.is_loopback or ip.is_link_local:
+                logger.warning(f'SSRF blocked: {url} resolves to private IP {addr}')
+                return False
+        return True
+    except (ValueError, socket.gaierror, OSError) as exc:
+        logger.warning(f'SSRF check failed for {url}: {exc}')
+        return False
+
+
+# ---------------------------------------------------------------------------
+# Blueprint
+# ---------------------------------------------------------------------------
+
+suno_bp = Blueprint('suno', __name__)
+
+# ---------------------------------------------------------------------------
+# Metadata helpers
+# ---------------------------------------------------------------------------
+
+
+def _load_generated_metadata() -> dict:
+    if GENERATED_METADATA_FILE.exists():
+        try:
+            with open(GENERATED_METADATA_FILE) as f:
+                return json.load(f)
+        except Exception:
+            return {}
+    return {}
+
+
+def _save_generated_metadata(metadata: dict) -> None:
+    """Persist generated music metadata (atomic write)."""
+    tmp = GENERATED_METADATA_FILE.with_suffix('.tmp')
+    tmp.write_text(json.dumps(metadata, indent=2))
+    tmp.replace(GENERATED_METADATA_FILE)
+
+
+def _add_song_to_metadata(filename: str, title: str, prompt: str, style: str,
+                          duration: float = 0, song_id: str = '') -> None:
+    """Write a new song entry to generated_metadata.json in the format music.py expects."""
+    metadata = _load_generated_metadata()
+    metadata[filename] = {
+        'title': title,
+        'artist': 'Clawdbot AI',
+        'description': prompt[:200] if prompt else 'AI-generated track',
+        'genre': _guess_genre(style or prompt),
+        'energy': 'high',
+        'duration_seconds': round(duration, 1) if duration else 0,
+        'fun_facts': [],
+        'dj_intro_hints': [],
+        'dj_backstory': f'Generated by Clawdbot from prompt: {prompt[:100]}' if prompt else '',
+        'made_by': 'Clawdbot',
+        'created_date': datetime.now().strftime('%Y-%m-%d'),
+        'suno_id': song_id,
+    }
+    _save_generated_metadata(metadata)
+
+
+def _is_uuid(s: str) -> bool:
+    """Check if string looks like a UUID (hex-hex-hex-hex-hex pattern)."""
+    import re
+    return bool(re.match(r'^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$', s.strip(), re.IGNORECASE))
+
+
+def _slugify_title(title: str) -> str:
+    """Convert a song title to a safe filename slug (no extension)."""
+    import re
+    import unicodedata
+    # If the title is a UUID (Suno sometimes returns song ID as title), reject it
+    if _is_uuid(title):
+        return 'generated-track'
+    # Normalize unicode (e.g., smart quotes → ascii)
+    s = unicodedata.normalize('NFKD', title).encode('ascii', 'ignore').decode('ascii')
+    # Lowercase, replace non-alnum with hyphens, collapse multiples, strip edges
+    s = re.sub(r'[^a-z0-9]+', '-', s.lower()).strip('-')
+    return s[:80] or 'generated-track'
+
+
+def _unique_filename(directory: Path, base: str, ext: str = '.mp3') -> str:
+    """Return a unique filename in directory, appending -2, -3, etc. if needed."""
+    candidate = f'{base}{ext}'
+    if not (directory / candidate).exists():
+        return candidate
+    counter = 2
+    while (directory / f'{base}-{counter}{ext}').exists():
+        counter += 1
+    return f'{base}-{counter}{ext}'
+
+
+def _guess_genre(text: str) -> str:
+    """Rough genre guess from prompt keywords."""
+    if not text:
+        return 'Unknown'
+    t = text.lower()
+    for genre, keywords in [
+        ('Hip-Hop', ['hip hop', 'hiphop', 'rap', 'trap', 'beats']),
+        ('Electronic', ['electronic', 'edm', 'techno', 'house', 'synth', 'dance']),
+        ('Rock', ['rock', 'metal', 'guitar', 'punk', 'grunge']),
+        ('Pop', ['pop', 'catchy', 'radio', 'chorus']),
+        ('Country', ['country', 'western', 'cowboy', 'twang']),
+        ('Reggae', ['reggae', 'ska', 'dub', 'jamaican']),
+        ('Jazz', ['jazz', 'blues', 'soul', 'funk', 'groove']),
+    ]:
+        if any(kw in t for kw in keywords):
+            return genre
+    return 'Unknown'
+
+
+# ---------------------------------------------------------------------------
+# Main endpoint
+# ---------------------------------------------------------------------------
+
+
+@suno_bp.route('/api/suno', methods=['GET', 'POST'])
+def handle_suno():
+    """
+    Unified Suno endpoint.
+    action=generate  — Submit a generation job
+    action=status    — Poll job status (downloads when ready)
+    action=list      — List generated songs
+    action=credits   — Check API credits
+    """
+    if request.method == 'POST':
+        body = request.get_json(silent=True) or {}
+        action = body.get('action') or request.args.get('action', 'list')
+        # Allow POST body params to override query params
+        _q = lambda k, default='': body.get(k) or request.args.get(k, default)
+    else:
+        body = {}
+        action = request.args.get('action', 'list')
+        _q = lambda k, default='': request.args.get(k, default)
+
+    if not SUNO_API_KEY:
+        return jsonify({'action': 'error', 'response': 'SUNO_API_KEY not configured — add it to .env'})
+
+    try:
+        # ------------------------------------------------------------------
+        if action == 'list':
+            return _action_list()
+
+        elif action == 'generate':
+            return _action_generate(_q, body)
+
+        elif action == 'status':
+            return _action_status(_q('job_id') or _q('song_id'))
+
+        elif action == 'credits':
+            return _action_credits()
+
+        else:
+            return jsonify({'action': 'error', 'response': f"Unknown action '{action}'. Use: generate, status, list, credits"})
+
+    except Exception as exc:
+        logger.exception('Suno endpoint error')
+        return jsonify({'action': 'error', 'response': f'Suno error: {exc}'}), 500
+
+
+# ---------------------------------------------------------------------------
+# Action handlers
+# ---------------------------------------------------------------------------
+
+
+def _action_list():
+    """Return all generated songs with metadata."""
+    metadata = _load_generated_metadata()
+    songs = []
+    for f in sorted(GENERATED_MUSIC_DIR.iterdir(), key=lambda p: p.stat().st_mtime, reverse=True):
+        if f.suffix.lower() in {'.mp3', '.wav', '.ogg', '.m4a'}:
+            meta = metadata.get(f.name, {})
+            songs.append({
+                'filename': f.name,
+                'title': meta.get('title', f.stem),
+                'genre': meta.get('genre', 'Unknown'),
+                'description': meta.get('description', ''),
+                'duration_seconds': meta.get('duration_seconds', 0),
+                'made_by': meta.get('made_by', 'Clawdbot'),
+                'created_date': meta.get('created_date', ''),
+                'url': f'/generated_music/{f.name}',
+                'size_bytes': f.stat().st_size,
+            })
+    return jsonify({
+        'action': 'list',
+        'count': len(songs),
+        'songs': songs,
+        'response': f'Got {len(songs)} AI-generated tracks in the vault!',
+    })
+
+
+def _action_generate(_q, body: dict):
+    """Submit a song generation job to Suno API."""
+    prompt = _q('prompt') or body.get('prompt', '')
+    style = _q('style') or body.get('style', '')
+    title = _q('title') or body.get('title', '')
+    lyrics = _q('lyrics') or body.get('lyrics', '')
+    instrumental = (_q('instrumental') or str(body.get('instrumental', 'false'))).lower() == 'true'
+    vocal_gender = _q('vocal_gender') or body.get('vocal_gender', 'm')
+
+    if not prompt and not lyrics and not style:
+        return jsonify({'action': 'error', 'response': 'Need a prompt, lyrics, or style — tell me what kind of song to make.'})
+
+    # Determine mode: custom (explicit lyrics) vs description (Suno writes lyrics)
+    if lyrics:
+        song_prompt = lyrics
+        has_lyrics = True
+    elif '[Verse' in prompt or '[Chorus' in prompt or '[Hook' in prompt or '[Bridge' in prompt:
+        song_prompt = prompt
+        has_lyrics = True
+    else:
+        # Description mode — Suno auto-generates lyrics from the description
+        combined = f'{style}. {prompt}' if style and prompt else (style or prompt)
+        song_prompt = combined[:500]
+        has_lyrics = False
+
+    # Build Suno API request
+    if has_lyrics:
+        request_body = {
+            'prompt': song_prompt,
+            'customMode': True,
+            'instrumental': instrumental,
+            'model': 'V5',
+            'vocalGender': vocal_gender,
+            'negativeTags': 'low quality, mumbling, distorted, off-key',
+            'style': style or 'Catchy, Radio-friendly, Professional',
+        }
+        if title:
+            request_body['title'] = title
+    else:
+        request_body = {
+            'prompt': song_prompt,
+            'customMode': False,
+            'instrumental': instrumental,
+            'model': 'V5',
+            'vocalGender': vocal_gender,
+        }
+
+    if SUNO_CALLBACK_URL:
+        request_body['callBackUrl'] = SUNO_CALLBACK_URL
+
+    logger.info(f'Suno generate: mode={"custom" if has_lyrics else "auto"} prompt={song_prompt[:80]}')
+
+    try:
+        resp = http_requests.post(
+            f'{SUNO_API_BASE}/api/v1/generate',
+            headers={'Authorization': f'Bearer {SUNO_API_KEY}', 'Content-Type': 'application/json'},
+            json=request_body,
+            timeout=30,
+        )
+        logger.info(f'Suno API response: {resp.status_code} {resp.text[:300]}')
+
+        if resp.status_code == 200:
+            data = resp.json()
+            if data.get('code') == 200 and data.get('data', {}).get('taskId'):
+                task_id = data['data']['taskId']
+                job_id = str(uuid.uuid4())
+                suno_jobs[job_id] = {
+                    'status': 'generating',
+                    'prompt': prompt,
+                    'title': title,
+                    'style': style,
+                    'task_id': task_id,
+                    'created_at': time.time(),
+                }
+                return jsonify({
+                    'action': 'generating',
+                    'job_id': job_id,
+                    'task_id': task_id,
+                    'response': f"Cooking! '{title or 'your track'}' is being generated — check back in 30-60 seconds.",
+                    'estimated_seconds': 45,
+                })
+            else:
+                return jsonify({'action': 'error', 'response': f"Suno API error: {data.get('msg', 'Unknown error')}"})
+        else:
+            return jsonify({'action': 'error', 'response': f'Suno API HTTP {resp.status_code}: {resp.text[:200]}'})
+
+    except http_requests.RequestException as exc:
+        return jsonify({'action': 'error', 'response': f"Couldn't reach Suno API: {exc}"})
+
+
+def _action_status(job_id: str):
+    """Poll generation status; downloads song when Suno reports SUCCESS."""
+    if not job_id:
+        # Return status of most recent job
+        if suno_jobs:
+            job_id = max(suno_jobs.keys())
+        else:
+            return jsonify({'action': 'status', 'status': 'no_jobs', 'response': 'No songs cooking right now.'})
+
+    if job_id not in suno_jobs:
+        return jsonify({'action': 'status', 'status': 'not_found', 'response': "Can't find that job."})
+
+    job = suno_jobs[job_id]
+
+    # If already complete, just report
+    if job.get('status') == 'complete':
+        return jsonify({
+            'action': 'complete',
+            'status': 'complete',
+            'job_id': job_id,
+            'song_id': job.get('song_id', ''),
+            'title': job.get('title', 'Generated Track'),
+            'url': job.get('url', ''),
+            'response': f"Done! '{job.get('title', 'your track')}' is ready to spin!",
+        })
+
+    elapsed = time.time() - job['created_at']
+
+    # Don't bother polling Suno for the first 20 seconds
+    if elapsed < 20:
+        return jsonify({
+            'action': 'status',
+            'status': 'generating',
+            'elapsed_seconds': int(elapsed),
+            'response': f'Still cooking — about {max(0, 30 - int(elapsed))} more seconds...',
+        })
+
+    task_id = job.get('task_id')
+    if not task_id:
+        return jsonify({'action': 'status', 'status': 'generating', 'elapsed_seconds': int(elapsed), 'response': 'Generating...'})
+
+    try:
+        check = http_requests.get(
+            f'{SUNO_API_BASE}/api/v1/generate/record-info',
+            headers={'Authorization': f'Bearer {SUNO_API_KEY}'},
+            params={'taskId': task_id},
+            timeout=15,
+        )
+        logger.debug(f'Suno status check: {check.status_code} {check.text[:300]}')
+
+        if check.status_code == 200:
+            cdata = check.json()
+            if cdata.get('code') == 200:
+                status_data = cdata.get('data', {})
+                gen_status = status_data.get('status', '')
+
+                if gen_status == 'SUCCESS':
+                    songs = status_data.get('response', {}).get('sunoData', [])
+                    # Suno returns 2 clips per generation — only take the first one
+                    songs = songs[:1] if songs else []
+                    for song in songs:
+                        audio_url = song.get('audioUrl') or song.get('audio_url')
+                        if not audio_url:
+                            continue
+                        song_id = song.get('id', task_id)
+                        _raw_title = song.get('title') or ''
+                        # Suno API sometimes returns song ID as title — reject UUIDs
+                        if _raw_title and not _is_uuid(_raw_title):
+                            song_title = _raw_title
+                        else:
+                            song_title = job.get('title') or job.get('prompt', '')[:60] or 'Generated Track'
+                        duration = song.get('duration', 0)
+                        slug = _slugify_title(song_title)
+                        filename = _unique_filename(GENERATED_MUSIC_DIR, slug)
+                        save_path = GENERATED_MUSIC_DIR / filename
+
+                        if not save_path.exists():
+                            if not _is_safe_download_url(audio_url):
+                                continue
+                            audio_resp = http_requests.get(audio_url, timeout=60, stream=True)
+                            if audio_resp.status_code == 200:
+                                content_length = int(audio_resp.headers.get('Content-Length', 0))
+                                if content_length > SUNO_MAX_DOWNLOAD_BYTES:
+                                    logger.warning(f'Suno download rejected: Content-Length {content_length} exceeds limit')
+                                    continue
+                                chunks = []
+                                total = 0
+                                for chunk in audio_resp.iter_content(chunk_size=65536):
+                                    total += len(chunk)
+                                    if total > SUNO_MAX_DOWNLOAD_BYTES:
+                                        logger.warning(f'Suno download aborted: exceeded {SUNO_MAX_DOWNLOAD_BYTES} bytes')
+                                        break
+                                    chunks.append(chunk)
+                                else:
+                                    save_path.write_bytes(b''.join(chunks))
+                                    logger.info(f'Suno downloaded: {song_title} → {filename}')
+                            else:
+                                logger.warning(f'Suno download failed: {audio_resp.status_code}')
+                                continue
+
+                        # Save metadata
+                        _add_song_to_metadata(
+                            filename=filename,
+                            title=song_title,
+                            prompt=job.get('prompt', ''),
+                            style=job.get('style', ''),
+                            duration=duration,
+                            song_id=song_id,
+                        )
+
+                        # Update job
+                        job['status'] = 'complete'
+                        job['song_id'] = song_id
+                        job['title'] = song_title
+                        job['url'] = f'/generated_music/{filename}'
+
+                        # Notify frontend poller
+                        completed_songs_queue.append({
+                            'song_id': song_id,
+                            'filename': filename,
+                            'title': song_title,
+                            'job_id': job_id,
+                            'url': f'/generated_music/{filename}',
+                            'completed_at': datetime.now().isoformat(),
+                            'prompt': job.get('prompt', ''),
+                        })
+
+                        return jsonify({
+                            'action': 'complete',
+                            'status': 'complete',
+                            'job_id': job_id,
+                            'song_id': song_id,
+                            'title': song_title,
+                            'url': f'/generated_music/{filename}',
+                            'response': f"Done! '{song_title}' is ready to spin!",
+                        })
+
+                    return jsonify({'action': 'status', 'status': 'complete_no_audio', 'response': 'Song generated but audio unavailable.'})
+
+                elif gen_status in ('PENDING', 'TEXT_SUCCESS', 'FIRST_SUCCESS'):
+                    return jsonify({
+                        'action': 'status',
+                        'status': 'generating',
+                        'elapsed_seconds': int(elapsed),
+                        'response': f'Still cooking ({gen_status})...',
+                    })
+                else:
+                    return jsonify({'action': 'status', 'status': gen_status.lower(), 'response': f'Status: {gen_status}'})
+
+    except Exception as exc:
+        logger.warning(f'Suno status poll error: {exc}')
+
+    return jsonify({
+        'action': 'status',
+        'status': 'generating',
+        'elapsed_seconds': int(elapsed),
+        'response': f'Still working... ({int(elapsed)}s elapsed)',
+    })
+
+
+def _action_credits():
+    """Check remaining Suno API credits."""
+    try:
+        resp = http_requests.get(
+            f'{SUNO_API_BASE}/api/v1/account/credits',
+            headers={'Authorization': f'Bearer {SUNO_API_KEY}'},
+            timeout=10,
+        )
+        if resp.status_code == 200:
+            data = resp.json()
+            credits = data.get('data', {}).get('credits', data.get('credits', '?'))
+            return jsonify({'action': 'credits', 'credits': credits, 'response': f'Suno credits remaining: {credits}'})
+        return jsonify({'action': 'error', 'response': f'Credits check failed: HTTP {resp.status_code}'})
+    except Exception as exc:
+        return jsonify({'action': 'error', 'response': f'Credits check error: {exc}'})
+
+
+# ---------------------------------------------------------------------------
+# Webhook callback (sunoapi.org POSTs here when song is done)
+# ---------------------------------------------------------------------------
+
+
+@suno_bp.route('/api/suno/callback', methods=['POST'])
+def suno_callback():
+    """Webhook from sunoapi.org — downloads song and queues frontend notification."""
+    try:
+        # Verify HMAC signature when a webhook secret is configured
+        if SUNO_WEBHOOK_SECRET:
+            sig_header = request.headers.get('X-Suno-Signature', '')
+            payload = request.get_data()
+            expected = hmac.new(SUNO_WEBHOOK_SECRET.encode(), payload, hashlib.sha256).hexdigest()
+            if not hmac.compare_digest(sig_header, expected):
+                logger.warning('Suno callback rejected: invalid signature')
+                return jsonify({'status': 'forbidden'}), 403
+
+        data = request.json or {}
+        logger.info(f'Suno callback: {json.dumps(data, indent=2)[:500]}')
+
+        if data.get('code') == 200:
+            callback_type = data.get('data', {}).get('callbackType', '')
+            task_id = data.get('data', {}).get('taskId', '')
+
+            # sunoapi.org sends: "text" (lyrics ready), "first"/"second" (audio ready), "complete"
+            # Only process 'complete' to avoid duplicates (first/second are partial deliveries
+            # of the same songs that appear again in complete).
+            if callback_type == 'complete' or (
+                callback_type not in ('text', 'first', 'second') and data.get('data', {}).get('data')
+            ):
+                songs = data.get('data', {}).get('data', [])
+                # Suno returns 2 clips per generation — only take the first one
+                # (user asked for 1 song, not 2 variations)
+                songs = songs[:1] if songs else []
+                for song in songs:
+                    audio_url = song.get('audioUrl') or song.get('audio_url')
+                    if not audio_url:
+                        continue  # "text" callback — lyrics only, no audio yet
+                    song_id = song.get('id', task_id)
+                    _raw_cb_title = song.get('title', '')
+                    if _raw_cb_title and not _is_uuid(_raw_cb_title):
+                        song_title = _raw_cb_title
+                    else:
+                        song_title = 'Generated Track'
+                    duration = song.get('duration', 0)
+                    slug = _slugify_title(song_title)
+                    filename = _unique_filename(GENERATED_MUSIC_DIR, slug)
+                    save_path = GENERATED_MUSIC_DIR / filename
+
+                    if audio_url and not save_path.exists():
+                        if not _is_safe_download_url(audio_url):
+                            continue
+                        try:
+                            audio_resp = http_requests.get(audio_url, timeout=60, stream=True)
+                            if audio_resp.status_code == 200:
+                                content_length = int(audio_resp.headers.get('Content-Length', 0))
+                                if content_length > SUNO_MAX_DOWNLOAD_BYTES:
+                                    logger.warning(f'Callback download rejected: size {content_length} exceeds limit')
+                                    continue
+                                chunks = []
+                                total = 0
+                                for chunk in audio_resp.iter_content(chunk_size=65536):
+                                    total += len(chunk)
+                                    if total > SUNO_MAX_DOWNLOAD_BYTES:
+                                        logger.warning(f'Callback download aborted: exceeded {SUNO_MAX_DOWNLOAD_BYTES} bytes')
+                                        break
+                                    chunks.append(chunk)
+                                else:
+                                    save_path.write_bytes(b''.join(chunks))
+                                    logger.info(f'Callback downloaded: {song_title} → {filename}')
+
+                                # Find matching job
+                                prompt = ''
+                                style = ''
+                                job_id = None
+                                for jid, job in suno_jobs.items():
+                                    if job.get('task_id') == task_id:
+                                        job['status'] = 'complete'
+                                        job['song_id'] = song_id
+                                        job['url'] = f'/generated_music/{filename}'
+                                        prompt = job.get('prompt', '')
+                                        style = job.get('style', '')
+                                        job_id = jid
+                                        break
+
+                                _add_song_to_metadata(filename, song_title, prompt, style, duration, song_id)
+
+                                completed_songs_queue.append({
+                                    'song_id': song_id,
+                                    'filename': filename,
+                                    'title': song_title,
+                                    'job_id': job_id or task_id,
+                                    'url': f'/generated_music/{filename}',
+                                    'completed_at': datetime.now().isoformat(),
+                                    'prompt': prompt,
+                                })
+                        except Exception as exc:
+                            logger.warning(f'Callback download error: {exc}')
+
+        return jsonify({'status': 'ok'})
+
+    except Exception as exc:
+        logger.error(f'Suno callback error: {exc}')
+        logger.error('Suno callback error: %s', exc)
+        return jsonify({'status': 'error', 'message': 'Internal server error'})
+
+
+# ---------------------------------------------------------------------------
+# Completed songs queue (frontend polls this)
+# ---------------------------------------------------------------------------
+
+
+@suno_bp.route('/api/suno/completed', methods=['GET', 'POST'])
+def suno_completed():
+    """
+    GET  — Returns completed songs waiting for notification.
+    POST — Clears specific song (or all) from queue after UI has shown it.
+    """
+    global completed_songs_queue
+
+    if request.method == 'POST':
+        song_id = request.args.get('song_id') or (request.get_json(silent=True) or {}).get('song_id')
+        if song_id:
+            completed_songs_queue = [s for s in completed_songs_queue if s['song_id'] != song_id]
+        else:
+            completed_songs_queue = []
+        return jsonify({'status': 'ok', 'cleared': True})
+
+    if completed_songs_queue:
+        return jsonify({'has_completed': True, 'songs': completed_songs_queue, 'count': len(completed_songs_queue)})
+    return jsonify({'has_completed': False, 'songs': [], 'count': 0})