# Flappy Dodo Audio Upload API

Modal deployment for uploading audio and generating covers with Suno Studio API.

**Deployed URL:** `https://suno-ai--flappy-dodo-audio-upload-api.modal.run`

## Endpoints

### 1. Health Check
```bash
curl https://suno-ai--flappy-dodo-audio-upload-api.modal.run/
```

### 2. Upload Audio Only
Uploads audio file and returns the processed clip.

```bash
curl -X POST https://suno-ai--flappy-dodo-audio-upload-api.modal.run/upload-audio \
  -F 'file=@./test.wav'
```

### 3. Generate Cover
Generates a cover from an existing clip ID.

```bash
curl -X POST https://suno-ai--flappy-dodo-audio-upload-api.modal.run/generate-cover \
  -H 'Content-Type: application/json' \
  -d '{"cover_clip_id": "YOUR_CLIP_ID", "style": "jazz"}'
```

### 4. Upload and Generate Covers (Combined) ⭐ RECOMMENDED

This is the main endpoint for the hackathon - it does everything in one call!

**Single style:**
```bash
curl -X POST https://suno-ai--flappy-dodo-audio-upload-api.modal.run/upload-and-cover \
  -F 'file=@./test.wav' \
  -F 'styles=marimba'
```

**Multiple styles (passed as a single comma-separated string to the tags field):**
```bash
curl -X POST https://suno-ai--flappy-dodo-audio-upload-api.modal.run/upload-and-cover \
  -F 'file=@./test.wav' \
  -F 'styles=marimba,jazz,rock'
```

Note: The `styles` parameter is passed directly to the Suno API as the `tags` field, so "marimba,jazz,rock" will generate covers with all three style influences combined.

**With pretty output (using jq):**
```bash
curl -X POST https://suno-ai--flappy-dodo-audio-upload-api.modal.run/upload-and-cover \
  -F 'file=@./test.wav' \
  -F 'styles=marimba' | jq .
```

### 5. Practice Utilities

- `GET /leaderboard?difficulty=practice` — retrieve Practice Jam leaderboard entries (offline merge aware)
- `POST /leaderboard/record` — append a new leaderboard entry and auto-trim to the top 50
- `GET /practice/hints` — curated learning tips for the practice overlays
- `GET /practice/spotlight` — rotating artist spotlight with genres, tips, and recommended challenges

## Response Format

The `/upload-and-cover` endpoint returns:

```json
{
  "success": true,
  "upload_id": "aad3f393-7541-41ce-b20c-55c499d13be3",
  "original_clip": {
    "id": "b8d9b3db-ec25-4625-b540-9f281ff8e7e3",
    "title": "Everytime",
    "status": "complete",
    "audio_url": "https://cdn1.suno.ai/b8d9b3db-ec25-4625-b540-9f281ff8e7e3.mp3",
    "image_url": "https://cdn2.suno.ai/image_b8d9b3db-ec25-4625-b540-9f281ff8e7e3.jpeg",
    "metadata": { ... }
  },
  "cover_clips": [
    {
      "id": "db99c801-a4e9-4ed6-8c1f-c41e49b4cd43",
      "title": "Everytime (Cover)",
      "status": "streaming",
      "audio_url": "https://audiopipe-dev.suno.ai/?item_id=db99c801-a4e9-4ed6-8c1f-c41e49b4cd43",
      "image_url": "https://cdn2.suno.ai/image_db99c801-a4e9-4ed6-8c1f-c41e49b4cd43.jpeg",
      "metadata": {
        "tags": "marimba,jazz,rock",
        ...
      }
    },
    {
      "id": "8c623de3-2b7b-4871-bd81-41d9a43f1ff3",
      "title": "Everytime (Cover)",
      "status": "streaming",
      "audio_url": "https://audiopipe-dev.suno.ai/?item_id=8c623de3-2b7b-4871-bd81-41d9a43f1ff3",
      "metadata": {
        "tags": "marimba,jazz,rock",
        ...
      }
    }
  ]
}
```

## Notes

- Each cover generation creates 2 clips (variations)
- Clips are returned when they reach "streaming" or "complete" status
- The endpoint polls automatically until clips are ready (up to 2 minutes)
- Supported audio formats: mp3, wav, flac, etc.

## Example Styles

Try these styles for interesting results:
- `marimba` - Percussion-heavy tropical vibes
- `jazz` - Smooth jazz interpretation
- `rock` - Rock band version
- `electronic` - EDM/electronic remix
- `classical` - Orchestral arrangement
- `acoustic` - Stripped down acoustic version
- `reggae` - Reggae rhythm
- `blues` - Blues interpretation

## Testing

Run the test script:
```bash
./test_flappy_dodo.sh
```

Or test directly:
```bash
# Quick test with your audio file
curl -X POST https://suno-ai--flappy-dodo-audio-upload-api.modal.run/upload-and-cover \
  -F 'file=@./test.wav' \
  -F 'styles=marimba'
```