ATS Song Creator

Generate original music tracks with vocals, instruments, and lyrics by publishing tasks to the Agent Task Service (ATS). Songs are generated by the ats-song-creator backend and returned as hosted mp3 URLs.

How It Works

1. You create a task on the song-creator ATS channel with a payload describing the song
2. The backend picks up the task, generates music using AI, and uploads the audio to cloud storage
3. You poll for completion and receive URLs to the finished mp3 files
4. Present the results to the user with playback links

Prerequisites

The ats CLI must be installed and authenticated:

npm install -g @difflabai/ats-cli
ats auth login

Payload Fields

Creating a Task

ats create "Song Title" \
  --channel song-creator \
  --type song \
  --payload '{
    "prompt": "upbeat indie pop, female vocals, acoustic guitar, bright synths, 120 bpm, key of C major, joyful and energetic",
    "lyrics": "[verse 1]\nWoke up to the morning light\nEverything is feeling right\nGot a song inside my head\nDancing out of bed\n\n[chorus]\nThis is our moment now\nSing it loud, sing it proud\nNothing gonna bring us down\nWe own this town\n\n[verse 2]\nRunning through the open streets\nEvery stranger that I meet\nGot a smile that says hello\nLet the good times flow\n\n[chorus]\nThis is our moment now\nSing it loud, sing it proud\nNothing gonna bring us down\nWe own this town\n\n[bridge]\nWhen the world gets heavy\nAnd the night feels long\nJust remember steady\nYou were born to sing this song\n\n[chorus]\nThis is our moment now\nSing it loud, sing it proud\nNothing gonna bring us down\nWe own this town\n\n[outro]\nOur moment... right now...",
    "audio_duration": 180
  }'

This returns a task ID:

Created task abc123-def456

Polling for Completion

Poll every 10 seconds until the task status is completed. Typical generation time is 30-90 seconds.

ats get TASK_ID -f json

Response while processing:

{
  "id": "abc123-def456",
  "status": "in_progress",
  "channel": "song-creator",
  "type": "song"
}

Response when complete:

{
  "id": "abc123-def456",
  "status": "completed",
  "channel": "song-creator",
  "type": "song",
  "result": {
    "urls": [
      "https://f003.backblazeb2.com/file/difflab-songs/abc123-def456/variant-0.mp3",
      "https://f003.backblazeb2.com/file/difflab-songs/abc123-def456/variant-1.mp3"
    ]
  }
}

If the task fails:

{
  "id": "abc123-def456",
  "status": "failed",
  "error": "Generation timed out"
}

Full Workflow Example

# 1. Create the song task
TASK_ID=$(ats create "Midnight Drive" \
  --channel song-creator \
  --type song \
  --payload '{
    "prompt": "synthwave, male vocals, retro synthesizers, drum machine, 100 bpm, key of A minor, nostalgic and dreamy",
    "lyrics": "[verse 1]\nNeon lights blur past my window\nEmpty road and a full moon glow\nRadio hum and the engine purrs\nMidnight drive where the city blurs\n\n[chorus]\nChasing lights on an endless highway\nLost in time going my way\nStars above and the road below\nMidnight drive, let the feeling flow\n\n[verse 2]\nShadows dance on the dashboard glass\nMemories fade but the music lasts\nTurn it up let the bass line roll\nSynthwave rhythm feeds my soul\n\n[chorus]\nChasing lights on an endless highway\nLost in time going my way\nStars above and the road below\nMidnight drive, let the feeling flow\n\n[outro]\nDriving on... into the dawn...",
    "audio_duration": 210
  }' --quiet)

# 2. Poll until complete
while true; do
  STATUS=$(ats get "$TASK_ID" -f json | jq -r '.status')
  if [ "$STATUS" = "completed" ]; then
    echo "Song ready!"
    ats get "$TASK_ID" -f json | jq '.result.urls[]'
    break
  elif [ "$STATUS" = "failed" ]; then
    echo "Generation failed"
    ats get "$TASK_ID" -f json | jq '.error'
    break
  fi
  echo "Generating... ($STATUS)"
  sleep 10
done

Prompt Tips

• The first 10 seconds matter most. The opening sets the tone for the entire track. Front-load your prompt with the most important sonic qualities.
• Be specific about genre and sub-genre. “synthwave” is better than “electronic”. “midwest emo, twinkly guitars” is better than “rock”.
• Specify vocal style. “female vocals, breathy, soft” or “male vocals, raspy, powerful belting”.
• Include tempo and key. “120 bpm, key of G major” gives the model concrete musical parameters.
• Describe the mood. “melancholic and introspective” vs “high-energy party anthem” shapes the arrangement.
• Name instruments. “acoustic guitar, upright bass, brushed drums, pedal steel” is far more effective than “country instruments”.

Lyrics Tips

• Start with a strong opener. The first line of verse 1 sets the hook. Make it vivid and immediate.
• Use structure tags. Always include [verse 1], [chorus], [verse 2], [bridge], [outro] etc. These guide the musical arrangement.
• Keep choruses repetitive. Repetition in the chorus makes the song memorable and singable.
• Contrast verse and chorus energy. Verses can be narrative and detailed; choruses should be punchy and anthemic.
• Use an outro to wind down. A short [outro] with trailing phrases (“driving on… into the dawn…”) gives a natural ending.
• Line length matters. Keep lines singable — roughly 6-12 syllables per line works well.

Output Format

The completed task returns a result object containing a urls array with 2 mp3 variants. Each variant is a different take on the same song — same lyrics and style but with variation in the musical performance.

{
  "urls": [
    "https://f003.backblazeb2.com/file/difflab-songs/{task-id}/variant-0.mp3",
    "https://f003.backblazeb2.com/file/difflab-songs/{task-id}/variant-1.mp3"
  ]
}

Present Results to User

When presenting results, use this template:

Your song “{title}” is ready!

I generated 2 variants for you to choose from:

• Variant 1: Listen
• Variant 2: Listen

Both versions follow your lyrics and style direction. Listen to each and pick your favorite — or I can generate new variants with adjusted parameters.

Song details:

• Style: {prompt summary}
• Duration: {audio_duration}s
• Lyrics structure: {number of verses, choruses, etc.}

Troubleshooting

• “ats: command not found” — Install the CLI: npm install -g @difflabai/ats-cli
• “Not authenticated” — Run ats auth login to authenticate
• Task stuck in in_progress — Generation typically takes 30-90 seconds. If it exceeds 5 minutes, the task likely failed. Check with ats get TASK_ID -f json.
• Task status failed — Check the error field. Common causes: invalid payload format, lyrics too long, or backend service temporarily unavailable. Retry with corrected payload.
• Empty urls array — This can happen if generation succeeded but upload failed. Retry by creating a new task.
• Duration limits — Maximum is 600 seconds (10 minutes). Songs over 300 seconds may have reduced quality. For best results, keep duration between 120-240 seconds.