API-documentatie

Inleiding

De API doet precies wat de website doet. Je stuurt een gelegenheid, de naam van de persoon voor wie het lied is en een handvol concrete details. Daaruit ontstaat eerst een volledige songtekst, daarna een geproduceerde opname met zang, arrangement en mix. Het hele proces duurt meestal vijf tot tien minuten.

Alle aanvragen gaan naar https://api.liedmaker.nl/v1. De API spreekt uitsluitend HTTPS, accepteert JSON en antwoordt met JSON. Er is geen verplichte SDK: elke taal die HTTP kan, volstaat. De voorbeelden op deze pagina gebruiken curl, Python en Node, omdat dat de drie meest voorkomende gevallen zijn.

Elk domein heeft zijn eigen API-basis en zijn eigen prijs in de lokale valuta. Een sleutel geldt voor het domein waarvoor hij is uitgegeven. Wie meerdere markten bedient, krijgt meerdere sleutels of één sleutel met meerdere vrijgegeven domeinen.

Toegang

Er is bewust geen zelfregistratie. We geven sleutels met de hand uit, omdat achter elk lied echte productiekosten zitten en we willen weten waarvoor de integratie bedoeld is. In de praktijk is dat een korte mail en één werkdag.

Schrijf naar songs@maxkuch.com en noem vier dingen:

• Wat je wilt bouwen, in twee of drie zinnen.
• Ongeveer hoeveel volume per maand.
• In welke talen de liedjes gezongen moeten worden.
• Of je webhooks kunt ontvangen of liever pollt.

Je krijgt dan twee sleutels: een testsleutel met het voorvoegsel sk_test_, die niets kost en vaste demo-opnamen levert, en een livesleutel met het voorvoegsel sk_live_. Beide werken meteen, zonder dat losse endpoints apart vrijgegeven hoeven te worden.

Authenticatie

Elke aanvraag draagt de sleutel in de Authorization-header als bearer-token. Aanvragen zonder geldige header krijgen een 401 en het fouttype authentication_error.

curl https://api.liedmaker.nl/v1/songs \
  -H "Authorization: Bearer $SONG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "occasion": "birthday",
    "recipient_name": "Anna",
    "relationship": "sister",
    "language": "nl",
    "mood": "happy",
    "style": "pop",
    "voice": "female",
    "details": "Climbs every weekend, always ten minutes late, calls everyone chef.",
    "callback_url": "https://example.com/hooks/songs"
  }' 

Behandel de sleutel als een wachtwoord: alleen aan de serverkant, nooit in frontendcode, nooit in een openbare repository. Raakt een sleutel kwijt, schrijf ons dan, we blokkeren hem meteen en geven een nieuwe uit. Een account mag meerdere actieve sleutels hebben, zodat wisselen zonder uitval kan.

Test- en livesleutels delen dezelfde endpoints. Of een aanvraag in testmodus liep, staat in het veld livemode van elk object.

Snelstart

Een lied maken is één aanroep. Het antwoord komt meteen en bevat een lied-id met de status queued. Al het andere gebeurt op de achtergrond.

import os, time, requests

API = "https://api.liedmaker.nl/v1"
HEAD = {"Authorization": "Bearer " + os.environ["SONG_API_KEY"]}

song = requests.post(API + "/songs", headers=HEAD, json={
    "occasion": "wedding",
    "recipient_name": "Lea and Tim",
    "relationship": "friends",
    "language": "nl",
    "mood": "romantic",
    "details": "Met at a bike repair shop, dog named Miso, both terrible dancers.",
}).json()

while song["status"] not in ("preview_ready", "complete", "failed"):
    time.sleep(5)
    song = requests.get(API + "/songs/" + song["id"], headers=HEAD).json()

print(song["lyrics"])
print(song["preview_url"])

Het voorbeeld pollt voor de eenvoud elke vijf seconden. In productie zijn webhooks de betere weg, omdat ze zowel de open verbinding als de wachttijd besparen. Beide worden ondersteund, webhooks staan verderop beschreven.

Het belangrijkste veld is details. Daar horen de concrete dingen over de persoon: de bijnaam, de eigenaardigheid, de vakantie die misging. Algemene zinnen als "ze is een warm mens" leveren algemene regels op. Drie tot vijf concrete details zijn genoeg en maken het verschil tussen aardig en echt persoonlijk.

Endpoints in het kort

Een lied maken

POST /v1/songs neemt de omschrijving aan en begint meteen. Slechts drie velden zijn verplicht, de rest heeft zinnige standaardwaarden of wordt passend bij de gelegenheid gekozen.

const res = await fetch("https://api.liedmaker.nl/v1/songs", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.SONG_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": crypto.randomUUID(),
  },
  body: JSON.stringify({
    occasion: "anniversary",
    recipient_name: "Mara",
    relationship: "partner",
    language: "nl",
    mood: "warm",
    details: "Ten years, three apartments, one very loud coffee machine.",
    callback_url: "https://example.com/hooks/songs",
    metadata: { order_id: "A-10423" },
  }),
});

const song = await res.json();
console.log(song.id, song.status);

Het song-object

Elk endpoint dat één lied teruggeeft, levert hetzelfde object. Velden die nog niet vaststaan zijn null en vullen zich tijdens de productie.

{
  "id": "sng_3n8Kd2ZpQv",
  "object": "song",
  "status": "queued",
  "created_at": "2026-09-16T09:41:02Z",
  "occasion": "birthday",
  "recipient_name": "Anna",
  "relationship": "sister",
  "language": "nl",
  "mood": "happy",
  "style": "pop",
  "voice": "female",
  "lyrics": null,
  "preview_url": null,
  "audio_url": null,
  "duration_seconds": null,
  "paid": false,
  "price": { "amount": 2999, "currency": "EUR" },
  "metadata": {},
  "livemode": true
}

{
  "id": "sng_3n8Kd2ZpQv",
  "object": "song",
  "status": "complete",
  "created_at": "2026-09-16T09:41:02Z",
  "completed_at": "2026-09-16T09:47:35Z",
  "lyrics": "[Verse 1]\nAnna, six in the morning, chalk on your hands ...",
  "preview_url": "https://cdn.liedmaker.nl/preview/sng_3n8Kd2ZpQv.mp3",
  "audio_url": "https://cdn.liedmaker.nl/full/sng_3n8Kd2ZpQv.mp3?expires=1789412855&sig=...",
  "duration_seconds": 184,
  "paid": true,
  "price": { "amount": 2999, "currency": "EUR" },
  "metadata": { "order_id": "A-10423" },
  "livemode": true
}

Statuswaarden

Een lied doorloopt de toestanden in deze volgorde. Het gaat nooit terug, en complete, failed en cancelled zijn eindtoestanden.

Eén mislukte productiepoging leidt niet meteen tot failed. We proberen het intern meerdere keren en geven pas op als alle pogingen mislukken. Daarom is failed zeldzaam en betekent het echt: dit lied komt er niet.

Ophalen en opsommen

GET /v1/songs/{id} geeft de actuele stand van een lied. Het endpoint is goedkoop en mag elke seconde bevraagd worden, zolang de limiet wordt aangehouden.

curl -G https://api.liedmaker.nl/v1/songs \
  -H "Authorization: Bearer $SONG_API_KEY" \
  -d status=complete \
  -d limit=20 \
  -d starting_after=sng_3n8Kd2ZpQv

Lijsten zijn cursorgebaseerd. Je krijgt maximaal limit items, standaard 20 en hoogstens 100, nieuwste eerst. Is has_more waar, dan geef je next_cursor bij de volgende aanroep mee als starting_after. Filteren kan op status, occasion, language, paid en op created_after en created_before.

{
  "object": "list",
  "data": [
    { "id": "sng_9Wq1LmT4bR", "status": "complete", "recipient_name": "Jonas", "...": "..." },
    { "id": "sng_3n8Kd2ZpQv", "status": "complete", "recipient_name": "Anna",  "...": "..." }
  ],
  "has_more": true,
  "next_cursor": "sng_3n8Kd2ZpQv"
}

Songtekst en audio

De songtekst is gratis en volledig, geen fragment. GET /v1/songs/{id}/lyrics geeft hem als text/plain, met markeringen voor coupletten en refrein. Dezelfde tekst staat in het veld lyrics van het song-object.

Bij audio zijn er twee trappen. De preview is de eerste 45 seconden van de afgeronde opname, geen aparte demo: dezelfde stem, hetzelfde arrangement, dezelfde tekst. Hij is zonder betaling beschikbaar en blijft dat. Het volledige bestand levert GET /v1/songs/{id}/audio pas na vrijgave.

Beide adressen zijn ondertekend en 24 uur geldig. Ze zijn bedoeld om te downloaden, niet om blijvend naar te linken. Heb je een bestand langer nodig, download het dan één keer en bewaar het zelf. Een nieuwe aanroep van het endpoint maakt op elk moment een vers adres.

Het formaat is overal MP3 met 320 kbit/s. Wie WAV nodig heeft, hangt ?format=wav eraan, wat beschikbaar is voor accounts met studiovrijgave.

Opnieuw genereren

Zit een resultaat ernaast, dan kost opnieuw genereren niets. POST /v1/songs/{id}/regenerate maakt een nieuwe versie onder hetzelfde id en zet de status terug op queued. De vorige versie blijft bewaard onder previous_versions.

curl https://api.liedmaker.nl/v1/songs/sng_3n8Kd2ZpQv/regenerate \
  -H "Authorization: Bearer $SONG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "keep_lyrics": false,
    "reason": "voice_not_matching",
    "note": "Please try a lower male voice and a slower tempo."
  }' 

Met keep_lyrics: true blijft de tekst staan en wordt alleen de opname opnieuw gemaakt. Dat is de juiste weg als de tekst zit en alleen de stem of het tempo ernaast zat. Met false wordt ook de tekst herschreven.

Het veld note gaat rechtstreeks de nieuwe generatie in, dus een concrete zin loont. "Lagere mannenstem, langzamer" werkt, "beter maken" niet. Drie nieuwe generaties per lied zijn gratis, daarna even overleggen.

Betalen en vrijgeven

Er zijn twee manieren om een lied vrij te geven, afhankelijk van wie betaalt.

De eindklant betaalt

POST /v1/songs/{id}/checkout maakt een gehoste betaalpagina in de valuta van het domein, inclusief de betaalmethoden die in dat land gebruikelijk zijn. Je stuurt de klant erheen en krijgt na geslaagde betaling de gebeurtenis song.paid.

curl https://api.liedmaker.nl/v1/songs/sng_3n8Kd2ZpQv/checkout \
  -H "Authorization: Bearer $SONG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "success_url": "https://example.com/thanks?song=sng_3n8Kd2ZpQv",
    "cancel_url": "https://example.com/cart"
  }' 

{
  "object": "checkout_session",
  "song": "sng_3n8Kd2ZpQv",
  "url": "https://pay.liedmaker.nl/c/cs_live_8Hd2Kq...",
  "amount": 2999,
  "currency": "EUR",
  "expires_at": "2026-09-16T11:41:02Z"
}

Jij betaalt

Bij accounts met verzamelafrekening geeft POST /v1/songs/{id}/unlock het lied meteen vrij en boekt 29,99 € op het account. Geen omweg via een betaalpagina, handig bij een eigen kassasysteem.

curl https://api.liedmaker.nl/v1/songs/sng_3n8Kd2ZpQv/unlock \
  -H "Authorization: Bearer $SONG_API_KEY" \
  -X POST

In beide gevallen geldt hetzelfde gebruiksrecht: niet exclusief, maar uitdrukkelijk commercieel. Je mag het afgeronde lied binnen je eigen aanbod doorgeven, verkopen en publiceren.

Geldige waarden

De opsommingen voor gelegenheid, stemming, stijl, stem en taal veranderen af en toe. Bouw ze niet vast in, maar vraag GET /v1/options op en houd het resultaat een paar uur in de cache.

{
  "object": "options",
  "language": "nl",
  "occasions": ["birthday", "wedding", "anniversary", "farewell", "funeral",
                "christening", "graduation", "christmas", "declaration", "other"],
  "moods":     ["happy", "warm", "funny", "romantic", "gentle", "epic", "surprise_me"],
  "styles":    ["pop", "rock", "folk", "schlager", "hiphop", "ballad", "country",
                "electronic", "jazz", "childrens", "surprise_me"],
  "voices":    ["female", "male", "duet", "choir", "childrens", "surprise_me"],
  "languages": ["de", "en", "dk", "nl", "it", "se", "fr", "es", "no", "pl", "fi", "is", "jp"]
}

Elk van deze waarden mag ook worden weggelaten. De waarde surprise_me is geen plaatsvervanger maar een echte opdracht: we kiezen dan bewust iets dat bij de gelegenheid en de details past.

Webhooks

Geef bij het aanmaken een callback_url op, dan sturen we elke gebeurtenis als POST daarheen. Dat is de aanbevolen weg, omdat hij pollen en wachten bespaart.

{
  "id": "evt_5Tb7Rn2WqX",
  "object": "event",
  "type": "song.completed",
  "created_at": "2026-09-16T09:47:35Z",
  "data": {
    "object": {
      "id": "sng_3n8Kd2ZpQv",
      "object": "song",
      "status": "complete",
      "audio_url": "https://cdn.liedmaker.nl/full/sng_3n8Kd2ZpQv.mp3?expires=1789412855&sig=...",
      "...": "..."
    }
  }
}

Handtekening controleren

Elke aflevering draagt een header met tijdstempel en HMAC-SHA256 over tijdstempel, punt en ruwe body. Controleer hem voor je de inhoud gelooft, en gooi alles weg dat ouder is dan vijf minuten.

X-Song-Signature: t=1789412855,v1=7f2c1d9a4b6e8035c1f7a29d4e5b0c8371a6d2f94e8b3c07a15d9e2f6b4c8a01

import hashlib, hmac, os, time
from flask import Flask, request, abort

SECRET = os.environ["SONG_WEBHOOK_SECRET"].encode()
app = Flask(__name__)


@app.post("/hooks/songs")
def hook():
    header = request.headers.get("X-Song-Signature", "")
    parts = dict(p.split("=", 1) for p in header.split(",") if "=" in p)
    timestamp, signature = parts.get("t", ""), parts.get("v1", "")

    if abs(time.time() - int(timestamp or 0)) > 300:
        abort(400)  # older than five minutes, treat as replay

    expected = hmac.new(
        SECRET, (timestamp + "." + request.get_data(as_text=True)).encode(),
        hashlib.sha256,
    ).hexdigest()

    if not hmac.compare_digest(expected, signature):
        abort(400)

    event = request.get_json()
    if event["type"] == "song.completed":
        store(event["data"]["object"])

    return "", 200

Herhalingen

We verwachten binnen tien seconden een antwoord met status 2xx. Blijft dat uit, dan herhalen we acht keer over 24 uur met groeiende tussenpozen. Afleveringen kunnen zich daarbij herhalen en in zeldzame gevallen van volgorde wisselen, dus maak je endpoint idempotent en ga uit van created_at, niet van het moment van aankomst.

Idempotentie

Elke POST accepteert de header Idempotency-Key met een willekeurige unieke waarde, meestal een UUID. Komt dezelfde sleutel binnen 24 uur opnieuw binnen, dan geven we het oorspronkelijke antwoord terug in plaats van een tweede lied te maken.

curl https://api.liedmaker.nl/v1/songs \
  -H "Authorization: Bearer $SONG_API_KEY" \
  -H "Idempotency-Key: 9f1c7c2e-0a3b-4c8d-9e21-5f7a1b6c3d40" \
  -H "Content-Type: application/json" \
  -d '{ "occasion": "birthday", "recipient_name": "Anna", "language": "nl", "details": "..." }' 

Dat is precies de bescherming die je bij netwerkfouten nodig hebt: raakt een antwoord kwijt en herhaalt je code de aanvraag, dan ontstaat er toch maar één lied. Stuur je dezelfde sleutel met een afwijkende body, dan antwoorden we met 409 en het fouttype conflict.

Fouten

Fouten komen altijd in hetzelfde formaat, met machineleesbaar type en code, een leesbare melding en, waar het helpt, het betrokken veld. De request_id hoort in elke supportvraag, zodat we de aanvraag in de logs kunnen vinden.

{
  "error": {
    "type": "validation_error",
    "code": "details_too_short",
    "message": "details must contain at least 40 characters so the song has something to work with",
    "param": "details",
    "request_id": "req_2Lm9Xc4Kd1"
  }
}

Bij 429 en 5xx is herhalen zinvol, het liefst met exponentieel groeiende tussenpozen en wat toeval. Bij 4xx anders dan 429 niet: dezelfde aanvraag mislukt opnieuw.

Limieten

Elk antwoord draagt de actuele stand in de headers, zodat je niet hoeft te gokken.

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 57
X-RateLimit-Reset: 1789412880
X-Concurrent-Limit: 10
X-Concurrent-Running: 3

Hogere limieten zijn geen probleem, ze zijn alleen niet de standaard. Groeit je volume, schrijf ons dan kort, dan verhogen we ze.

Versiebeheer

De hoofdversie staat in het pad en blijft stabiel. Binnen v1 komen er alleen toevoegingen: nieuwe velden, nieuwe waarden in opsommingen, nieuwe endpoints. Bestaande velden verdwijnen niet en veranderen niet van betekenis.

Wil je extra zekerheid, pin dan een datum in een header. Zonder header geldt altijd de nieuwste stand.

X-Song-Version: 2026-09-01

Je code zou onbekende velden in antwoorden moeten negeren in plaats van erop te stranden. Dat is de enige aanname die wij over clients doen.

Testmodus

Sleutels met het voorvoegsel sk_test_ lopen door precies dezelfde endpoints, maar leiden niet tot een echte productie en kosten niets. Na enkele seconden krijg je een vaste demotekst en een demo-opname, en alle objecten dragen livemode: false.

Daarmee kun je ook de vervelende gevallen oefenen. Bepaalde namen in het veld recipient_name dwingen een bepaalde afloop af: test_fail leidt tot failed, test_slow tot een productie van ongeveer tien minuten, test_ratelimit tot een 429-antwoord. Zo test je de foutafhandeling zonder op een echte storing te wachten.

Webhooks werken in testmodus ook, met hetzelfde handtekeningmechanisme en een eigen geheim.

Rechten en gegevens

Met de vrijgave krijg je een niet-exclusief, maar uitdrukkelijk commercieel gebruiksrecht op het afgeronde lied. Je mag het doorgeven, verkopen, openbaar afspelen en in je eigen product opnemen. Niet exclusief betekent: wij houden het recht de opname zelf te gebruiken, bijvoorbeeld als voorbeeld.

Over het auteursrecht op door AI gemaakte muziek is in veel rechtsstelsels nog geen uitsluitsel. Wij verzekeren je het gebruik contractueel, maar kunnen niet toezeggen dat op de opname een eigen auteursrecht ontstaat dat je tegen derden kunt afdwingen. Wie daarvan afhankelijk is, laat dat beter vooraf juridisch toetsen.

Invoer en afgeronde liedjes bewaren we 90 dagen, daarna worden ze gewist. Een enkel lied eerder wissen kan via DELETE /v1/songs/{id}. De gegevens uit details gebruiken we uitsluitend voor de productie van dat ene lied en niet om eigen modellen te trainen.

Stuur je gegevens van je klanten naar ons, dan ben jij verwerkingsverantwoordelijke en zijn wij verwerker. Een verwerkersovereenkomst krijg je op aanvraag.

Support

Vragen, hogere limieten, verwerkersovereenkomst, bijzondere gevallen: songs@maxkuch.com. Noem bij technische problemen de request_id uit het foutantwoord, dan vinden we de aanvraag meteen.

Voor integraties via AI-agenten is er daarnaast een Model Context Protocol-server. Die is gedocumenteerd op /mcp/ en gebruikt dezelfde sleutels als de REST-API.