Music Generation
Synthesize AI-powered music from text prompts using ACE-Step v1.5. Optional reference audio guides style and timbre.
Overview
The Music API allows you to generate short musical pieces (5–120 seconds) from text descriptions. Each generation is billed at $0.00015 per second (150 µUSD/s).
Daily generation limits apply by subscription tier:
| Tier | Daily Limit | Est. Cost/Day |
|---|---|---|
| Free | Disabled | — |
| Starter | 30s | $0.0045 |
| Basic | 2m | $0.018 |
| Pro | 60m | $0.54 |
Quick Start
curl -X POST https://getvrex.com/api/v1/music \
-H "Authorization: Bearer sk-your-api-key" \
-H "Content-Type: application/json" \
-d '{
"caption": "Upbeat pop song with synth drums",
"lyrics": "Let the beat drop, yeah yeah yeah",
"duration_ms": 30000
}'Typical generation takes 15–40 seconds. You can poll the job endpoint every 1–2 seconds or configure webhooks for completion notifications.
Reference Audio
Upload a short audio sample to guide the music generation. The engine will analyze the timbre, mood, and instrumentation and apply similar characteristics to the generated music.
curl -X POST https://getvrex.com/api/v1/music/ref-audio \
-H "Authorization: Bearer sk-your-api-key" \
-F "audio=@path/to/sample.wav"Supported formats: WAV, MP3, FLAC (max 10MB, max 10 seconds recommended)
API Reference
/musicSubmit an async music generation job.
Request Body
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
| caption | string | Required | — | Music prompt describing the desired sound. 100–500 characters. Example: 'upbeat electronic dance music with pulsing bassline'. |
| lyrics | string | Optional | — | Optional lyrics to guide generation. Up to 2000 characters. |
| duration_ms | number | Optional | 30000 | Song duration in milliseconds. Range: 5000–120000 (5–120 seconds). |
| ref_audio_url | string | Optional | — | Presigned URL of reference audio from POST /music/ref-audio endpoint. Used to guide style/timbre. |
Response (202 Accepted)
{
"job_id": "550e8400-e29b-41d4-a716-446655440000",
"generation_id": "550e8400-e29b-41d4-a716-446655440001",
"status": "pending",
"duration_ms": 30000,
"estimated_cost_usd": 0.0045
}Errors
| Code | Status | Description |
|---|---|---|
| VALIDATION_ERROR | 400 | Invalid request (caption missing, duration out of range) |
| INSUFFICIENT_BALANCE | 402 | Insufficient balance. Please top up your account. |
| PROMPT_FILTER_REJECTED | 400 | Prompt violates acceptable use policy |
| RATE_LIMITED | 429 | Rate limit exceeded or queue full |
| DAILY_LIMIT_EXCEEDED | 429 | Daily generation limit reached for tier |
/music/:idPoll the status of a music generation job.
Response
{
"job_id": "550e8400-e29b-41d4-a716-446655440000",
"generation_id": "550e8400-e29b-41d4-a716-446655440001",
"status": "completed",
"caption": "Upbeat pop song with synth drums",
"lyrics": "Let the beat drop, yeah yeah yeah...",
"duration_ms": 30000,
"audio_url": "https://r2.getvrex.com/music/...",
"audio_format": "audio/mpeg",
"size_bytes": 450000,
"cost_usd": 0.0045,
"created_at": "2025-01-01T12:00:00.000Z",
"completed_at": "2025-01-01T12:00:35.000Z"
}Possible statuses: pending, processing, completed, failed
audio_url is a presigned download URL (valid 1 hour). Downloads the MP3 file.
/music/ref-audioUpload reference audio to guide music generation style.
Request (multipart form-data)
Response (201 Created)
{
"ref_audio_url": "https://r2.getvrex.com/ref-audio/...",
"expires_in": 3600,
"size_bytes": 125000,
"duration_ms": 5000
}Use the ref_audio_url in the /music request body.
/music/usageCheck your music generation usage and daily limit status.
Response
{
"tier": "pro",
"daily_limit_ms": 3600000,
"usage_today_ms": 180000,
"remaining_ms": 3420000,
"usage_this_month_ms": 1200000,
"generations_count": 42,
"total_cost_usd": 0.18
}FAQ
How long does music generation take?
Typical generation takes 15–40 seconds per 30-second song, depending on GPU load. You can check status via polling or webhooks.
Can I use generated music commercially?
Yes, commercial use is permitted under our Terms of Service. Always comply with music licensing laws in your jurisdiction.
What formats are supported for reference audio?
WAV, MP3, and FLAC formats up to 10MB. For best results, keep reference audio under 10 seconds.
What happens if my prompt is rejected?
Prompts containing non-music content, adult material, or copyright violations will be rejected with a 400 error and no charge. See our Acceptable Use Policy.
Can I refund a generation if I didn't like it?
Failed generations are automatically refunded. For quality issues, contact support within 24 hours of generation.
How does the daily limit work?
Your daily limit (e.g., Pro = 60 minutes) resets at midnight UTC. Check remaining quota via GET /music/usage.