POST/api/v1/media/music/search

Music Search

Search Spotify for tracks, artists, and albums. Returns names, cover art, preview URLs, and metadata.

Authentication

All Media API requests require your gyramedia_ key in the Authorization header.

Authorization: Bearer gyramedia_xxxxxxxxxxxx

Request body

{
  "q": "Wizkid Essence",
  "type": "track",
  "limit": 10
}

Example request

curl

curl -X POST https://gyra.ng/api/v1/media/music/search \
  -H "Authorization: Bearer gyramedia_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
  "q": "Wizkid Essence",
  "type": "track",
  "limit": 10
}'

Response

application/json

{
  "query": "Wizkid Essence",
  "type": "track",
  "count": 10,
  "results": [
    {
      "id": "5p1OvDeMBBMWvGj9xTa0VY",
      "name": "Essence",
      "artists": "Wizkid, Tems",
      "album": "Made in Lagos",
      "coverArt": "https://i.scdn.co/image/...",
      "previewUrl": "https://p.scdn.co/mp3-preview/...",
      "durationMs": 248000,
      "externalUrl": "https://open.spotify.com/track/..."
    }
  ],
  "balanceAfter": 4.10
}

Error codes

invalid_api_keyMissing or revoked key

401

wrong_categoryKey is not a media key

403

insufficient_creditsWallet balance too low

402

rate_limitedToo many requests per minute

429

invalid_requestMissing or invalid parameters

400

provider_errorUpstream provider failed

502

no_transcriptVideo has no captions

404