The BlueMetal Music API

Authentication#

Server-to-server calls use a bearer key: Authorization: Bearer bm_live_…. Keys are created on the dashboard and shown exactly once — we store only sha256(key), so a lost key is replaced, never recovered. Never put one in client-side code.

The dashboard and playground use a session cookie instead. There are no passwords: sign in with GitHub, or ask for an email magic link that is valid for 15 minutes and can be used once.

Generation lifecycle#

A generation moves queued → running → succeeded, failed or canceled. Rendering costs roughly two-fifths of the song's own length on one RTX 5090 — a 60-second track lands in about 22 seconds, a three-minute track in about 70.

Poll with backoff — start at a second and grow to about five, well inside the 600 reads/minute limit. If you would rather not poll at all, pass a webhook_url and we will call you once. And if the song is short and you can hold a connection, pass mode:"sync": it returns the finished object inside 90 seconds, or a 202 with status:"running" if it needs longer, so your client must handle both.

Send an Idempotency-Key on every create. A replay within 24 hours returns the original generation instead of paying for a second one — which matters most on the retry after a timeout, when you cannot tell whether the first request landed.

Turn a description and optional lyrics into a full song. Returns 202 with a queued generation in async mode, or 200 with a finished one in sync mode if it lands inside 90 seconds.

curl https://api.bluemetal.ai/v1/music/generations \
  -H "Authorization: Bearer $BLUEMETAL_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
        "model": "minimax-music-3",
        "prompt": "Upbeat indie pop, 120 BPM, female vocal, bright guitars",
        "lyrics": "[Verse]\nCity lights are humming low\n[Chorus]\nHold on, hold on, the night is ours",
        "duration": 120,
        "format": "mp3"
      }'

{
  "id": "gen_01JABCDEF",
  "object": "music.generation",
  "model": "minimax-music-3",
  "status": "queued",
  "created_at": 1756500000,
  "started_at": null,
  "completed_at": null,
  "audio": null,
  "usage": null,
  "error": null,
  "queue_position": 2,
  "estimated_wait_s": 25
}

The same object, with audio and usage filled in once it succeeds. 404 if the generation is not yours. Poll this with backoff; every read mints a fresh 24-hour audio URL.

curl https://api.bluemetal.ai/v1/music/generations/gen_01JABCDEF \
  -H "Authorization: Bearer $BLUEMETAL_API_KEY"

{
  "id": "gen_01JABCDEF",
  "object": "music.generation",
  "status": "succeeded",
  "created_at": 1756500000,
  "started_at": 1756500003,
  "completed_at": 1756500043,
  "audio": {
    "url": "https://…r2 presigned GET…",
    "format": "mp3",
    "duration": 178.4,
    "bytes": 2914560,
    "sample_rate": 32000,
    "expires_at": 1756586443
  },
  "usage": { "audio_seconds": 178.4, "amount_usd": 0.0107 },
  "error": null
}

Your generations, newest first, cursor-paginated.

curl "https://api.bluemetal.ai/v1/music/generations?limit=20&status=succeeded" \
  -H "Authorization: Bearer $BLUEMETAL_API_KEY"

{ "object": "list", "data": [ { … } ], "has_more": false }

Cancels a generation that is still queued. 409 once it has started — a running job is already burning GPU.

curl -X POST https://api.bluemetal.ai/v1/music/generations/gen_01JABCDEF/cancel \
  -H "Authorization: Bearer $BLUEMETAL_API_KEY"

{ "id": "gen_01JABCDEF", "status": "canceled", … }

An OpenAI-shaped model list, extended with the fields a provider listing wants: modalities, quantization, max duration, per-second pricing and supported parameters. GET /v1/models/{id} returns one.

curl https://api.bluemetal.ai/v1/models -H "Authorization: Bearer $BLUEMETAL_API_KEY"

{
  "object": "list",
  "data": [{
    "id": "minimax-music-3",
    "object": "model",
    "owned_by": "minimax",
    "name": "MiniMax Music 3",
    "description": "Text+lyrics → full song, up to 5 minutes, 32 kHz stereo",
    "input_modalities": ["text"],
    "output_modalities": ["audio"],
    "quantization": "int4-mixed",
    "max_duration_seconds": 300,
    "pricing": { "audio_second": "0.000115", "unit": "USD" },
    "supported_parameters": ["prompt", "lyrics", "duration", "seed", "format"],
    "endpoints": ["/v1/music/generations", "/v1/audio/speech"]
  }]
}

Exists so an OpenAI SDK works with only a base-URL swap. input maps to lyrics and instructions to prompt. Always synchronous, and it returns raw audio bytes rather than JSON.

curl https://api.bluemetal.ai/v1/audio/speech \
  -H "Authorization: Bearer $BLUEMETAL_API_KEY" \
  -H "Content-Type: application/json" \
  -o song.mp3 \
  -d '{
        "model": "minimax-music-3",
        "instructions": "Synthwave, 110 BPM, retro 80s synths",
        "input": "[Verse]\nNeon rivers, chrome and glass",
        "response_format": "mp3"
      }'

Your account, including the remaining prepaid credit. Session cookie or an API key.

curl https://api.bluemetal.ai/v1/account -H "Authorization: Bearer $BLUEMETAL_API_KEY"

{ "id": "acct_…", "email": "you@example.com", "credits_usd": 0.4731, "created_at": 1756400000, "plan": "free" }

POST /v1/keys creates a key and returns the secret exactly once — only sha256(key) is stored. GET /v1/keys lists keys without their secrets, showing a prefix. DELETE /v1/keys/{id} revokes one and returns 204.

curl https://api.bluemetal.ai/v1/keys \
  -H "Authorization: Bearer $BLUEMETAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"prod"}'

{ "id": "key_…", "name": "prod", "key": "bm_live_…", "created_at": 1756400000, "last_used_at": null }

Generations, audio seconds and spend, bucketed by day.

curl "https://api.bluemetal.ai/v1/usage?from=1756425600&bucket=day" \
  -H "Authorization: Bearer $BLUEMETAL_API_KEY"

{
  "data": [
    { "ts": 1756425600, "generations": 14, "audio_seconds": 1382.6, "amount_usd": 0.0829 }
  ],
  "total": { "generations": 143, "audio_seconds": 14204.1, "amount_usd": 0.8522 }
}

Webhooks#

Pass webhook_url on a create and we POST the whole generation object once it reaches a terminal state, as {"type":"music.generation.succeeded","data":{…}}. Non-2xx responses are retried three times, after 10 s, 60 s and 300 s.

POST https://your-app.example.com/hooks/bluemetal
bluemetal-signature: t=1756500043,v1=9f86d081884c7d659a2feaa0c55ad015…
bluemetal-delivery: 7c9e6679-7425-40de-944b-e07fc1f90ae7

{
  "type": "music.generation.succeeded",
  "data": { "id": "gen_01JABCDEF", "status": "succeeded", "audio": { … }, "usage": { … } }
}

Verify the signature before you trust the body. It is an HMAC-SHA256 of t + "." + body using your account's signing secret, which lives on the dashboard. Compare in constant time and reject timestamps more than a few minutes old.

import crypto from "node:crypto"

export function verify(rawBody, header, secret) {
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")))
  const age = Math.abs(Date.now() / 1000 - Number(parts.t))
  if (age > 300) return false                        // reject replays
  const expected = crypto
    .createHmac("sha256", secret)
    .update(`${parts.t}.${rawBody}`)
    .digest("hex")
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1))
}

Errors#

Errors are OpenAI-shaped, with the matching HTTP status. Everything 4xx and 5xx is logged against the x-request-id on the response — quote it and we can find the exact request.

{
  "error": {
    "message": "duration must be between 10 and 300",
    "type": "invalid_request_error",
    "code": "invalid_request",
    "param": "duration"
  }
}

Rate limits#

Every response carries x-ratelimit-limit, x-ratelimit-remaining, x-ratelimit-reset, retry-after (on 429 only). On a 429, wait for retry-after rather than retrying immediately — a tight retry loop is the fastest way to stay rate limited.

Pricing#

$0.000115 per second of delivered audio, with a 15-second minimum per request. You are billed for what the model actually produced, never for idle GPU time, and credit is debited only when a generation succeeds.

New accounts get $0.50 of credit — about 24 three-minute tracks — with no card. When the balance hits zero, creates return 402: there is no overage and no invoice in v1.