API Documentation
Integrate AI music generation into your applications
Quick Start
https://api.tuneforge.io/api/v1Authorization: Bearer tf_your_api_keyAll API requests require authentication. Include your API key in the Authorization header.
Authentication
TuneForge uses two authentication methods depending on the endpoint type.
Method 1: API Key (Music Generation & Account)
For music generation and account endpoints, use an API key from your account settings. Include it in the Authorization header:
curl https://api.tuneforge.io/api/v1/account/me \
-H "Authorization: Bearer tf_your_api_key"Method 2: Hotkey Signature (Scoring & Analytics)
Scoring endpoints are accessible to any registered neuron (miner or validator) on subnet 234. No user account needed — authenticate with your Bittensor hotkey by signing each request.
Required headers:
| Header | Description |
|---|---|
| X-Validator-Hotkey | Your ss58 hotkey address |
| X-Validator-Nonce | Current timestamp in nanoseconds (must be within 300s of server time) |
| X-Validator-Signature | Hex-encoded signature of the message (see below) |
Signature message format:
message = "{nonce}.{hotkey}.{method}.{path}.{body_hash}"
# body_hash = SHA-256 hex digest of request body, or "empty" for GET requests
# Example for GET /api/v1/scores/best:
# "1710600000000000000.5H8t4Kqj....GET./api/v1/scores/best.empty"Python example:
import time, hashlib
import bittensor as bt
wallet = bt.wallet(name="my_coldkey", hotkey="my_hotkey")
hotkey = wallet.hotkey.ss58_address
nonce = str(time.time_ns())
method = "GET"
path = "/api/v1/scores/best"
body_hash = "empty" # no body for GET requests
message = f"{nonce}.{hotkey}.{method}.{path}.{body_hash}"
signature = wallet.hotkey.sign(message.encode()).hex()
import requests
resp = requests.get(
f"https://api.tuneforge.io{path}",
headers={
"X-Validator-Hotkey": hotkey,
"X-Validator-Nonce": nonce,
"X-Validator-Signature": signature,
},
)
print(resp.json())Keep your API keys and hotkey files secure. Do not expose them in client-side code, public repositories, or share them with others.
Endpoints
Music Generation
Scoring & Analytics
Every track generated on the TuneForge network is evaluated by validators across 16 scoring dimensions plus 4 penalty multipliers. The score_breakdown object is included in track responses when available, giving full transparency into how each track was scored.
These endpoints use hotkey signature authentication — any registered neuron (miner or validator) on subnet 234 can access them. See the Authentication section for details.
| Category | Scorers (weight) |
|---|---|
| Prompt Adherence (30%) | clap (19%), attribute (11%) |
| Composition (21%) | musicality (9%), melody (6%), structural (6%) |
| Production & Fidelity (16%) | production (5%), neural_quality (5%), vocal (4%), quality (2%) |
| Naturalness & Mix (18%) | vocal_lyrics (8%), mix_separation (4%), timbral (3%), learned_mos (3%) |
| Other (8%) | diversity (6%), speed (2%) |
| Preference (2-20%) | preference — auto-scales when trained |
The export endpoint includes an audio_url field for each entry. Combine with the base URL to download audio for fine-tuning or analysis.
Penalty multipliers (1.0 = no penalty): duration_penalty, artifact_penalty, fad_penalty, fingerprint_penalty. Final score = composite × all penalties.
Account
Rate Limits
| Plan | Rate Limit |
|---|---|
| Free | 60 req/min |
| Pro | 300 req/min |
| Premier | 1,000 req/min |
Rate Limit Headers
Every API response includes headers to help you track your rate limit usage:
| Header | Description |
|---|---|
X-RateLimit-Limit | Maximum requests allowed per minute |
X-RateLimit-Remaining | Requests remaining in the current window |
X-RateLimit-Reset | Unix timestamp when the rate limit resets |
Error Codes
| Code | Status | Description |
|---|---|---|
| 200 | OK | Request succeeded |
| 201 | Created | Resource created successfully |
| 400 | Bad Request | Invalid request parameters or body |
| 401 | Unauthorized | Missing or invalid API key |
| 402 | Payment Required | Insufficient credits for this operation |
| 404 | Not Found | Resource not found |
| 429 | Too Many Requests | Rate limit exceeded. Check X-RateLimit headers |
| 500 | Internal Server Error | Something went wrong on our end |
All error responses include a JSON body with a detail field describing the error:
{
"detail": "Insufficient credits. You need 5 credits but have 2 remaining."
}Code Examples
Full examples showing how to generate music, poll for status, and retrieve the audio URL.
# Generate music
curl -X POST https://api.tuneforge.io/api/v1/music/generate \
-H "Authorization: Bearer tf_your_api_key" \
-H "Content-Type: application/json" \
-d '{
"prompt": "Chill lo-fi hip hop beat with vinyl crackle",
"genre": "lo-fi",
"mood": "calm",
"duration_seconds": 15
}'
# Check generation status
curl https://api.tuneforge.io/api/v1/music/status/req_abc123def456 \
-H "Authorization: Bearer tf_your_api_key"
# Download the audio
curl -O https://api.tuneforge.io/api/v1/music/audio/trk_001.wav \
-H "Authorization: Bearer tf_your_api_key"