API-skjölun

Inngangur

Viðmótið gerir nákvæmlega það sama og vefsíðan. Þú sendir tilefnið, nafn þess sem lagið er um og nokkur áþreifanleg atriði. Úr því verður fyrst fullbúinn texti og síðan framleidd upptaka með söng, útsetningu og hljóðblöndun. Allt ferlið tekur venjulega fimm til tíu mínútur.

Allar fyrirspurnir fara á https://api.lagid.is/v1. Viðmótið talar aðeins HTTPS, tekur við JSON og svarar með JSON. Ekkert SDK er skylda: hvaða mál sem kann HTTP dugar. Dæmin á þessari síðu nota curl, Python og Node, því það eru þrjú algengustu tilvikin.

Hvert lén hefur sitt eigið grunnslóð og sitt eigið verð í staðbundinni mynt. Lykillinn virkar fyrir það lén sem hann var gefinn út fyrir. Sá sem sinnir mörgum mörkuðum fær annaðhvort marga lykla eða einn lykil opinn fyrir mörg lén.

Aðgangur

Það er vísvitandi engin sjálfvirk skráning. Lyklar eru gefnir út handvirkt, því á bak við hvert lag liggur raunverulegur framleiðslukostnaður og við viljum vita í hvað samþættingin fer. Í reynd snýst þetta um stutt skeyti og einn virkan dag.

Skrifaðu á songs@maxkuch.com og segðu fjóra hluti:

• Hvað þú ætlar að smíða, í tveimur eða þremur setningum.
• Áætlað magn á mánuði.
• Á hvaða tungumálum á að syngja.
• Hvort þú tekur við webhook-tilkynningum eða vilt spyrja viðmótið um stöðu.

Þú færð tvo lykla: prófunarlykil með forskeytinu sk_test_, sem er ókeypis og skilar föstum sýnishornum, og framleiðslulykil með forskeytinu sk_live_. Báðir virka strax, engir endapunktar þarf að opna sérstaklega.

Auðkenning

Hver fyrirspurn ber lykilinn í Authorization-hausnum sem bearer-tákn. Fyrirspurnir án gilds hauss fá 401 og villugerðina authentication_error.

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

Farðu með lykilinn eins og lykilorð: aðeins á þjónsvélinni, aldrei í kóða í vafranum, aldrei í opinberu geymslusafni. Leki lykill út, skrifaðu okkur: við lokum honum strax og gefum út nýjan. Reikningur getur haft marga gilda lykla, svo skipti ganga án rofs.

Prófunar- og framleiðslulyklar nota sömu endapunkta. Reiturinn livemode sýnir í hverjum hlut hvort fyrirspurnin fór í prófunarham.

Fljótleg byrjun

Að búa til lag er eitt kall. Svarið kemur strax og inniheldur auðkenni í stöðunni queued. Allt hitt gerist í bakgrunni.

import os, time, requests

API = "https://api.lagid.is/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": "is",
    "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"])

Dæmið spyr á fimm sekúndna fresti til einföldunar. Í rekstri eru webhook-tilkynningar betri leið, því þær spara bæði opna tengingu og biðina. Báðar leiðir eru studdar, webhook er lýst neðar.

Reiturinn sem ræður úrslitum er details. Þangað fara áþreifanlegu atriðin um manneskjuna: gælunafn, sérviska, frí sem fór úrskeiðis. Almennar setningar á borð við "hún er hlý manneskja" gefa almennar línur. Þrjú til fimm áþreifanleg atriði duga og þau ráða því hvort lagið er bara notalegt eða raunverulega um einhvern.

Endapunktar í stuttu máli

Að búa til lag

POST /v1/songs tekur við lýsingunni og fer strax af stað. Aðeins þrír reitir eru skylda, hinir hafa skynsamlegt sjálfgefið gildi eða eru valdir eftir tilefninu.

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

Laghluturinn

Sérhver endapunktur sem skilar einu lagi skilar sama hlut. Reitir sem eru ekki til enn eru null og fyllast eftir því sem framleiðslunni vindur fram.

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

Stöðugildi

Lagið fer í gegnum stöðurnar í þessari röð. Aldrei er farið til baka og complete, failed og cancelled eru lokastöður.

Ein misheppnuð framleiðslutilraun leiðir ekki strax til failed. Við reynum nokkrum sinnum innanhúss og gefumst fyrst upp þegar allar tilraunir bregðast. Þess vegna er failed sjaldgæft og þýðir í raun: þetta lag kemur ekki.

Að sækja og telja upp

GET /v1/songs/{id} skilar núverandi stöðu lagsins. Endapunkturinn er léttur og þolir fyrirspurn á sekúndu fresti, svo lengi sem þú heldur þig innan tíðnimarkanna.

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

Listar vinna með bendli. Þú færð mest limit færslur, sjálfgefið 20 og mest 100, frá þeim nýjustu. Sé has_more satt sendirðu next_cursor sem starting_after í næsta kalli. Sía má eftir 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"
}

Texti og hljóð

Textinn er ókeypis og heill, ekki brot. GET /v1/songs/{id}/lyrics skilar honum sem text/plain, með merkingum fyrir erindi og viðlag. Sami texti stendur í reitnum lyrics í laghlutnum.

Í hljóðinu eru tvö þrep. Sýnishornið er fyrstu 45 sekúndur fullbúinnar upptöku, ekki sérstök prufa: sama rödd, sama útsetning, sami texti. Það er til staðar án greiðslu og verður það áfram. Heila skrá afhendir GET /v1/songs/{id}/audio fyrst eftir opnun.

Báðar slóðir eru undirritaðar og gilda í 24 klukkustundir. Þær eru til niðurhals, ekki til varanlegrar tengingar. Þurfirðu skrána lengur, sæktu hana einu sinni og geymdu sjálf. Nýtt kall á endapunktinn gefur ferska slóð hvenær sem er.

Sniðið er alltaf MP3 320 kbit/s. Sá sem þarf WAV bætir við ?format=wav, í boði fyrir reikninga með stúdíóvalkosti.

Endurgerð

Sannfæri niðurstaðan ekki kostar endurgerð ekkert. POST /v1/songs/{id}/regenerate býr til nýja útgáfu undir sama auðkenni og setur stöðuna aftur í queued. Fyrri útgáfan varðveitist undir previous_versions.

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

Með keep_lyrics: true helst textinn og aðeins upptakan er gerð upp á nýtt. Það er rétta leiðin þegar textinn situr og aðeins röddin eða hraðinn brást. Með false er textinn líka skrifaður upp á nýtt.

Reiturinn note fer beint inn í endurgerðina, svo áþreifanleg setning borgar sig. "Dýpri karlrödd, hægar" virkar, "gerðu betur" ekki. Þrjár endurgerðir á lag eru ókeypis, umfram það skrifaðu okkur.

Greiðsla og opnun

Það eru tvær leiðir til að opna lag, eftir því hver greiðir.

Lokakaupandinn greiðir

POST /v1/songs/{id}/checkout býr til greiðslusíðu hjá okkur í mynt lénsins, með þeim greiðslumátum sem tíðkast í landinu. Þú sendir viðskiptavininn þangað og færð atburðinn song.paid þegar greiðslan gengur í gegn.

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

Þú greiðir

Á reikningum með safnreikningi opnar POST /v1/songs/{id}/unlock lagið strax og skuldfærir 3.490 kr. Án krókaleiðar um greiðslusíðu, þægilegt þegar eigin kassi er til staðar.

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

Í báðum tilvikum gildir sami notkunarréttur: ekki einkaréttur en ótvírætt í atvinnuskyni. Fullbúna lagið máttu afhenda áfram, selja og birta sem hluta af eigin framboði.

Leyfileg gildi

Listar yfir tilefni, stemningar, stíla, raddir og tungumál breytast öðru hverju. Í stað þess að skrifa þau fast í kóðann skaltu spyrja GET /v1/options og geyma svarið í skyndiminni í nokkrar klukkustundir.

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

Öllum þessum gildum má líka sleppa. Gildið surprise_me er ekki uppfylling heldur raunveruleg fyrirmæli: þá veljum við vísvitandi eitthvað sem hæfir tilefninu og atriðunum.

Webhook

Gefðu upp callback_url við stofnun og við sendum hvern atburð þangað með POST. Það er ráðlagða leiðin, því hún sparar fyrirspurnir og bið.

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

Að sannreyna undirskrift

Hver sending ber haus með tímastimpli og HMAC-SHA256 yfir tímastimpil, punkt og hrátt meginmál. Sannreyndu hann áður en þú treystir innihaldinu og hafnaðu öllu sem er eldra en fimm mínútur.

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

Endurtekningar

Við væntum 2xx-svars innan tíu sekúndna. Komi það ekki reynum við átta sinnum á 24 klukkustundum með vaxandi millibili. Sendingar geta því endurtekið sig og í sjaldgæfum tilvikum komið í rangri röð: gerðu endapunktinn þinn einkvæman og treystu reitnum created_at, ekki komutímanum.

Einkvæmni

Sérhver POST tekur við hausnum Idempotency-Key með hvaða einkvæmu gildi sem er, venjulega UUID. Komi sami lykill aftur innan 24 klukkustunda skilum við upphaflega svarinu í stað þess að búa til annað lag.

curl https://api.lagid.is/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": "is", "details": "..." }' 

Þetta er einmitt vörnin sem þarf við netvillur: glatist svarið og kóðinn þinn endurtaki fyrirspurnina verður samt eitt lag til. Sendirðu sama lykil með öðru meginmáli svörum við með 409 og villugerðinni conflict.

Villur

Villur koma alltaf í sama formi, með vélleshæfu type og code, læsilegum skilaboðum og, þar sem það á við, tilvísun í reit. Láttu request_id fylgja hverri fyrirspurn til okkar, þá finnum við kallið í annálunum.

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

Við 429 og 5xx borgar sig að reyna aftur, helst með veldisvaxandi millibili og örlítilli slembni. Við önnur 4xx en 429 ekki: sama fyrirspurn bregst aftur.

Mörk

Hvert svar ber núverandi stöðu í hausum, svo þú þarft ekki að giska.

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

Hærri mörk eru ekkert vandamál, þau eru bara ekki upphafsstillingin. Vaxi magnið skrifaðu tvær setningar og við hækkum þau.

Útgáfustýring

Aðalútgáfan stendur í slóðinni og helst stöðug. Innan v1 koma aðeins viðbætandi breytingar: nýir reitir, ný gildi í listum, nýir endapunktar. Reitir sem eru til hverfa ekki og skipta ekki um merkingu.

Til enn meira öryggis máttu festa dagsetningu í haus. Án hauss gildir alltaf nýjasta hegðunin.

X-Song-Version: 2026-09-01

Kóðinn þinn á að hunsa óþekkta reiti í svörum, ekki falla á þeim. Það er eina forsendan sem við gefum okkur um viðskiptavini.

Prófunarhamur

Lyklar með forskeytinu sk_test_ fara í gegnum nákvæmlega sömu endapunkta en ræsa enga raunverulega framleiðslu og kosta ekkert. Eftir fáeinar sekúndur færðu fastan sýnitexta og sýniupptöku, og hver hlutur ber livemode: false.

Þannig má líka æfa leiðinlegu tilvikin. Tiltekin nöfn í reitnum recipient_name þvinga fram tiltekna niðurstöðu: test_fail leiðir til failed, test_slow til framleiðslu sem tekur um tíu mínútur, test_ratelimit til svars 429. Villumeðhöndlun má því prófa án þess að bíða eftir raunverulegri bilun.

Webhook virkar líka í prófunarham, með sömu undirskriftaraðferð og eigin leynilykli.

Réttindi og gögn

Með opnuninni færðu notkunarrétt á fullbúna laginu sem er ekki einkaréttur en ótvírætt í atvinnuskyni. Þú mátt afhenda það áfram, selja það, flytja það opinberlega og setja það inn í eigin vöru. Ekki einkaréttur þýðir að við höldum réttinum til að nota upptökuna líka sjálf, til dæmis sem dæmi.

Um höfundarétt á tónlist sem gervigreind býr til hafa mörg réttarkerfi ekki enn endanlegt svar. Notkunarréttinn tryggjum við með samningi, en við getum ekki fullyrt að sjálfstæður höfundaréttur gagnvart þriðja aðila verði til á upptökunni. Sá sem reiðir sig á það ætti að kanna málið fyrirfram.

Aðföng og fullbúin lög geymum við í 90 daga, síðan er þeim eytt. Til að eyða einu lagi fyrr er DELETE /v1/songs/{id}. Upplýsingar úr details notum við eingöngu til að framleiða þetta eina lag og aldrei til að þjálfa eigin líkön.

Sendir þú okkur gögn viðskiptavina þinna ert þú ábyrgðaraðili og við vinnsluaðili. Vinnslusamningur er fáanlegur sé eftir honum leitað.

Aðstoð

Spurningar, hærri mörk, vinnslusamningur, sérstök tilvik: songs@maxkuch.com. Við tæknileg vandamál láttu request_id úr villusvarinu fylgja, þá finnum við kallið strax.

Fyrir samþættingu gegnum gervigreindarumboð er að auki Model Context Protocol-þjónn, lýst á /mcp/, með sömu lyklum og REST-viðmótið.