API-dokumentaatio

Johdanto

Rajapinta tekee täsmälleen saman kuin verkkosivu. Lähetät tilaisuuden, laulun kohteen nimen ja muutaman konkreettisen yksityiskohdan. Siitä syntyy ensin valmis sanoitus ja sen jälkeen tuotettu äänite laulun, sovituksen ja miksauksen kera. Koko matka kestää tavallisesti kahdesta kolmeen minuuttia.

Kaikki pyynnöt menevät osoitteeseen https://api.tekoalylaulu.fi/v1. Rajapinta puhuu vain HTTPS:ää, ottaa vastaan JSONia ja vastaa JSONilla. Pakollista SDK:ta ei ole: mikä tahansa kieli, joka osaa HTTP:n, riittää. Tämän sivun esimerkit käyttävät curlia, Pythonia ja Nodea, koska ne ovat kolme yleisintä tapausta.

Jokaisella verkkotunnuksella on oma rajapinnan perusosoite ja oma hinta paikallisessa valuutassa. Avain toimii sillä verkkotunnuksella, jolle se on myönnetty. Useaa markkinaa hoitava saa joko useita avaimia tai yhden avaimen, joka on avattu useaan verkkotunnukseen.

Käyttöoikeus

Automaattista rekisteröitymistä ei tietoisesti ole. Avaimet jaetaan käsin, koska jokaisen laulun takana on todellisia tuotantokustannuksia ja haluamme tietää, mihin integraatio menee. Käytännössä kyse on lyhyestä viestistä ja yhdestä arkipäivästä.

Kirjoita osoitteeseen songs@maxkuch.com ja kerro neljä asiaa:

• Mitä olet rakentamassa, parilla kolmella lauseella.
• Arvioitu määrä kuukaudessa.
• Millä kielillä laulujen pitää laulaa.
• Otatko vastaan webhookeja vai kyselläänkö tila rajapinnasta.

Saat kaksi avainta: testiavaimen etuliitteellä sk_test_, joka on maksuton ja palauttaa kiinteitä esittelyääniä, sekä tuotantoavaimen etuliitteellä sk_live_. Molemmat toimivat heti, yksittäisiä päätepisteitä ei tarvitse avata erikseen.

Tunnistautuminen

Jokainen pyyntö kuljettaa avaimen Authorization-otsakkeessa bearer-tunnisteena. Ilman kelvollista otsaketta vastaus on 401 ja virhetyyppi authentication_error.

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

Käsittele avainta kuin salasanaa: vain palvelinpuolella, ei koskaan selainkoodissa eikä julkisessa repositoriossa. Jos avain vuotaa, kirjoita meille: suljemme sen heti ja myönnämme uuden. Tilillä voi olla useita voimassa olevia avaimia, joten vaihto onnistuu ilman katkoa.

Testi- ja tuotantoavaimet käyttävät samoja päätepisteitä. Kentästä livemode näkee jokaisessa objektissa, menikö pyyntö testitilassa.

Pikaopas

Laulun luonti on yksi kutsu. Vastaus tulee heti ja sisältää tunnisteen tilassa queued. Kaikki muu tapahtuu taustalla.

import os, time, requests

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

Esimerkki kysyy tilaa viiden sekunnin välein yksinkertaisuuden vuoksi. Tuotannossa webhookit ovat parempi tie, koska ne säästävät sekä avoimen yhteyden että odottelun. Molemmat tavat on tuettu, webhookit kuvataan alempana.

Ratkaiseva kenttä on details. Sinne menevät konkreettiset asiat henkilöstä: lempinimi, erikoisuus, loma joka meni pieleen. Yleiset lauseet tyyliin "hän on lämmin ihminen" tuottavat yleisiä säkeitä. Kolmesta viiteen konkreettista yksityiskohtaa riittää, ja juuri ne ratkaisevat, onko laulu vain mukava vai oikeasti jostakusta.

Päätepisteet lyhyesti

Laulun luonti

POST /v1/songs ottaa vastaan toimeksiannon ja käynnistyy heti. Pakollisia on vain kolme kenttää, muilla on järkevä oletus tai ne valitaan tilaisuuden mukaan.

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

Lauluobjekti

Jokainen yksittäisen laulun palauttava päätepiste palauttaa saman objektin. Kentät, joita ei vielä ole, ovat null ja täyttyvät tuotannon edetessä.

{
  "id": "sng_3n8Kd2ZpQv",
  "object": "song",
  "status": "queued",
  "created_at": "2026-09-16T09:41:02Z",
  "occasion": "birthday",
  "recipient_name": "Anna",
  "relationship": "sister",
  "language": "fi",
  "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.tekoalylaulu.fi/preview/sng_3n8Kd2ZpQv.mp3",
  "audio_url": "https://cdn.tekoalylaulu.fi/full/sng_3n8Kd2ZpQv.mp3?expires=1789412855&sig=...",
  "duration_seconds": 184,
  "paid": true,
  "price": { "amount": 2999, "currency": "EUR" },
  "metadata": { "order_id": "A-10423" },
  "livemode": true
}

Tila-arvot

Laulu kulkee vaiheet tässä järjestyksessä. Taaksepäin ei mennä, ja complete, failed ja cancelled ovat lopputiloja.

Yksittäinen epäonnistunut tuotantoyritys ei johda heti tilaan failed. Yritämme sisäisesti useamman kerran ja luovutamme vasta, kun kaikki yritykset kaatuvat. Siksi failed on harvinainen ja tarkoittaa todella: tätä laulua ei tule.

Haku ja listaus

GET /v1/songs/{id} palauttaa laulun nykytilan. Päätepiste on kevyt ja kestää sekunnin välein kyselyn, kunhan pysyt taajuusrajan sisällä.

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

Listat toimivat kursorilla. Saat enintään limit kohdetta, oletuksena 20 ja enintään 100, uusimmasta alkaen. Jos has_more on tosi, annat arvon next_cursor seuraavassa kutsussa kenttään starting_after. Suodattaa voi kentillä status, occasion, language, paid sekä created_after ja 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"
}

Sanoitus ja ääni

Sanoitus on maksuton ja täysi, ei katkelma. GET /v1/songs/{id}/lyrics palauttaa sen muodossa text/plain, säkeistö- ja kertosäemerkintöineen. Sama sanoitus on lauluobjektin kentässä lyrics.

Äänessä on kaksi tasoa. Esikuuntelu on valmiin äänitteen ensimmäiset 45 sekuntia, ei erillinen demo: sama ääni, sama sovitus, sama sanoitus. Se on saatavilla ilman maksua ja pysyy niin. Koko tiedoston antaa GET /v1/songs/{id}/audio vasta avauksen jälkeen.

Molemmat osoitteet ovat allekirjoitettuja ja voimassa 24 tuntia. Ne on tarkoitettu lataamiseen, ei pysyväksi linkiksi. Jos tarvitset tiedostoa pidempään, lataa se kerran ja säilytä itse. Päätepisteen uusi kutsu antaa milloin tahansa tuoreen osoitteen.

Muoto on aina MP3 320 kbit/s. WAVia tarvitseva lisää ?format=wav, saatavilla studio-option tileille.

Uudelleenluonti

Jos tulos ei vakuuta, uudelleenluonti ei maksa mitään. POST /v1/songs/{id}/regenerate luo uuden version saman tunnisteen alle ja palauttaa tilan arvoon queued. Edellinen versio säilyy kentässä previous_versions.

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

Arvolla keep_lyrics: true sanoitus säilyy ja vain äänite tehdään uudelleen. Se on oikea tie, kun teksti istuu ja vain ääni tai tempo meni pieleen. Arvolla false myös sanoitus kirjoitetaan uusiksi.

Kenttä note menee suoraan uudelleenluontiin, joten konkreettinen lause kannattaa. "Matalampi miesääni, hitaammin" toimii, "tee paremmin" ei. Luomme uudelleen kunnes tulos istuu, enintään kuusi kertaa laulua kohti maksutta. Sen ylittävästä kirjoita meille.

Maksu ja avaus

Laulun avaamiseen on kaksi tapaa, riippuen siitä kuka maksaa.

Loppuasiakas maksaa

POST /v1/songs/{id}/checkout luo meille maksusivun verkkotunnuksen valuutassa ja maassa tavanomaisilla maksutavoilla. Ohjaat asiakkaan sinne ja saat tapahtuman song.paid, kun maksu menee läpi.

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

Sinä maksat

Koontilaskutteisilla tileillä POST /v1/songs/{id}/unlock avaa laulun heti ja veloittaa tililtä summan 24,99 €. Ilman kiertotietä maksusivun kautta, kätevää kun oma kassa on olemassa.

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

Molemmissa tapauksissa pätee sama käyttöoikeus: ei-yksinomainen mutta nimenomaisesti kaupallinen. Valmiin laulun saa antaa eteenpäin, myydä ja julkaista osana omaa tarjontaa.

Sallitut arvot

Tilaisuuksien, tunnelmien, tyylien, äänien ja kielten listat muuttuvat silloin tällöin. Sen sijaan että kirjoittaisit ne kiinteästi koodiin, kysy GET /v1/options ja pidä vastaus välimuistissa muutaman tunnin.

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

Jokaisen näistä arvoista voi myös jättää pois. Arvo surprise_me ei ole täyte vaan oikea ohje: silloin valitsemme tietoisesti jotain, mikä sopii tilaisuuteen ja yksityiskohtiin.

Webhookit

Anna luonnissa callback_url, niin lähetämme sinne jokaisen tapahtuman POST-kutsuna. Se on suositeltu tie, koska se säästää kyselyn ja odottelun.

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

Allekirjoituksen tarkistus

Jokainen toimitus kuljettaa otsakkeen, jossa on aikaleima ja HMAC-SHA256 aikaleimasta, pisteestä ja raakarungosta. Tarkista se ennen kuin luotat sisältöön, ja hylkää kaikki yli viisi minuuttia vanha.

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

Uusinnat

Odotamme 2xx-vastausta kymmenessä sekunnissa. Jos sitä ei tule, yritämme kahdeksan kertaa 24 tunnin aikana kasvavin välein. Toimitukset voivat siis toistua ja harvoin saapua eri järjestyksessä: tee päätepisteestäsi idempotentti ja luota kenttään created_at, älä saapumisaikaan.

Idempotenssi

Jokainen POST ottaa vastaan otsakkeen Idempotency-Key millä tahansa yksilöivällä arvolla, tavallisesti UUID. Jos sama avain palaa 24 tunnin sisällä, palautamme alkuperäisen vastauksen sen sijaan että loisimme toisen laulun.

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

Juuri tätä suojaa verkkovirheissä tarvitaan: jos vastaus katoaa ja koodisi toistaa pyynnön, lauluja syntyy silti yksi. Jos lähetät saman avaimen eri rungolla, vastaamme 409 ja virhetyypillä conflict.

Virheet

Virheet tulevat aina samassa muodossa, koneluettavilla kentillä type ja code, luettavalla viestillä ja tarvittaessa kenttäviittauksella. Liitä request_id jokaiseen yhteydenottoon, niin löydämme kutsun lokeista.

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

Koodeilla 429 ja 5xx uusinta kannattaa, mieluiten eksponentiaalisesti kasvavin välein ja ripauksella satunnaisuutta. Muilla 4xx-koodeilla kuin 429 ei kannata: sama pyyntö kaatuu uudelleen.

Rajat

Jokainen vastaus kuljettaa ajantasaisen tilanteen otsakkeissa, joten arvailla ei tarvitse.

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

Korkeammat rajat eivät ole ongelma, ne eivät vain ole lähtöasetus. Kun määrä kasvaa, kirjoita kaksi lausetta, niin nostamme niitä.

Versiointi

Pääversio on polussa ja pysyy vakaana. Version v1 sisällä tulee vain lisääviä muutoksia: uusia kenttiä, uusia arvoja listoihin, uusia päätepisteitä. Olemassa olevat kentät eivät katoa eivätkä vaihda merkitystä.

Lisävarmuudeksi voit kiinnittää päivämäärän otsakkeeseen. Ilman otsaketta voimassa on aina uusin käyttäytyminen.

X-Song-Version: 2026-09-01

Koodisi pitää ohittaa vastausten tuntemattomat kentät, ei kaatua niihin. Se on ainoa oletus, jonka teemme asiakkaista.

Testitila

Avaimet etuliitteellä sk_test_ kulkevat täsmälleen samojen päätepisteiden läpi mutta eivät käynnistä oikeaa tuotantoa eivätkä maksa mitään. Muutamassa sekunnissa saat kiinteän esittelysanoituksen ja esittelyäänitteen, ja jokainen objekti kuljettaa livemode: false.

Näin myös ikävät tapaukset voi harjoitella. Tietyt nimet kentässä recipient_name pakottavat tietyn lopputuloksen: test_fail johtaa tilaan failed, test_slow noin kymmenen minuutin tuotantoon, test_ratelimit vastaukseen 429. Virheenkäsittelyn voi siis testata odottamatta oikeaa häiriötä.

Webhookit toimivat myös testitilassa, samalla allekirjoitusmekanismilla ja omalla salaisuudellaan.

Oikeudet ja tiedot

Avauksen myötä saat ei-yksinomaisen mutta nimenomaisesti kaupallisen käyttöoikeuden valmiiseen lauluun. Saat antaa sen eteenpäin, myydä sen, esittää sen julkisesti ja upottaa sen omaan tuotteeseesi. Ei-yksinomainen tarkoittaa, että pidätämme oikeuden käyttää äänitettä myös itse, esimerkiksi esimerkkinä.

Tekoälyn tekemän musiikin tekijänoikeuksiin monilla oikeusjärjestyksillä ei ole vielä lopullista vastausta. Käyttöoikeuden takaamme sopimuksella, mutta emme voi vakuuttaa, että äänitteeseen syntyy erillinen, kolmansia sitova tekijänoikeus. Sitä tarvitsevan kannattaa selvittää asia etukäteen.

Syötteet ja valmiit laulut säilyvät 90 päivää, sitten ne poistetaan. Yksittäisen laulun aiempaan poistoon on DELETE /v1/songs/{id}. Kentän details tietoja käytämme vain tämän yhden laulun tuottamiseen, emme koskaan omien mallien opettamiseen.

Jos välität meille asiakkaidesi tietoja, sinä olet rekisterinpitäjä ja me käsittelijä. Käsittelysopimus on saatavilla pyynnöstä.

Tuki

Kysymykset, korkeammat rajat, käsittelysopimus, erikoistapaukset: songs@maxkuch.com. Teknisissä ongelmissa liitä mukaan request_id virhevastauksesta, niin löydämme kutsun heti.

Tekoälyagenttien integraatiolle on lisäksi Model Context Protocol -palvelin, kuvattuna osoitteessa /mcp/, samoilla avaimilla kuin REST-rajapinta.