How to Integrate SoundCloud API with V0

Start in V0 and describe the music player interface you want to build. A good starting point is a track listing component that shows artwork, title, and play controls, plus an embed area for the SoundCloud player. V0 will generate React components using Tailwind CSS with proper media player semantics and accessible controls. Ask for specific UI elements relevant to your use case: a sticky player bar that persists as users browse, a waveform placeholder (SoundCloud provides the actual waveform via the Widget API), track cards in a grid or list layout, and a search input. Specify the color scheme you want — many music apps use dark themes with accent colors. Make sure V0 generates loading skeleton states for the track list since API calls have latency. Ask V0 to create TypeScript interfaces for the SoundCloud track data shape so the components are fully typed from the start. Once V0 generates the components, review them in the preview to confirm the player controls look and feel right, then proceed to wire up the actual SoundCloud data.

Create a Next.js App Router route handler at app/api/soundcloud/tracks/route.ts. The SoundCloud API v2 uses your client_id as a query parameter for authentication — there is no Bearer token needed for public track fetching. The base URL is https://api.soundcloud.com. To fetch tracks from a specific user, call the /users/{user_id}/tracks endpoint. To search for tracks globally, use the /tracks endpoint with a q query parameter. The API returns an array of track objects with properties like artwork_url, title, permalink_url, duration, playback_count, and waveform_url. Your route handler should accept query parameters for userId (to fetch a specific user's tracks), query (for search), and limit for pagination. Parse the SoundCloud response and return a cleaned payload with just the fields your frontend needs — this reduces payload size and keeps your API contract clean. Add error handling for 401 (invalid client_id), 404 (user not found), and rate limit errors. SoundCloud's public API allows around 15,000 requests per day for registered apps.

1// app/api/soundcloud/tracks/route.ts
2import { NextRequest, NextResponse } from 'next/server';
3
4const SC_BASE = 'https://api.soundcloud.com';
5
6export async function GET(request: NextRequest) {
7  const { searchParams } = new URL(request.url);
8  const userId = searchParams.get('userId');
9  const query = searchParams.get('query');
10  const limit = searchParams.get('limit') || '20';
11
12  try {
13    let endpoint: string;
14
15    if (userId) {
16      endpoint = `${SC_BASE}/users/${userId}/tracks`;
17    } else if (query) {
18      endpoint = `${SC_BASE}/tracks`;
19    } else {
20      return NextResponse.json(
21        { error: 'Provide either userId or query parameter' },
22        { status: 400 }
23      );
24    }
25
26    const url = new URL(endpoint);
27    url.searchParams.set('client_id', process.env.SOUNDCLOUD_CLIENT_ID!);
28    url.searchParams.set('limit', limit);
29    if (query) url.searchParams.set('q', query);
30
31    const response = await fetch(url.toString(), {
32      next: { revalidate: 60 }, // Cache for 60 seconds
33    });
34
35    if (!response.ok) {
36      return NextResponse.json(
37        { error: `SoundCloud API error: ${response.status}` },
38        { status: response.status }
39      );
40    }
41
42    const data = await response.json();
43    const tracks = (Array.isArray(data) ? data : data.collection || []).map(
44      (track: Record<string, unknown>) => ({
45        id: track.id,
46        title: track.title,
47        artworkUrl: track.artwork_url,
48        permalinkUrl: track.permalink_url,
49        duration: track.duration,
50        playbackCount: track.playback_count,
51        waveformUrl: track.waveform_url,
52        user: {
53          username: (track.user as Record<string, unknown>)?.username,
54          avatarUrl: (track.user as Record<string, unknown>)?.avatar_url,
55        },
56      })
57    );
58
59    return NextResponse.json({ tracks });
60  } catch (error) {
61    console.error('SoundCloud tracks error:', error);
62    return NextResponse.json({ error: 'Failed to fetch tracks' }, { status: 500 });
63  }
64}

For actually playing audio, use SoundCloud's oEmbed endpoint rather than the REST API. The oEmbed endpoint at https://soundcloud.com/oembed accepts a track permalink URL and returns an HTML iframe embed code. This is the simplest way to get a playable SoundCloud player into your Next.js page without any API key — it is completely public. Create a route handler at app/api/soundcloud/embed/route.ts that accepts a track URL, calls the oEmbed endpoint, and returns the iframe HTML. Your React component can then set the iframe HTML using dangerouslySetInnerHTML or parse the src URL from the HTML string and render it as a proper React iframe element. The oEmbed endpoint supports parameters like color (hex color without #), auto_play (true/false), hide_related (true/false), show_comments (true/false), and visual (true/false — shows the waveform). Using color matching your app's theme makes the embedded player feel native. The iframe approach means SoundCloud handles all playback, DRM, and licensing — you do not need to handle audio files directly.

1// app/api/soundcloud/embed/route.ts
2import { NextRequest, NextResponse } from 'next/server';
3
4export async function GET(request: NextRequest) {
5  const trackUrl = request.nextUrl.searchParams.get('url');
6
7  if (!trackUrl) {
8    return NextResponse.json({ error: 'url parameter is required' }, { status: 400 });
9  }
10
11  try {
12    const oEmbedUrl = new URL('https://soundcloud.com/oembed');
13    oEmbedUrl.searchParams.set('url', trackUrl);
14    oEmbedUrl.searchParams.set('format', 'json');
15    oEmbedUrl.searchParams.set('color', 'ff3300'); // SoundCloud orange
16    oEmbedUrl.searchParams.set('auto_play', 'false');
17    oEmbedUrl.searchParams.set('hide_related', 'true');
18    oEmbedUrl.searchParams.set('show_comments', 'false');
19    oEmbedUrl.searchParams.set('visual', 'true');
20
21    const response = await fetch(oEmbedUrl.toString(), {
22      next: { revalidate: 3600 }, // Cache embed for 1 hour
23    });
24
25    if (!response.ok) {
26      return NextResponse.json(
27        { error: 'Failed to fetch SoundCloud embed' },
28        { status: response.status }
29      );
30    }
31
32    const data = await response.json();
33
34    return NextResponse.json({
35      html: data.html,
36      title: data.title,
37      author: data.author_name,
38      thumbnailUrl: data.thumbnail_url,
39    });
40  } catch (error) {
41    console.error('SoundCloud embed error:', error);
42    return NextResponse.json({ error: 'Embed fetch failed' }, { status: 500 });
43  }
44}

To use the SoundCloud REST API for track search and metadata fetching, you need a client_id. Register your app at https://soundcloud.com/you/apps by logging into SoundCloud and clicking 'Register a new application'. Fill in your app name, description, and the Vercel deployment URL as your homepage. Once registered, you receive a client_id. In the Vercel Dashboard, navigate to your project, then click Settings → Environment Variables. Add SOUNDCLOUD_CLIENT_ID with your client_id value. Do not add the NEXT_PUBLIC_ prefix — this keeps it server-side only. Set it for Production, Preview, and Development scopes. For the oEmbed-only use case (no track search, just embedding by URL), you do not need a client_id at all — the oEmbed endpoint is completely public. The client_id is only required for the /tracks REST API endpoint used for search and user track listings. After adding the environment variable, redeploy your project from the Vercel Dashboard to ensure the new value is available to your serverless functions.