Muziek genereren via API

Account en API-keys

Je gebruikt hetzelfde account voor het developerportal, credits en de gewone Studio. In het portal maak je maximaal vijf actieve keys met afzonderlijke scopes. Je ziet per key de prefix, aanmaakdatum en laatste gebruiksmoment.

1. Maak een account of log in. Je komt daarna direct terug in het developerportal.
2. Geef de key een herkenbare naam. Gebruik aparte keys voor productie en ontwikkeling.
3. Kopieer de volledige key meteen. Wij bewaren alleen een hash en kunnen de key later niet terughalen.
4. Trek een key direct in bij twijfel. Requests met die key geven daarna 401 unauthorized.

Authenticatie

Zet je API-key in de Authorization-header. Plaats hem nooit in client-side JavaScript, een mobiele appbundle of een publieke repository.

Authorization: Bearer $MMMAI_API_KEY

Een key kan de scopes music:generate, music:read en webhooks:write hebben. Een ingetrokken of ongeldige key geeft 401 unauthorized. Een ontbrekende scope geeft 403 forbidden.

Start je eerste generatie

Gebruik voor iedere nieuwe opdracht een unieke Idempotency-Key van 1 tot 128 tekens. Je kunt een mislukte netwerkrequest veilig met dezelfde key en exact dezelfde JSON-body herhalen.

curl -X POST https://muziekmakenmetai.nl/api/v1/music/generations/ \
  -H "Authorization: Bearer $MMMAI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-2026-0001" \
  -d '{
    "model": "music-v2",
    "prompt": "Een opgewekte instrumentale poptrack met piano en een rustig einde",
    "instrumental": true,
    "title": "Ochtendlicht"
  }'

Een nieuwe job geeft 202 Accepted. Een veilige replay geeft 200 OK en hetzelfde job-ID. Gebruik je dezelfde idempotency-key met een andere body, dan krijg je 409 idempotency_conflict.

{
  "id": "17e0da64-350c-499b-b66d-4f012b95da24",
  "object": "music_generation",
  "status": "queued",
  "model": "music-v1",
  "created_at": "2026-09-05T08:15:30+00:00",
  "completed_at": null,
  "tracks": [],
  "url": "https://muziekmakenmetai.nl/api/v1/music/generations/17e0da64-350c-499b-b66d-4f012b95da24/"
}

Status en resultaat ophalen

Lees de URL uit de response of de Location-header. Poll zolang de status queued of processing is. Stop bij succeeded of failed.

curl https://muziekmakenmetai.nl/api/v1/music/generations/17e0da64-350c-499b-b66d-4f012b95da24/ \
  -H "Authorization: Bearer $MMMAI_API_KEY"

{
  "id": "17e0da64-350c-499b-b66d-4f012b95da24",
  "object": "music_generation",
  "status": "succeeded",
  "model": "music-v1",
  "created_at": "2026-09-05T08:15:30+00:00",
  "completed_at": "2026-09-05T08:17:04+00:00",
  "tracks": [
    {
      "id": "4182",
      "title": "Ochtendlicht",
      "duration_seconds": 72,
      "audio_url": "https://muziekmakenmetai.nl/media/generated_assets/music/ochtendlicht.mp3",
      "image_url": "https://muziekmakenmetai.nl/media/generated_assets/music/ochtendlicht.jpg"
    }
  ]
}

De API toont tracks pas nadat de audio naar onze eigen opslag is gekopieerd. Bij failed krijg je foutcode generation_failed en wordt de gereserveerde credit hersteld.

Requestvelden

prompt is het enige veld dat altijd verplicht is. De API weigert onbekende velden zodat een typfout niet stil wordt genegeerd.

Lees de actuele capabilities voor de machineleesbare modellen, grenzen en beschikbare velden.

Welk model kies je?

Alle modellen kosten één credit per generatie en leveren twee versies.

Talen voor zang en songtekst

Gebruik de volledige Nederlandse taalnaam. Nederlands, Engels, Duits, Frans, Spaans, Italiaans en Portugees zijn de aanbevolen waarden. Andere taalnamen tot 40 tekens worden ook geaccepteerd, maar de uitspraak en zangkwaliteit kunnen per taal verschillen.

In description mode verwerkt de API language in de muziekopdracht. In custom_mode bepaalt je eigen songtekst de gezongen taal. Zet language dan nog steeds correct voor je administratie en toekomstige compatibiliteit.

Credits en limieten

Iedere generatie reserveert één credit. De API gebruikt eerst je API-credits en valt daarna terug op je niet-verlopende songcredits; je ziet beide saldi via GET /account/. Bij een definitief mislukte generatie wordt de credit teruggeboekt naar de wallet waar de generatie mee betaald is.

curl https://muziekmakenmetai.nl/api/v1/account/ \
  -H "Authorization: Bearer $MMMAI_API_KEY"

Nieuwe keys staan standaard op 30 requests per minuut. De accountresponse bevat de limiet die voor jouw key geldt. Te weinig credits geeft 402 insufficient_credits; een overschreden limiet geeft 429 rate_limited.

Prepaid API-prijzen

Eén generatie-request kost één credit. Je betaalt vooraf, zonder maandabonnement of onverwachte rekening. Bij een definitief mislukte generatie zet de creditledger de credit automatisch terug.

Maak een account en koop API-credits. API-credits werken uitsluitend in de API. Los gekochte songcredits voor de Studio mogen ook als fallback in de API. Deze prepaidcredits verlopen niet. Maandcredits van Plus en Pro werken uitsluitend in de Studio.

Webhooks instellen

Stel één publieke HTTPS-URL per key in. De URL mag niet naar localhost, een privénetwerk of een adres met credentials wijzen.

curl -X PUT https://muziekmakenmetai.nl/api/v1/webhook/ \
  -H "Authorization: Bearer $MMMAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://jouw-app.nl/webhooks/muziek"}'

De response bevat een signing_secret. Bewaar dit als secret. Stuur {"url":""} om de webhook uit te schakelen.

Webhooks controleren

Bereken HMAC-SHA256 over de exacte ruwe requestbody, voorafgegaan door de timestamp en een punt. Vergelijk de uitkomst constant-time met X-MMMAI-Signature. Gebruik X-MMMAI-Event om dubbele verwerking te voorkomen.

import hashlib
import hmac

signed = timestamp.encode() + b"." + raw_body
expected = "sha256=" + hmac.new(
    signing_secret.encode(), signed, hashlib.sha256
).hexdigest()

if not hmac.compare_digest(expected, received_signature):
    raise ValueError("Ongeldige webhookhandtekening")

Terminale events zijn music.generation.succeeded en music.generation.failed. De bezorger accepteert iedere 2xx-response, volgt geen redirects en probeert een tijdelijke bezorgfout maximaal vijf keer opnieuw.

Foutcodes

API-validatiefouten hebben steeds dezelfde JSON-vorm. Een onbekend of niet aan jouw key gekoppeld job-ID geeft 404.

{
  "error": {
    "code": "invalid_parameter",
    "message": "prompt is verplicht."
  }
}