Skip to main content
POST
/
api
/
external
/
v1
/
download-track
POST /download-track
curl --request POST \
  --url https://api.trackyard.com/api/external/v1/download-track
Download a licensed track as an MP3 file. Optionally request a smart-trimmed clip with automatic segment selection and hit point alignment. Cost: 1 credit per request License: Perpetual sync license included automatically. No additional step required.

​
Authentication

All requests require a valid API key in the Authorization header: 
Authorization: Bearer your_api_key_here

​
Request Body

​
track_id
string
required
The track ID from search results.Example: "trk_abc123"
​
duration_seconds
number
Clip length in seconds. Omit this field to download the full track.When specified, Trackyard analyzes the waveform and selects the best-sounding segment automatically.Range: 10-300 seconds Recommended minimum: 10 seconds (shorter clips may lack musical coherence)
​
hit_point_seconds
number
Offset (in seconds) where the musical peak should land. Requires duration_seconds.The algorithm finds the dominant energy peak in the track and aligns it to this offset.Use case: Sync the music’s climax to a specific moment in your video (product reveal, logo drop, title card).Range: Must be less than duration_seconds Precision: ±1 second

​
Example Requests

​
Download Full Track

curl -X POST https://api.trackyard.com/api/external/v1/download-track \
  -H "Authorization: Bearer $TRACKYARD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"track_id": "trk_abc123"}' \
  --output track.mp3

​
Download 30-Second Clip (Best Segment Auto-Selected)

curl -X POST https://api.trackyard.com/api/external/v1/download-track \
  -H "Authorization: Bearer $TRACKYARD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "track_id": "trk_abc123",
    "duration_seconds": 30
  }' \
  --output clip-30s.mp3

​
Download 22-Second Clip with Hit Point at 12 Seconds

curl -X POST https://api.trackyard.com/api/external/v1/download-track \
  -H "Authorization: Bearer $TRACKYARD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "track_id": "trk_abc123",
    "duration_seconds": 22,
    "hit_point_seconds": 12
  }' \
  --output clip-with-hit.mp3
What happens: The music’s biggest drop/hit/crescendo lands at exactly 12 seconds, perfect for syncing to a product reveal or logo drop.

​
Response

Content-Type: audio/mpeg Content-Disposition: attachment; filename="track-title.mp3" The response body is the raw MP3 audio file. No JSON wrapper.

​
Response Headers

Content-Type: audio/mpeg
Content-Disposition: attachment; filename="Digital_Sunrise.mp3"
Content-Length: 3428760
X-Track-Id: trk_abc123
X-Track-Duration: 142
X-Credits-Remaining: 486
X-RateLimit-Remaining: 7

​
How Smart Trimming Works

When you specify duration_seconds, Trackyard:
1

Analyzes the waveform

Scans the entire track for musical phrases, energy peaks, beat alignment, and tonal consistency.
2

Scores possible segments

Every potential clip is scored based on musical coherence, energy distribution, and start/end quality.
3

Selects the best segment

Returns the highest-scoring segment as a clean MP3 with no fade-outs or awkward cuts.

​
When to Use Smart Trimming

✅ Short-form content — Instagram Reels, TikToks, YouTube Shorts✅ Ads — Social media ads, pre-roll, mid-roll✅ Product demos — SaaS walkthroughs, unboxing videos✅ Trailers — App, game, or film trailers✅ Batch processing — Auto-scoring 100+ videos at scale

​
Hit Point Alignment

The hit_point_seconds parameter choreographs the music’s peak to a specific moment in your video.

​
Use Cases

Scenario: 15-second Instagram Reel, product appears at 8 secondsRequest:
{
  "track_id": "trk_xyz789",
  "duration_seconds": 15,
  "hit_point_seconds": 8
}
Result: Music peaks right when the product enters the frame.
Scenario: 30-second YouTube ad, logo reveals at 22 secondsRequest:
{
  "track_id": "trk_def456",
  "duration_seconds": 30,
  "hit_point_seconds": 22
}
Result: Musical peak aligns with the logo for maximum impact.
Scenario: 45-second app trailer, title card at 35 secondsRequest:
{
  "track_id": "trk_ghi123",
  "duration_seconds": 45,
  "hit_point_seconds": 35
}
Result: Music builds throughout, peaks at the title card.

​
What’s Included in the License

Every download includes a perpetual sync license automatically:

Perpetual License Rights

  • ✅ No expiration — Use the track forever
  • ✅ No renewals — One-time payment, no recurring fees
  • ✅ Multi-platform — Social media, YouTube, podcasts, websites
  • ✅ Worldwide — No geographic restrictions
  • ✅ Unlimited views — No caps on impressions or plays
What’s NOT included:
  • ❌ Broadcast (TV/film) — requires upgraded license tier
  • ❌ Audio resale — can’t redistribute as standalone audio
  • ❌ Sync to offensive/illegal content
See How Trackyard Works for full licensing details.

​
Error Responses

​
401 Unauthorized
Missing or invalid API key.
{
  "error": "Unauthorized",
  "message": "Invalid API key"
}
​
402 Payment Required
Out of credits.
{
  "error": "Out of credits",
  "message": "Please top up or upgrade your plan"
}
​
404 Not Found
Track ID doesn’t exist.
{
  "error": "Not Found",
  "message": "Track not found"
}
​
400 Bad Request
Invalid parameters (e.g., hit_point_seconds without duration_seconds).
{
  "error": "Bad Request",
  "message": "hit_point_seconds requires duration_seconds",
  "code": "invalid_parameters"
}
See Error Codes for full reference.

​
Tips for Best Results

Preview first: Use the preview_url from search results to audition tracks before downloading
Choose tracks with clear peaks: Electronic drops, orchestral crescendos, and hip hop hits work best for hit point alignment
Test different durations: If a 30-second clip doesn’t sound right, try 28 or 32 seconds for better segment selection
Align hit points to visual moments: Product reveals, logo drops, title cards, scene transitions

​
Next Steps

Smart Clip Trimming

Learn how automatic segment selection works

Search API

Find tracks to download

Use Cases

See hit point alignment in action

Code Examples

Python and JavaScript examples