DEV Community: yan zhiyu

Build a Text-to-Song Web App with the Suno API (Lyrics In, Full Song Out)

yan zhiyu — Tue, 05 May 2026 03:05:14 +0000

You type a few lines of lyrics. You hit a button. Thirty seconds later, a complete song plays back — vocals, melody, instrumentation, the works.

That's what we're building in this tutorial: a minimal but fully functional text-to-song web app powered by the Suno API. Users paste in their own lyrics, pick a style, and get back a real AI-generated song with vocals.

What we're building:

A Next.js app with a simple two-field form: lyrics input + style tags
A backend API route that submits to Suno and polls for results
A frontend that streams status updates and plays the finished song inline

Time to complete: ~30 minutes

Stack: Next.js 14 (App Router), Node.js, Suno API via TTAPI

Prerequisites: Node.js 18+, a free TTAPI account

Why the Suno API for Lyrics-to-Song?

Most AI music tools treat lyrics as optional. Suno's custom mode does the opposite — you supply the exact lyrics, and the model builds the vocal melody, arrangement, and instrumentation around them. This makes it genuinely useful for:

Songwriters who want to hear a demo of their lyrics without recording anything
Content creators who want a branded jingle from a script
Developers building creative tools where the user's words become a song

The key parameter is custom: true combined with a structured prompt that contains your lyrics with section tags like [Verse], [Chorus], and [Bridge].

Full API reference: TTAPI Suno API Documentation

How the Suno Custom Lyrics Mode Works

Before writing code, it helps to understand the data flow:

User types lyrics + style tags
        ↓
POST /suno/v1/music   (custom: true)
        ↓
{ jobId: "abc123" }   (immediate response)
        ↓
GET /suno/v2/fetch?jobId=abc123   (poll every 5s)
        ↓
{ status: "SUCCESS", musics: [{ audioUrl: "..." }] }
        ↓
<audio> tag plays the result

The Suno API is fully asynchronous — you never get the audio URL in the first response. You always store the jobId and fetch results separately. For more on this pattern, see the Suno API Async Workflow.

Step 1 — Project Setup

npx create-next-app@latest text-to-song --app --no-tailwind --no-src-dir
cd text-to-song
npm install

Create a .env.local file in the project root:

TTAPI_KEY=your_api_key_here

Get your key from ttapi.io after signing up.

Step 2 — The Backend API Route

We need two API routes:

POST /api/generate — submits the lyrics to Suno and returns a jobId
GET /api/result?jobId=xxx — fetches the job status and returns the audio URL when ready

Create app/api/generate/route.js:

const BASE_URL = 'https://api.ttapi.io';

export async function POST(request) {
  const { lyrics, tags, title } = await request.json();

  if (!lyrics || lyrics.trim().length < 10) {
    return Response.json(
      { error: 'Lyrics must be at least 10 characters.' },
      { status: 400 }
    );
  }

  const response = await fetch(`${BASE_URL}/suno/v1/music`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'TT-API-KEY': process.env.TTAPI_KEY,
    },
    body: JSON.stringify({
      custom: true,           // use the user's exact lyrics
      instrumental: false,    // we want vocals
      mv: 'chirp-v5',         // latest Suno v5 model
      title: title || 'My Song',
      tags: tags || 'pop, emotional, female vocal',
      prompt: lyrics,         // lyrics go here, with [Verse]/[Chorus] tags
    }),
  });

  const data = await response.json();

  if (data.status !== 'SUCCESS') {
    return Response.json(
      { error: `Suno submission failed: ${data.message}` },
      { status: 500 }
    );
  }

  return Response.json({ jobId: data.data.jobId });
}

Now create app/api/result/route.js:

const BASE_URL = 'https://api.ttapi.io';

export async function GET(request) {
  const { searchParams } = new URL(request.url);
  const jobId = searchParams.get('jobId');

  if (!jobId) {
    return Response.json({ error: 'jobId is required' }, { status: 400 });
  }

  const response = await fetch(
    `${BASE_URL}/suno/v2/fetch?jobId=${jobId}`,
    {
      headers: { 'TT-API-KEY': process.env.TTAPI_KEY },
    }
  );

  const data = await response.json();

  // Still processing
  if (data.status === 'ON_QUEUE' || data.status === 'PROCESSING') {
    return Response.json({ status: 'pending' });
  }

  // Done
  if (data.status === 'SUCCESS' && data.data?.musics?.length > 0) {
    const track = data.data.musics[0];
    return Response.json({
      status: 'done',
      audioUrl: track.audioUrl,
      title: track.title,
      duration: Math.round(track.duration),
      imageUrl: track.imageUrl,
    });
  }

  // Failed
  return Response.json(
    { status: 'failed', error: data.message || 'Generation failed.' },
    { status: 500 }
  );
}

Step 3 — The Frontend

Replace the contents of app/page.js with:

'use client';

import { useState, useRef } from 'react';

const STYLE_PRESETS = [
  { label: 'Pop (Female vocal)', value: 'pop, emotional, female vocal, melodic' },
  { label: 'Hip-Hop', value: 'hip-hop, rap, trap beat, male vocal' },
  { label: 'Indie Folk', value: 'indie folk, acoustic guitar, soft vocal, warm' },
  { label: 'R&B', value: 'r&b, soul, smooth, female vocal, slow' },
  { label: 'Rock', value: 'rock, electric guitar, powerful vocal, energetic' },
  { label: 'Custom...', value: 'custom' },
];

const LYRICS_PLACEHOLDER = `[Verse]
Write your first verse here
Each line becomes part of the song
The AI will build a melody around your words

[Chorus]
This is the hook that repeats
Make it catchy and easy to sing
Your chorus will shine through

[Verse 2]
Second verse continues the story
More detail, more emotion here

[Chorus]
This is the hook that repeats
Make it catchy and easy to sing
Your chorus will shine through`;

export default function Home() {
  const [lyrics, setLyrics] = useState('');
  const [title, setTitle] = useState('');
  const [selectedPreset, setSelectedPreset] = useState(STYLE_PRESETS[0].value);
  const [customTags, setCustomTags] = useState('');
  const [status, setStatus] = useState('idle'); // idle | submitting | pending | done | failed
  const [result, setResult] = useState(null);
  const [error, setError] = useState('');
  const pollTimer = useRef(null);

  const tags = selectedPreset === 'custom' ? customTags : selectedPreset;

  async function handleGenerate() {
    if (!lyrics.trim()) {
      setError('Please enter some lyrics first.');
      return;
    }

    setError('');
    setResult(null);
    setStatus('submitting');

    // Submit the job
    const submitRes = await fetch('/api/generate', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ lyrics, tags, title }),
    });

    const submitData = await submitRes.json();

    if (!submitRes.ok) {
      setError(submitData.error || 'Submission failed.');
      setStatus('failed');
      return;
    }

    const { jobId } = submitData;
    setStatus('pending');

    // Start polling
    pollTimer.current = setInterval(async () => {
      const pollRes = await fetch(`/api/result?jobId=${jobId}`);
      const pollData = await pollRes.json();

      if (pollData.status === 'done') {
        clearInterval(pollTimer.current);
        setResult(pollData);
        setStatus('done');
      } else if (pollData.status === 'failed') {
        clearInterval(pollTimer.current);
        setError(pollData.error || 'Generation failed.');
        setStatus('failed');
      }
      // if 'pending', keep polling
    }, 5000);
  }

  function handleReset() {
    clearInterval(pollTimer.current);
    setStatus('idle');
    setResult(null);
    setError('');
  }

  return (
    <main style={styles.main}>
      <h1 style={styles.h1}>Text to Song</h1>
      <p style={styles.subtitle}>
        Paste your lyrics, pick a style, and get a full AI-generated song in ~30 seconds.
      </p>

      {/* Song title */}
      <label style={styles.label}>Song Title</label>
      <input
        style={styles.input}
        type="text"
        placeholder="My Song"
        value={title}
        onChange={(e) => setTitle(e.target.value)}
        disabled={status !== 'idle'}
      />

      {/* Style picker */}
      <label style={styles.label}>Style</label>
      <div style={styles.presetGrid}>
        {STYLE_PRESETS.map((preset) => (
          <button
            key={preset.value}
            style={{
              ...styles.presetBtn,
              ...(selectedPreset === preset.value ? styles.presetBtnActive : {}),
            }}
            onClick={() => setSelectedPreset(preset.value)}
            disabled={status !== 'idle'}
          >
            {preset.label}
          </button>
        ))}
      </div>

      {selectedPreset === 'custom' && (
        <input
          style={styles.input}
          type="text"
          placeholder="e.g. jazz, saxophone, melancholic, slow"
          value={customTags}
          onChange={(e) => setCustomTags(e.target.value)}
          disabled={status !== 'idle'}
        />
      )}

      {/* Lyrics input */}
      <label style={styles.label}>
        Lyrics{' '}
        <span style={styles.hint}>
          Use [Verse], [Chorus], [Bridge] section tags for best results
        </span>
      </label>
      <textarea
        style={styles.textarea}
        placeholder={LYRICS_PLACEHOLDER}
        value={lyrics}
        onChange={(e) => setLyrics(e.target.value)}
        disabled={status !== 'idle'}
        rows={14}
      />

      {/* Error */}
      {error && <p style={styles.error}>{error}</p>}

      {/* Generate button */}
      {status === 'idle' || status === 'failed' ? (
        <button style={styles.btn} onClick={handleGenerate}>
          Generate Song
        </button>
      ) : status === 'submitting' ? (
        <button style={{ ...styles.btn, ...styles.btnDisabled }} disabled>
          Submitting...
        </button>
      ) : status === 'pending' ? (
        <button style={{ ...styles.btn, ...styles.btnDisabled }} disabled>
          Generating… (this takes ~30s)
        </button>
      ) : null}

      {/* Result */}
      {status === 'done' && result && (
        <div style={styles.resultCard}>
          {result.imageUrl && (
            <img src={result.imageUrl} alt={result.title} style={styles.coverArt} />
          )}
          <h2 style={styles.trackTitle}>{result.title}</h2>
          <p style={styles.trackMeta}>{result.duration}s · {tags}</p>
          <audio controls src={result.audioUrl} style={styles.player} />
          <div style={styles.resultActions}>
            <a href={result.audioUrl} download style={styles.downloadBtn}>
              Download MP3
            </a>
            <button style={styles.resetBtn} onClick={handleReset}>
              Generate Another
            </button>
          </div>
        </div>
      )}
    </main>
  );
}

const styles = {
  main: {
    maxWidth: 680,
    margin: '0 auto',
    padding: '48px 24px',
    fontFamily: '-apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif',
    color: '#111',
  },
  h1: { fontSize: 32, fontWeight: 700, marginBottom: 8 },
  subtitle: { color: '#555', marginBottom: 32, lineHeight: 1.5 },
  label: { display: 'block', fontWeight: 600, marginBottom: 8, marginTop: 24 },
  hint: { fontWeight: 400, color: '#888', fontSize: 13 },
  input: {
    width: '100%',
    padding: '10px 14px',
    fontSize: 15,
    border: '1px solid #ddd',
    borderRadius: 8,
    boxSizing: 'border-box',
    outline: 'none',
  },
  textarea: {
    width: '100%',
    padding: '12px 14px',
    fontSize: 14,
    fontFamily: 'monospace',
    border: '1px solid #ddd',
    borderRadius: 8,
    boxSizing: 'border-box',
    resize: 'vertical',
    lineHeight: 1.6,
  },
  presetGrid: { display: 'flex', flexWrap: 'wrap', gap: 8, marginBottom: 4 },
  presetBtn: {
    padding: '8px 14px',
    borderRadius: 20,
    border: '1px solid #ddd',
    background: '#fff',
    cursor: 'pointer',
    fontSize: 13,
  },
  presetBtnActive: {
    background: '#111',
    color: '#fff',
    borderColor: '#111',
  },
  btn: {
    marginTop: 24,
    width: '100%',
    padding: '14px',
    background: '#111',
    color: '#fff',
    border: 'none',
    borderRadius: 8,
    fontSize: 16,
    fontWeight: 600,
    cursor: 'pointer',
  },
  btnDisabled: { background: '#888', cursor: 'not-allowed' },
  error: { color: '#c00', marginTop: 12, fontSize: 14 },
  resultCard: {
    marginTop: 32,
    padding: 24,
    border: '1px solid #eee',
    borderRadius: 12,
    background: '#fafafa',
  },
  coverArt: { width: '100%', borderRadius: 8, marginBottom: 16 },
  trackTitle: { fontSize: 22, fontWeight: 700, margin: '0 0 4px' },
  trackMeta: { color: '#888', fontSize: 13, marginBottom: 16 },
  player: { width: '100%', marginBottom: 16 },
  resultActions: { display: 'flex', gap: 12 },
  downloadBtn: {
    flex: 1,
    padding: '10px 0',
    background: '#111',
    color: '#fff',
    textAlign: 'center',
    borderRadius: 8,
    textDecoration: 'none',
    fontWeight: 600,
    fontSize: 14,
  },
  resetBtn: {
    flex: 1,
    padding: '10px 0',
    background: '#fff',
    border: '1px solid #ddd',
    borderRadius: 8,
    fontWeight: 600,
    fontSize: 14,
    cursor: 'pointer',
  },
};

Step 4 — Run It

npm run dev

Open http://localhost:3000. You'll see:

A title field
Style preset buttons (Pop, Hip-Hop, Indie Folk, R&B, Rock, Custom)
A lyrics textarea with section tag guidance
A Generate button

Paste in some lyrics with [Verse] and [Chorus] tags, hit Generate, and wait ~30 seconds. The result card appears with cover art, an inline audio player, and a download button.

Lyrics Formatting Guide

The prompt field in custom mode is where your lyrics go. Suno reads section tags to understand song structure. Here's what works:

Tag	What it does
`[Verse]`	Standard verse section
`[Chorus]`	Repeated hook — use identical text each time for a real chorus
`[Bridge]`	Contrasting mid-section, usually appears once
`[Intro]`	Opening instrumental or vocal section
`[Outro]`	Closing section
`[Pre-Chorus]`	Build-up before the chorus

Formatting tips:

Repeat the [Chorus] block verbatim 2–3 times in the prompt — Suno will recognize it as a repeating section
Keep lines short (4–8 words). Long lines get cut off or rushed
Avoid special characters, emoji, or punctuation-heavy lines
The more natural the line rhythm, the better the vocal melody

Example prompt structure:

[Verse]
Walking down an empty street
Rain against the windowpane
Everything I thought I'd keep
Slowly washing down the drain

[Chorus]
Let it go, let it go
Nothing left to hold on to
Let it go, let it go
I was never meant for you

[Verse 2]
Found your jacket on the chair
Packed it up without a word
Left the key beneath the stair
Said the things that went unheard

[Chorus]
Let it go, let it go
Nothing left to hold on to
Let it go, let it go
I was never meant for you

[Bridge]
Maybe someday I'll look back
See this moment for what it was
No regret and no attack
Just the end of what once was

[Chorus]
Let it go, let it go
Nothing left to hold on to
Let it go, let it go
I was never meant for you

Style Tags Reference

The tags field defines the musical feel. Some combinations that produce strong results:

Genre	Tags
Emotional pop	`pop, emotional, female vocal, piano, melodic`
Hip-hop	`hip-hop, trap, 808, male vocal, punchy`
Indie folk	`indie folk, acoustic guitar, warm, soft vocal`
R&B / soul	`r&b, soul, smooth, female vocal, minor key`
Rock anthem	`rock, electric guitar, powerful, male vocal, stadium`
Country	`country, storytelling, acoustic, twang, heartfelt`
Jazz vocal	`jazz, upright bass, brushed drums, female vocal, intimate`

Mix 4–6 tags for best results. Avoid contradictory combinations like fast + slow or male vocal + female vocal.

Step 5 — Deploying to Vercel

The app is ready to deploy as-is:

npm install -g vercel
vercel

When prompted, add your environment variable:

TTAPI_KEY=your_api_key_here

Vercel will give you a live URL in under a minute.

One thing to note: Next.js API routes have a default 10-second timeout on Vercel's Hobby plan. Our polling is done client-side (the browser polls /api/result every 5 seconds), so this isn't a problem — each individual API call completes well within the limit.

Going Further

Webhook instead of polling

For a production app, replace the client-side polling loop with a server-side webhook. Pass a hookUrl pointing to a new API route when submitting the job:

body: JSON.stringify({
  custom: true,
  instrumental: false,
  mv: 'chirp-v5',
  title,
  tags,
  prompt: lyrics,
  hookUrl: `${process.env.NEXT_PUBLIC_BASE_URL}/api/webhook`,
}),

Then handle the inbound POST in /api/webhook/route.js and push the result to your frontend via a websocket or server-sent event. See Suno API Async Workflow for the full webhook payload shape.

Generate lyrics first

If your users want help writing the lyrics before generating the song, use the Suno Lyrics API to generate structured lyrics from a topic, then feed the result directly into the music generation step.

Extend the track

Suno's default generation is around 2–3 minutes. To produce a longer version, take the musicId from the result and pass it to the Suno Extend API:

body: JSON.stringify({
  defaultParamFlag: 1,
  musicId: track.musicId,
  continueAt: track.duration - 5, // overlap last 5 seconds
})

Stems separation

After generation, use the Suno Stems API to split the track into a vocal stem and an instrumental stem — useful if users want to download just the acapella or just the backing track.

Complete File Structure

text-to-song/
├── app/
│   ├── api/
│   │   ├── generate/
│   │   │   └── route.js      ← submits to Suno API
│   │   └── result/
│   │       └── route.js      ← polls for job result
│   ├── page.js               ← full UI
│   └── layout.js             ← default Next.js layout
├── .env.local                ← TTAPI_KEY goes here
└── package.json

Resources

Suno API Full Documentation — complete endpoint reference and parameter guide
Suno API Quickstart — get your first song in 5 minutes
Suno Music API Reference — all parameters for the generation endpoint
Suno Lyrics API — generate lyrics before music
Suno Extend API — make a track longer
Suno Stems API — separate vocals and instrumentals
Suno API Async Workflow — polling vs webhooks explained

What did you build with this? Share your app or a generated track in the comments.

How to Build an AI Background Music Generator with the Suno API (For Videos & Podcasts)

yan zhiyu — Mon, 04 May 2026 05:55:36 +0000

Every video creator and podcaster knows the pain: you need background music that fits the mood, isn't copyrighted, and doesn't cost $50/track from a stock library. What if you could generate a custom, royalty-free track from a single text prompt in under 30 seconds?

In this tutorial, you'll build a lightweight AI background music generator using the Suno API via TTAPI. By the end, you'll have a working Node.js app that accepts a mood description and returns a downloadable .mp3 — ready to drop into your video editor or podcast software.

What we're building:

A Node.js script that takes a prompt like "calm lo-fi piano, no vocals, for a study vlog"
Submits it to the Suno API
Polls for the result
Downloads the generated .mp3 automatically

Time to complete: ~20 minutes

Prerequisites: Node.js 18+, a free TTAPI account

Why Suno API for Background Music?

Most AI music tools are consumer-facing. The Suno API gives you programmatic access to the same generation engine — meaning you can automate it, batch it, and integrate it into your own tools.

For background music specifically, the API shines because:

You can set "instrumental": true to get clean, vocal-free tracks every time
The tags parameter gives you precise genre and mood control
The async workflow means you can fire off a request and do other things while it generates
Generated audio is yours to use — no per-track licensing fees on top of API costs

The full API reference lives at TTAPI Suno API Documentation.

Step 1 — Get Your API Key

Sign up at ttapi.io
Navigate to your dashboard and copy your TT-API-KEY
Keep it handy — you'll add it to a .env file shortly

Step 2 — Project Setup

Create a new directory and initialize the project:

mkdir suno-bg-music && cd suno-bg-music
npm init -y
npm install node-fetch dotenv

Create a .env file:

TTAPI_KEY=your_api_key_here

Create the main file:

touch generate.js

Your project structure should look like this:

suno-bg-music/
├── generate.js
├── .env
├── package.json
└── output/        ← mp3s will be saved here

Create the output folder:

mkdir output

Step 3 — Submit a Music Generation Request

The Suno API works asynchronously. You submit a request, get back a jobId, then poll a separate endpoint to retrieve the result when it's ready.

Here's the full generation function. Open generate.js and add:

import fetch from 'node-fetch';
import fs from 'fs';
import path from 'path';
import { createWriteStream } from 'fs';
import { pipeline } from 'stream/promises';
import 'dotenv/config';

const API_KEY = process.env.TTAPI_KEY;
const BASE_URL = 'https://api.ttapi.io';

// Step 1: Submit the generation job
async function generateMusic(prompt, tags) {
  const response = await fetch(`${BASE_URL}/suno/v1/music`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'TT-API-KEY': API_KEY,
    },
    body: JSON.stringify({
      custom: false,        // let Suno handle the lyrics/structure
      instrumental: true,   // no vocals — clean background music
      mv: 'chirp-v5',       // latest Suno v5 model
      prompt: prompt,
      tags: tags,
    }),
  });

  const data = await response.json();

  if (data.status !== 'SUCCESS') {
    throw new Error(`Submission failed: ${JSON.stringify(data)}`);
  }

  console.log(`✅ Job submitted. jobId: ${data.data.jobId}`);
  return data.data.jobId;
}

Key parameters explained:

instrumental: true — this is the most important setting for background music. It tells Suno to generate a clean track with no vocals.
mv: 'chirp-v5' — always use the latest model for the best output quality.
custom: false — since we're generating instrumental music, we don't need to supply lyrics.
tags — this is where you define the sound. Think of it as your style brief to the AI.

Step 4 — Poll for the Result

After submitting, the job takes 60–120 seconds to complete. We'll poll the fetch endpoint every 10 seconds until the status flips to SUCCESS:

// Step 2: Poll until the job is complete
async function pollForResult(jobId, intervalMs = 10000, maxAttempts = 24) {
  console.log('⏳ Waiting for generation to complete...');

  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
    await new Promise((resolve) => setTimeout(resolve, intervalMs));

    const response = await fetch(
      `${BASE_URL}/suno/v2/fetch?jobId=${jobId}`,
      {
        headers: { 'TT-API-KEY': API_KEY },
      }
    );

    const data = await response.json();

    if (data.status === 'SUCCESS' && data.data?.musics?.length > 0) {
      console.log(`✅ Generation complete after ${attempt} poll(s).`);
      return data.data.musics[0]; // return the first track
    }

    if (data.status === 'FAILED') {
      throw new Error(`Job failed: ${JSON.stringify(data)}`);
    }

    console.log(`   Attempt ${attempt}/${maxAttempts} — status: ${data.status}`);
  }

  throw new Error('Timed out waiting for generation result.');
}

The fetch response includes audioUrl, videoUrl, title, duration, and more. For background music, we only need audioUrl.

Step 5 — Download the MP3

// Step 3: Download the generated mp3
async function downloadMp3(audioUrl, filename) {
  const outputPath = path.join('output', filename);
  const response = await fetch(audioUrl);

  if (!response.ok) {
    throw new Error(`Failed to download audio: ${response.statusText}`);
  }

  await pipeline(response.body, createWriteStream(outputPath));
  console.log(`💾 Saved to: ${outputPath}`);
  return outputPath;
}

Step 6 — Wire It All Together

Add the main function at the bottom of generate.js:

async function main() {
  // --- Configure your track here ---
  const prompt = 'calm background music for a study vlog, no distractions';
  const tags = 'lo-fi, piano, ambient, instrumental, slow, soft';
  // ----------------------------------

  try {
    const jobId = await generateMusic(prompt, tags);
    const track = await pollForResult(jobId);

    const safeTitle = track.title.replace(/[^a-z0-9]/gi, '_').toLowerCase();
    const filename = `${safeTitle}_${Date.now()}.mp3`;

    await downloadMp3(track.audioUrl, filename);

    console.log('\n🎵 Track details:');
    console.log(`   Title:    ${track.title}`);
    console.log(`   Duration: ${Math.round(track.duration)}s`);
    console.log(`   Tags:     ${track.tags}`);
  } catch (err) {
    console.error('❌ Error:', err.message);
    process.exit(1);
  }
}

main();

Step 7 — Run It

Add "type": "module" to your package.json to enable ES module imports:

{
  "type": "module",
  ...
}

Then run:

node generate.js

Expected output:

✅ Job submitted. jobId: a3f9b2c1...
⏳ Waiting for generation to complete...
   Attempt 1/24 — status: ON_QUEUE
   Attempt 2/24 — status: ON_QUEUE
   Attempt 3/24 — status: ON_QUEUE
✅ Generation complete after 4 poll(s).
💾 Saved to: output/calm_study_vlog_1714812345678.mp3

🎵 Track details:
   Title:    Calm Study Vlog
   Duration: 187s
   Tags:     lo-fi, piano, ambient, instrumental, slow, soft

Open the output/ folder and you'll find your generated .mp3, ready to import into DaVinci Resolve, Premiere, GarageBand, or any podcast editor.

Prompt & Tags Reference for Background Music

The tags parameter is your primary control over the sound. Here are some combinations that work well for common use cases:

Use Case	`prompt`	`tags`
Study / focus vlog	`"calm background for a study session"`	`"lo-fi, piano, ambient, instrumental, 80bpm"`
Tech / product demo	`"upbeat background for a software demo video"`	`"electronic, upbeat, corporate, instrumental, clean"`
Travel vlog	`"adventurous background music for a travel montage"`	`"cinematic, orchestral, instrumental, epic, wide"`
Podcast intro	`"short energetic intro for a tech podcast"`	`"electronic, punchy, upbeat, instrumental, intro"`
Meditation / wellness	`"peaceful background for a meditation video"`	`"ambient, drone, nature sounds, soft, slow"`
Gaming / action	`"intense background for a gaming highlight reel"`	`"electronic, intense, fast, instrumental, driving"`

Tips:

Keep tags to 4–6 descriptors. Too many can confuse the model.
BPM hints like "80bpm" or "120bpm" are respected but not guaranteed.
"instrumental" in tags reinforces the instrumental: true parameter — use both.
For very short clips (intros/outros), add "short" or "30 seconds" to the tags.

Going Further: Batch Generation

Need multiple options to choose from? Here's a quick wrapper to generate several variations in parallel:

async function generateBatch(variations) {
  const jobs = await Promise.all(
    variations.map(({ prompt, tags }) => generateMusic(prompt, tags))
  );

  const results = await Promise.all(jobs.map(pollForResult));

  for (const [i, track] of results.entries()) {
    const filename = `variation_${i + 1}_${Date.now()}.mp3`;
    await downloadMp3(track.audioUrl, filename);
  }
}

// Usage:
generateBatch([
  { prompt: 'calm lo-fi for a study vlog', tags: 'lo-fi, piano, ambient, instrumental' },
  { prompt: 'upbeat version of a study vlog theme', tags: 'electronic, upbeat, instrumental' },
  { prompt: 'cinematic version for a study vlog', tags: 'cinematic, orchestral, instrumental' },
]);

This fires all three jobs simultaneously, then downloads each result as it completes.

What to Build Next

With this foundation in place, here are some natural next steps:

Web UI — wrap the script in an Express endpoint and build a simple frontend where creators paste a description and get a download link
Webhook support — instead of polling, pass a hookUrl to your server and handle the callback; better for production workloads
Extend a track — use the Suno Extend API to lengthen a generated track beyond its default duration
Stems separation — use the Suno Stems API to split a generated track into vocals and instrumentals for further editing
Auto-match to video — read the duration of a video file with ffprobe, then pass that duration as a target to the generation prompt

Full Code

The complete generate.js file:

import fetch from 'node-fetch';
import path from 'path';
import { createWriteStream } from 'fs';
import { pipeline } from 'stream/promises';
import 'dotenv/config';

const API_KEY = process.env.TTAPI_KEY;
const BASE_URL = 'https://api.ttapi.io';

async function generateMusic(prompt, tags) {
  const response = await fetch(`${BASE_URL}/suno/v1/music`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'TT-API-KEY': API_KEY,
    },
    body: JSON.stringify({
      custom: false,
      instrumental: true,
      mv: 'chirp-v5',
      prompt,
      tags,
    }),
  });

  const data = await response.json();
  if (data.status !== 'SUCCESS') throw new Error(`Submission failed: ${JSON.stringify(data)}`);
  console.log(`✅ Job submitted. jobId: ${data.data.jobId}`);
  return data.data.jobId;
}

async function pollForResult(jobId, intervalMs = 5000, maxAttempts = 24) {
  console.log('⏳ Waiting for generation to complete...');
  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
    await new Promise((r) => setTimeout(r, intervalMs));
    const response = await fetch(`${BASE_URL}/suno/v2/fetch?jobId=${jobId}`, {
      headers: { 'TT-API-KEY': API_KEY },
    });
    const data = await response.json();
    if (data.status === 'SUCCESS' && data.data?.musics?.length > 0) {
      console.log(`✅ Done after ${attempt} poll(s).`);
      return data.data.musics[0];
    }
    if (data.status === 'FAILED') throw new Error(`Job failed: ${JSON.stringify(data)}`);
    console.log(`   Attempt ${attempt}/${maxAttempts} — status: ${data.status}`);
  }
  throw new Error('Timed out.');
}

async function downloadMp3(audioUrl, filename) {
  const outputPath = path.join('output', filename);
  const response = await fetch(audioUrl);
  if (!response.ok) throw new Error(`Download failed: ${response.statusText}`);
  await pipeline(response.body, createWriteStream(outputPath));
  console.log(`💾 Saved to: ${outputPath}`);
  return outputPath;
}

async function main() {
  const prompt = 'calm background music for a study vlog, no distractions';
  const tags = 'lo-fi, piano, ambient, instrumental, slow, soft';

  const jobId = await generateMusic(prompt, tags);
  const track = await pollForResult(jobId);
  const filename = `${track.title.replace(/[^a-z0-9]/gi, '_').toLowerCase()}_${Date.now()}.mp3`;
  await downloadMp3(track.audioUrl, filename);

  console.log(`\n🎵 ${track.title} — ${Math.round(track.duration)}s`);
}

main().catch((err) => { console.error('❌', err.message); process.exit(1); });

Resources

Suno API Full Documentation — complete endpoint reference, parameters, and workflow guides
Suno API Quickstart — get your first track in 5 minutes
Suno API Async Workflow — deep dive on polling vs webhooks
Suno Extend API — lengthen any generated track
Suno Stems API — separate vocals and instrumentals

Built something with this? Drop it in the comments — always interested to see what people ship with generative audio.

How to use the Midjourney API in your program

yan zhiyu — Tue, 30 Sep 2025 06:39:37 +0000

Unlocking MidJourney via TTAPI: A Practical Guide for Global Creators

Artificial Intelligence is reshaping the creative industry at lightning speed. Among all generative tools, MidJourney has become a favorite for designers, marketers, and creators looking to transform text prompts into breathtaking images.

But while MidJourney itself has traditionally been Discord-based, the TTAPI platform now provides a seamless way to integrate MidJourney’s image generation into your own products, workflows, and applications.

This article walks you through:

Why TTAPI is the smart choice for international developers
How to get started with MidJourney API calls through TTAPI
A hands-on Python code sample you can use today

Why TTAPI for MidJourney?

Unlike the Discord-only workflow, TTAPI enables:

Direct API Access – Call MidJourney in the same way you’d call any RESTful service.
Scalability – Queue, manage, and retrieve generations at scale for apps, SaaS, or production pipelines.
Flexibility – Integrate with your backend (Python, Node.js, Java, etc.) or even no-code tools.
Global Reach – Optimized infrastructure ensures fast response times, even across continents.

Making Your First MidJourney API Call with TTAPI

Below is a simple Python 3 example showing how to generate an image using MidJourney via TTAPI.

import requests

def main():
    url = "https://api.ttapi.io/midjourney/v1/imagine"
    headers = {
        "TT-API-KEY": "your_ttapi_api_key",  # Replace with your TTAPI API key
        "Content-Type": "application/json"
    }

    payload = {
        "prompt": "A futuristic city skyline at sunset, ultra realistic, cyberpunk style",
        "model": "fast"
    }

    response = requests.post(url, headers=headers, json=payload)

    if response.status_code == 200:
        data = response.json()
        print(data)
    else:
        print("Error:", response.status_code, response.text)

if __name__ == "__main__":
    main()

generate response:

{
    "status": "SUCCESS",
    "message": "success",
    "data": {
        "jobId": "1b3db557-f35c-4180-90cd-e6bfb0361955"
    }
}

If the request is successful, the jobId will be returned. Use the jobId to call the fetch query interface to obtain the generated image.For more information, see the TTAPI documentation.

import requests

def main():
    url = "https://api.ttapi.io/midjourney/v1/fetch"

    headers = {
        "TT-API-KEY": "your_ttapi_api_key",  # Replace with your TTAPI API key
    }

    params = {
        "jobId": "your_jobId"
    }

    response = requests.get(url, headers=headers, params=params)

    if response.status_code == 200:
        data = response.json()
        print(data)
    else:
        print("Error:", response.status_code, response.text)

How it works:

TT-API-KEY → Your API key in TTAPI used for request authorization.
prompt → The text description guiding MidJourney.
model → The task mode for generating images, including fast, relax and turbo.

Going Further

Once you master basic calls, TTAPI allows you to:

Generate variations of an existing image
Upscale results for higher resolution
Extend images beyond their original boundaries (outpainting)
Chain tasks with your business logic (e.g., auto-generate visuals for blog posts, ads, or e-commerce listings)

Final Thoughts

With TTAPI, the power of MidJourney moves beyond Discord and becomes a tool you can directly embed into your products and creative pipelines. Whether you’re building a SaaS platform, enriching marketing workflows, or simply exploring your imagination, TTAPI gives you a professional, scalable gateway to MidJourney’s AI art engine.

👉 Ready to try? Visit ttapi.io and start integrating MidJourney into your projects today.