Introduction

API Status: Active
Response time: ~0.8s
View Status Page

Important Notice: This is an unofficial API implementation of Riffusion. We are not affiliated with or endorsed by the original Riffusion project. Any changes to the underlying Riffusion model or technology may temporarily affect our API's functionality without notice. Use at your own discretion.

Welcome to the Riffusion API documentation. Our API allows you to generate music from text descriptions using state-of-the-art AI technology. Riffusion is a powerful tool that transforms text prompts into high-quality music snippets across various genres and styles.

Fast Generation

Generate unique music in seconds with simple text prompts

Custom Cookies

Use custom cookies to optimize requests and improve performance

Flexible Controls

Fine-tune your music generation with advanced parameters

Base URL

https://riffusionapi.com/api
99.9%
Uptime
50ms
Avg Latency
24/7
Support

Authentication

All API requests require authentication using an API key. Include your API key in the request headers:

x-api-key: YOUR_API_KEY

Security Warning

Never share your API key or commit it to version control. Store it securely as an environment variable in production environments.

API Key Management

You can manage your API keys from your dashboard. We recommend rotating your keys periodically for enhanced security.

Manage API Keys

Endpoints

GET /status

Description

Get current API usage and limits for your account

Response

{
 "status": "active",
 "plan": "pro",
 "monthly_calls": 150,
 "remaining_calls": 9850,
 "rate_limit_remaining": 9
}
POST /generate-music

Description

Submit a music generation request (asynchronous processing)

Request Body

{
 "prompt": "jazz piano with drums",
 "custom_cookies": [
   {
     "domain": "www.riffusion.com",
     "name": "sb-api-auth-token.0",
     "value": "base64-eyJhY2Nlc3NfdG9rZW4iOiJleUpoYkdja..."
   },
   {
     "domain": "www.riffusion.com",
     "name": "sb-api-auth-token.1",
     "value": "mlkZW50aXR5X2RhdGEiOnsiYXZhdGFyX3..."
   },
   {
     "domain": ".riffusion.com",
     "name": "ph_phc_AQw23OVpatMbQV6oPTq1Lf6yJOOM415JjJSn1vtRnFC_posthog",
     "value": "%7B%22distinct_id%22%3A%228a7c1cd2..."
   }
 ]
}
Request Parameters

prompt

Text description of the music to generate

Required

custom_cookies

Array of cookies to use with the request

Optional

seed

Random seed for generation

Optional

Response

{
 "status": "pending",
 "request_id": "550e8400-e29b-41d4-a716-446655440000",
 "message": "Your request has been submitted. Check /check-generation/{request_id} for results."
}
GET /check-generation/{request_id}

Description

Check the status of a music generation request

Path Parameters

  • request_id: The ID returned from the generation request

Response (Processing)

{
 "status": "processing",
 "message": "Your request is still processing"
}

Response (Completed)

{
 "status": "success",
 "urls": [
   "https://storage.riffusion.com/123.wav",
   "https://storage.riffusion.com/456.wav"
 ],
 "plan": "pro"
}

Response (Failed)

{
 "status": "failed",
 "details": {
   "detail": "Error generating music: WebDriver error occurred"
 }
}

Custom Cookies

Recommended Feature

Using custom cookies is strongly recommended to improve API performance and reliability. This approach helps manage load on the main Riffusion service and can provide faster response times.

The Riffusion API supports the use of custom cookies when making requests to the underlying Riffusion service. By providing your own cookies, you can:

  • Improve request success rates
  • Reduce generation times
  • Bypass certain rate limiting mechanisms
  • Maintain consistent session state

How to Use Custom Cookies

Custom cookies can be included with your generation request by adding a custom_cookies array in your request body:

{
 "prompt": "Summer hit",
 "custom_cookies": [
   {
     "domain": "www.riffusion.com",
     "name": "sb-api-auth-token.0",
     "value": "base64-eyJhY2Nlc3NfdG9rZW4iOiJleUpoYkdja..."
   },
   {
     "domain": "www.riffusion.com",
     "name": "sb-api-auth-token.1",
     "value": "mlkZW50aXR5X2RhdGEiOnsiYXZhdGFyX3..."
   },
   {
     "domain": ".riffusion.com",
     "name": "ph_phc_AQw23OVpatMbQV6oPTq1Lf6yJOOM415JjJSn1vtRnFC_posthog",
     "value": "%7B%22distinct_id%22%3A%228a7c1cd2..."
   }
 ]
}

Cookie Format

Each cookie object must include the following properties:

domain

The domain the cookie belongs to (usually "www.riffusion.com" or ".riffusion.com")

name

The name of the cookie

value

The value of the cookie

Pro Tip

For optimal performance, extract cookies from an active, authenticated Riffusion session. See our Cookie Extraction Tutorial below for step-by-step instructions.

Rate Limits

Standard Plan

Active
  • 5 requests per minute
  • 5,000 requests per month
  • Email support
$19 /month

Pro Plan

Recommended
  • 10 requests per minute
  • 10,000 requests per month
  • Priority support
  • Advanced parameters
$49 /month

Rate Limit Headers

Our API includes rate limit information in response headers:

  • X-RateLimit-Limit: Maximum requests per minute
  • X-RateLimit-Remaining: Remaining requests in the current window
  • X-RateLimit-Reset: Time when the rate limit resets (Unix timestamp)

Rate Limit Exceeded

When rate limits are exceeded, the API will return a 429 Too Many Requests status code. Please implement appropriate backoff and retry mechanisms in your application.

Examples

Check API Status

curl -X GET "https://riffusionapi.com/api/status" \
-H "accept: application/json" \
-H "x-api-key: YOUR_API_KEY"

Generate Music (Without Custom Cookies)

Stability Warning

Using the API without custom cookies may result in reduced reliability, higher failure rates, and slower response times. For production environments, we strongly recommend using custom cookies as shown in the next example.

curl -X POST "https://riffusionapi.com/api/generate-music" \
-H "accept: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
 "prompt": "jazz piano with drums"
}'

Check the status with the request_id you received:

curl -X GET "https://riffusionapi.com/api/check-generation/550e8400-e29b-41d4-a716-446655440000" \
-H "accept: application/json" \
-H "x-api-key: YOUR_API_KEY"

Generate Music with Custom Cookies (Recommended)

Recommended Approach

This method provides the most stable and reliable experience. Custom cookies help maintain session continuity with the Riffusion service.

curl -X POST "https://riffusionapi.com/api/generate-music" \
-H "accept: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
 "prompt": "Summer hit",
 "custom_cookies": [
   {
     "domain": "www.riffusion.com",
     "name": "sb-api-auth-token.0",
     "value": "base64-eyJhY2Nlc3NfdG9rZW4iOiJleUpoYkdja..."
   },
   {
     "domain": "www.riffusion.com",
     "name": "sb-api-auth-token.1",
     "value": "mlkZW50aXR5X2RhdGEiOnsiYXZhdGFyX3..."
   },
   {
     "domain": ".riffusion.com",
     "name": "ph_phc_AQw23OVpatMbQV6oPTq1Lf6yJOOM415JjJSn1vtRnFC_posthog",
     "value": "%7B%22distinct_id%22%3A%228a7c1cd2..."
   }
 ]
}'

Error Responses

{
 "detail": "Rate limit exceeded (10 requests per minute)"
}

{
 "detail": "Invalid API key"
}

{
 "detail": "Monthly API calls limit exceeded (10000 calls)"
}

{
 "detail": "Request not found"
}

{
 "status": "failed",
 "details": {
   "detail": "Error generating music: Timeout occurred"
 }
}

Tutorials