API Documentation

Integrate AI music generation into your applications with our simple REST API. Free to use, no API key required.

Base URL

https://acerun.eu/api/v1

Rate Limits

⚠️ Free Tier Limits

20 generations per day per IP address. Resets at midnight UTC. Rate limit info is included in response headers and body.

Header	Description
`X-RateLimit-Limit`	Total allowed requests per day (20)
`X-RateLimit-Remaining`	Remaining requests today
`X-RateLimit-Reset`	ISO 8601 timestamp when limit resets

Generate Music

POST /api/v1/generate

Request Body (JSON)

Parameter	Type	Required	Description
`tags`	string	Yes	Comma-separated genre/style tags (e.g. "pop, piano, upbeat")
`lyrics`	string	No	Song lyrics with structure markers: [Verse], [Chorus], [Bridge], [Outro]
`duration`	number	No	Duration in seconds (15–240). Default: 60
`instrumental`	boolean	No	If true, generates instrumental without vocals. Default: false
`seed`	number	No	Random seed for reproducibility. Use -1 for random. Default: -1

Success Response (200)

{
  "audio": "UklGRiQA... (base64-encoded WAV)",
  "format": "wav",
  "sample_rate": 44100,
  "duration": 60,
  "remaining": 19,
  "resetAt": "2025-01-16T00:00:00.000Z"
}

Error Response (429 — Rate Limited)

{
  "error": "rate_limit_exceeded",
  "message": "Daily limit of 20 free generations reached.",
  "remaining": 0,
  "resetAt": "2025-01-16T00:00:00.000Z"
}

Error Codes

Status	Error	Description
400	`invalid_request`	Missing or invalid request parameters
429	`rate_limit_exceeded`	Daily generation limit reached
500	`generation_failed`	Model failed to generate audio
503	`service_unavailable`	GPU service is temporarily down

Check API Status

GET /api/v1/generate

Returns API info and your current rate limit status.

Code Examples

cURL

curl -X POST https://acerun.eu/api/v1/generate \
  -H "Content-Type: application/json" \
  -d '{
    "tags": "pop, female vocals, piano, upbeat",
    "lyrics": "[Verse]\nWalking through the city lights\nEvery star is shining bright\n\n[Chorus]\nWe are running through the night",
    "duration": 60
  }'

Python

import requests
import base64

response = requests.post(
    "https://acerun.eu/api/v1/generate",
    json={
        "tags": "electronic, synth, energetic",
        "lyrics": "[Verse]\nDigital dreams in neon light",
        "duration": 90,
    }
)

data = response.json()

# Save the audio file
audio_bytes = base64.b64decode(data["audio"])
with open("song.wav", "wb") as f:
    f.write(audio_bytes)

print(f"Remaining today: {data['remaining']}")

JavaScript / TypeScript

const response = await fetch("https://acerun.eu/api/v1/generate", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    tags: "lo-fi, chill, piano",
    instrumental: true,
    duration: 120,
  }),
});

const data = await response.json();

// Convert base64 to audio blob
const audioBytes = Uint8Array.from(atob(data.audio), c => c.charCodeAt(0));
const blob = new Blob([audioBytes], { type: "audio/wav" });
const url = URL.createObjectURL(blob);

// Play the audio
const audio = new Audio(url);
audio.play();

Supported Tags

You can combine any of these tags freely:

Genres

pop, rock, jazz, electronic, hip-hop, classical, r&b, country, lo-fi, ambient, metal, funk, reggae, blues, latin, indie, soul, folk, edm, house, techno, trap, drill, afrobeat, k-pop, j-pop, bossa nova, disco, grunge, punk

Vocals

female vocals, male vocals, choir, rap, whisper, spoken word

Instruments

piano, guitar, drums, synth, bass, strings, saxophone, trumpet, violin, flute, organ, harp, ukulele, mandolin

Moods

upbeat, melancholic, energetic, chill, dramatic, romantic, dark, epic, peaceful, nostalgic, aggressive, dreamy, haunting