Hayai Music API

Access thousands of AI-generated, copyright-free music tracks programmatically. Stream audio, search by genre or mood, and integrate music into your applications with our RESTful API.

Base URL

https://music.hayai.tech/api/v1

Authentication

All API requests require authentication via a Bearer token in the Authorization header. You can generate API keys from the Developer Portal.

Example Request

curl https://music.hayai.tech/api/v1/tracks \
  -H "Authorization: Bearer sk_live_your_key_here"

Keep your API keys secret. Do not expose them in client-side code, public repositories, or browser requests. Use server-side proxying instead.

Rate Limits

The API enforces a default rate limit of 1,000 requests per 24-hour rolling window per API key. Rate limit information is included in every response via headers.

Header	Description
`X-RateLimit-Limit`	Total requests allowed in the window
`X-RateLimit-Remaining`	Remaining requests in current window
`X-RateLimit-Reset`	Window reset time (ISO 8601)

Errors

The API uses conventional HTTP status codes. All error responses include a consistent JSON body with success: false and a human-readable message.

Code	Meaning
`400`	Bad Request — Invalid parameters
`401`	Unauthorized — Missing or invalid API key
`404`	Not Found — Resource does not exist
`429`	Too Many Requests — Rate limit exceeded
`500`	Internal Server Error

Error Response

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or expired API key."
  }
}

Endpoints

GET/api/v1/tracks

List Tracks

Retrieve a paginated list of published tracks. Supports filtering by genre and mood, and sorting by newest or most popular.

Query Parameters

Parameter	Type	Required	Description
`page`	integer	Optional	Page number (default: 1)
`limit`	integer	Optional	Results per page, max 50 (default: 20)
`genre`	string	Optional	Filter by genre slug
`mood`	string	Optional	Filter by mood tag
`sort`	string	Optional	"newest" or "popular" (default: newest)

Request

curl https://music.hayai.tech/api/v1/tracks?genre=lofi&limit=5 \
  -H "Authorization: Bearer sk_live_your_key"

Response

{
  "success": true,
  "data": {
    "tracks": [
      {
        "id": "trk_a1b2c3d4",
        "title": "Midnight Rain",
        "artist": "Hayai AI",
        "genre": "lofi",
        "mood": "chill",
        "duration_secs": 184,
        "plays": 12420,
        "created_at": "2025-12-01T08:00:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 5,
      "total": 342,
      "totalPages": 69
    }
  }
}

GET/api/v1/tracks/:id

Get Track

Retrieve full metadata for a single track by its unique ID.

Request

curl https://music.hayai.tech/api/v1/tracks/trk_a1b2c3d4 \
  -H "Authorization: Bearer sk_live_your_key"

Response

{
  "success": true,
  "data": {
    "id": "trk_a1b2c3d4",
    "title": "Midnight Rain",
    "artist": "Hayai AI",
    "genre": "lofi",
    "mood": "chill",
    "bpm": 85,
    "key": "Cm",
    "duration_secs": 184,
    "plays": 12420,
    "tags": ["rain", "study", "ambient"],
    "cover_url": "https://cdn.hayai.music/covers/trk_a1b2c3d4.jpg",
    "created_at": "2025-12-01T08:00:00Z"
  }
}

GET/api/v1/tracks/:id/stream

Stream Track

Generate a pre-signed streaming URL for a track. The URL expires after 1 hour. Each call increments the play count.

Request

curl https://music.hayai.tech/api/v1/tracks/trk_a1b2c3d4/stream \
  -H "Authorization: Bearer sk_live_your_key"

Response

{
  "success": true,
  "data": {
    "stream_url": "https://cdn.hayai.music/stream/trk_a1b2c3d4?token=...",
    "expires_at": "2025-12-01T09:00:00Z",
    "track": {
      "id": "trk_a1b2c3d4",
      "title": "Midnight Rain",
      "duration_secs": 184
    }
  }
}

GET/api/v1/search

Search Tracks

Full-text search across track titles, artists, genres, and tags.

Query Parameters

Parameter	Type	Required	Description
`q`	string	Required	Search query
`limit`	integer	Optional	Max results, max 50 (default: 20)

Request

curl "https://music.hayai.tech/api/v1/search?q=ambient+rain&limit=10" \
  -H "Authorization: Bearer sk_live_your_key"

Response

{
  "success": true,
  "data": {
    "tracks": [
      {
        "id": "trk_a1b2c3d4",
        "title": "Midnight Rain",
        "artist": "Hayai AI",
        "genre": "lofi"
      }
    ],
    "total": 1
  }
}

GET/api/v1/genres

List Genres

Retrieve all available genre categories.

Request

curl https://music.hayai.tech/api/v1/genres \
  -H "Authorization: Bearer sk_live_your_key"

Response

{
  "success": true,
  "data": {
    "genres": [
      "lofi",
      "ambient",
      "electronic",
      "cinematic",
      "hip-hop",
      "jazz",
      "classical"
    ]
  }
}