API-dokumentasjon

Innledning

API-et gjør akkurat det nettsiden gjør. Du sender inn en anledning, navnet på den sangen handler om og noen konkrete detaljer. Av det vokser først en ferdig tekst, deretter et produsert opptak med sang, arrangement og miks. Hele veien tar normalt fem til ti minutter.

Alle kall går til https://api.lagsang.com/v1. API-et snakker bare HTTPS, tar imot JSON og svarer med JSON. Det finnes ingen obligatorisk SDK: hvilket som helst språk som kan HTTP holder. Eksemplene på denne siden bruker curl, Python og Node, fordi det er de tre vanligste tilfellene.

Hvert domene har sin egen API-base og sin egen pris i lokal valuta. En nøkkel gjelder for domenet den ble utstedt for. Den som betjener flere markeder får flere nøkler eller en nøkkel som er åpnet for flere domener.

Tilgang

Det finnes bevisst ingen automatisk registrering. Vi deler ut nøkler for hånd, fordi hver sang innebærer reelle produksjonskostnader og vi vil vite hva integrasjonen skal brukes til. I praksis handler det om en kort e-post og én virkedag.

Skriv til songs@maxkuch.com og nevn fire ting:

• Hva du vil bygge, i to eller tre setninger.
• Omtrentlig volum per måned.
• Hvilke språk sangene skal synges på.
• Om du kan ta imot webhooks eller heller vil spørre API-et.

Du får to nøkler: en testnøkkel med prefikset sk_test_, gratis, som leverer faste demoopptak, og en livenøkkel med prefikset sk_live_. Begge virker med én gang, uten at enkeltendepunkter må åpnes.

Autentisering

Hvert kall bærer nøkkelen i Authorization-headeren som bearer-token. Kall uten gyldig header får 401 og feiltypen authentication_error.

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

Behandle nøkkelen som et passord: bare på serversiden, aldri i frontend-kode, aldri i et åpent repositorium. Hvis en nøkkel kommer på avveie, skriv til oss: vi sperrer den umiddelbart og utsteder en ny. En konto kan ha flere aktive nøkler, så bytte skjer uten avbrudd.

Test- og livenøkler deler de samme endepunktene. Om et kall skjedde i testmodus, framgår av feltet livemode i hvert objekt.

Hurtigstart

Å lage en sang er ett enkelt kall. Svaret kommer med én gang og inneholder en id med status queued. Alt annet skjer i bakgrunnen.

import os, time, requests

API = "https://api.lagsang.com/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": "no",
    "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"])

For enkelhets skyld spør eksemplet hvert femte sekund. I produksjon er webhooks den bedre veien, fordi de sparer både åpen forbindelse og venting. Begge deler støttes, webhooks er beskrevet lenger ned.

Det avgjørende feltet er details. Der hører det konkrete om personen hjemme: kallenavnet, maniene, ferien som gikk galt. Generelle setninger som "hun er et varmt menneske" gir generelle linjer. Tre til fem konkrete detaljer holder, og de er forskjellen mellom en hyggelig sang og en sang som virkelig handler om noen.

Endepunktene kort fortalt

Lage en sang

POST /v1/songs tar imot briefen og starter med én gang. Bare tre felt er obligatoriske, alle andre har fornuftige standardverdier eller velges ut fra anledningen.

const res = await fetch("https://api.lagsang.com/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: "no",
    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);

Sangobjektet

Hvert endepunkt som leverer en enkelt sang leverer det samme objektet. Felt som ennå ikke finnes er null og fylles ut under produksjonen.

{
  "id": "sng_3n8Kd2ZpQv",
  "object": "song",
  "status": "queued",
  "created_at": "2026-09-16T09:41:02Z",
  "occasion": "birthday",
  "recipient_name": "Anna",
  "relationship": "sister",
  "language": "no",
  "mood": "happy",
  "style": "pop",
  "voice": "female",
  "lyrics": null,
  "preview_url": null,
  "audio_url": null,
  "duration_seconds": null,
  "paid": false,
  "price": { "amount": 2999, "currency": "NOK" },
  "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.lagsang.com/preview/sng_3n8Kd2ZpQv.mp3",
  "audio_url": "https://cdn.lagsang.com/full/sng_3n8Kd2ZpQv.mp3?expires=1789412855&sig=...",
  "duration_seconds": 184,
  "paid": true,
  "price": { "amount": 2999, "currency": "NOK" },
  "metadata": { "order_id": "A-10423" },
  "livemode": true
}

Statusverdier

En sang går gjennom tilstandene i denne rekkefølgen. Den går aldri bakover, og complete, failed og cancelled er sluttilstander.

Et enkelt mislykket produksjonsforsøk fører ikke direkte til failed. Internt prøver vi flere ganger og gir opp først når alle forsøk mislykkes. Derfor er failed sjelden og betyr virkelig: denne sangen kommer ikke.

Hente og liste

GET /v1/songs/{id} leverer den aktuelle tilstanden til en sang. Endepunktet er lett og tåler å bli spurt hvert sekund, så lenge du holder deg innenfor frekvensgrensen.

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

Lister er markørbaserte. Du får høyst limit oppføringer, 20 som standard og 100 som mest, med de nyeste først. Er has_more sann, sender du next_cursor som starting_after i neste kall. Du kan filtrere på status, occasion, language, paid samt created_after og 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"
}

Tekst og lyd

Teksten er gratis og fullstendig, ikke et utdrag. GET /v1/songs/{id}/lyrics leverer den som text/plain, med vers- og refrengmarkeringer. Den samme teksten står i feltet lyrics i sangobjektet.

For lyden finnes to nivåer. Forhåndslyttingen er de første 45 sekundene av det ferdige opptaket, ikke en egen demo: samme stemme, samme arrangement, samme tekst. Den finnes uten betaling og blir værende. Hele filen leverer GET /v1/songs/{id}/audio først etter opplåsing.

Begge adressene er signert og gyldige i 24 timer. De er til nedlasting, ikke til permanent lenking. Trenger du en fil lenger, last den ned én gang og lagre den selv. Et nytt kall mot endepunktet gir når som helst en fersk adresse.

Formatet er alltid MP3 med 320 kbit/s. Den som trenger WAV legger til ?format=wav, tilgjengelig for kontoer med studiovalget.

Generere på nytt

Hvis et resultat ikke overbeviser, koster en ny generering ingenting. POST /v1/songs/{id}/regenerate lager en ny versjon under samme id og setter statusen tilbake til queued. Den forrige versjonen blir liggende under previous_versions.

curl https://api.lagsang.com/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."
  }' 

Med keep_lyrics: true blir teksten stående og bare opptaket gjøres på nytt. Det er riktig vei når teksten sitter og bare stemmen eller tempoet var feil. Med false skrives også teksten om.

Feltet note går rett inn i den nye genereringen, så en konkret setning lønner seg. "Dypere mannsstemme, langsommere" virker, "gjør den bedre" gjør det ikke. Tre nye genereringer per sang er gratis, utover det ta kontakt.

Betaling og opplåsing

Det finnes to måter å låse opp en sang på, avhengig av hvem som betaler.

Sluttkunden betaler

POST /v1/songs/{id}/checkout lager en betalingsside hos oss i domenets valuta, med betalingsmåtene som er vanlige i det landet. Du sender kunden dit og får hendelsen song.paid når betalingen går gjennom.

curl https://api.lagsang.com/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.lagsang.com/c/cs_live_8Hd2Kq...",
  "amount": 2999,
  "currency": "NOK",
  "expires_at": "2026-09-16T11:41:02Z"
}

Du betaler

På kontoer med samlefakturering låser POST /v1/songs/{id}/unlock opp sangen med én gang og belaster kontoen med 299 kr. Ingen omvei via en betalingsside, praktisk når du har din egen kasse.

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

I begge tilfeller gjelder den samme bruksretten: ikke-eksklusiv, men uttrykkelig kommersiell. Du kan gi videre, selge og publisere den ferdige sangen innenfor ditt eget tilbud.

Gyldige verdier

Listene over anledning, stemning, stil, stemme og språk endrer seg av og til. Skriv dem ikke inn i koden, spør GET /v1/options og hold svaret i cache noen timer.

{
  "object": "options",
  "language": "no",
  "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"]
}

Hver av disse verdiene kan også utelates. Verdien surprise_me er ingen plassholder, men en ekte instruks: da velger vi bevisst noe som passer anledningen og detaljene.

Webhooks

Oppgi en callback_url ved opprettelsen, så sender vi hver hendelse dit med en POST. Det er den anbefalte veien fordi den sparer gjentatte spørringer og venting.

{
  "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.lagsang.com/full/sng_3n8Kd2ZpQv.mp3?expires=1789412855&sig=...",
      "...": "..."
    }
  }
}

Kontrollere signaturen

Hver levering bærer en header med tidsstempel og HMAC-SHA256 over tidsstempel, punktum og den rå kroppen. Kontroller den før du stoler på innholdet, og kast alt som er eldre enn fem minutter.

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

Gjentakelser

Vi venter et 2xx-svar innen ti sekunder. Uteblir det, prøver vi åtte ganger i løpet av 24 timer med økende mellomrom. Leveringer kan altså gjentas og i sjeldne tilfeller komme i feil rekkefølge: gjør endepunktet ditt idempotent og stol på created_at, ikke på ankomsttiden.

Idempotens

Hver POST tar imot headeren Idempotency-Key med en vilkårlig unik verdi, som oftest en UUID. Kommer den samme nøkkelen tilbake innen 24 timer, leverer vi det opprinnelige svaret i stedet for å lage en ny sang.

curl https://api.lagsang.com/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": "no", "details": "..." }' 

Det er nøyaktig den beskyttelsen som trengs mot nettverksfeil: går et svar tapt og koden din gjentar kallet, blir det likevel bare én sang. Sender du den samme nøkkelen med en annen kropp, svarer vi 409 med feiltypen conflict.

Feil

Feil kommer alltid i samme form, med maskinlesbare type og code, en lesbar melding og der det er relevant det berørte feltet. Ta med request_id i hvert supportspørsmål, så finner vi kallet i loggene.

{
  "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"
  }
}

Ved 429 og 5xx er det meningsfullt å prøve igjen, helst med eksponentielt økende mellomrom og litt tilfeldighet. Ved andre 4xx enn 429 er det det ikke: det samme kallet mislykkes igjen.

Grenser

Hvert svar bærer den aktuelle tilstanden i headerne, så du slipper å gjette.

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

Høyere grenser er ikke noe problem, de er bare ikke utgangspunktet. Vokser volumet, skriv to linjer så hever vi dem.

Versjonering

Hovedversjonen står i stien og ligger fast. Innenfor v1 kommer bare tillegg: nye felt, nye verdier i lister, nye endepunkter. Eksisterende felt forsvinner ikke og skifter ikke betydning.

For ekstra sikkerhet kan du låse en dato i en header. Uten header gjelder alltid den nyeste oppførselen.

X-Song-Version: 2026-09-01

Koden din bør ignorere ukjente felt i svarene i stedet for å gå i stykker. Det er den eneste antakelsen vi gjør om klienter.

Testmodus

Nøkler med prefikset sk_test_ går gjennom nøyaktig de samme endepunktene, men starter ingen ekte produksjon og koster ingenting. Etter noen sekunder får du en fast demotekst og et demoopptak, og hvert objekt bærer livemode: false.

Slik lar også de ubehagelige tilfellene seg prøve. Enkelte navn i feltet recipient_name tvinger fram et bestemt utfall: test_fail fører til failed, test_slow til en produksjon på omtrent ti minutter, test_ratelimit til et 429-svar. Du kan altså teste feilhåndteringen uten å vente på et ekte avbrudd.

Webhooks virker også i testmodus, med samme signaturmekanisme og en egen hemmelighet.

Rettigheter og data

Med opplåsingen får du en ikke-eksklusiv, men uttrykkelig kommersiell bruksrett til den ferdige sangen. Du kan gi den videre, selge den, framføre den offentlig og bygge den inn i produktet ditt. Ikke-eksklusiv betyr at vi beholder retten til selv å bruke opptaket, for eksempel som eksempel.

Når det gjelder opphavsrett til musikk laget med kunstig intelligens, har mange rettsordener ennå ikke noe endelig svar. Vi gir deg bruksretten avtalemessig, men kan ikke garantere at det oppstår en egen opphavsrett til opptaket som holder mot tredjeparter. Den som er avhengig av det, bør få saken vurdert på forhånd.

Vi beholder inndata og ferdige sanger i 90 dager, deretter slettes de. For å slette en enkelt sang tidligere finnes DELETE /v1/songs/{id}. Opplysningene i details bruker vi bare til å produsere akkurat den sangen og aldri til å trene egne modeller.

Sender du kundenes opplysninger til oss, er du behandlingsansvarlig og vi databehandler. En databehandleravtale finnes på forespørsel.

Support

Spørsmål, høyere grenser, databehandleravtale, særlige tilfeller: songs@maxkuch.com. Ved tekniske problemer, oppgi request_id fra feilsvaret, så finner vi kallet med én gang.

For integrasjoner via KI-agenter finnes i tillegg en Model Context Protocol-server, dokumentert på /mcp/, som bruker de samme nøklene som REST-API-et.