Dokumentacja API

Wprowadzenie

API robi dokładnie to samo co strona. Przesyłasz okazję, imię osoby, o której jest piosenka, i kilka konkretnych szczegółów. Powstaje z tego najpierw gotowy tekst, a potem wyprodukowane nagranie z wokalem, aranżacją i miksem. Całość trwa zwykle od pięciu do dziesięciu minut.

Wszystkie zapytania idą na https://api.mojamelodia.pl/v1. API mówi wyłącznie po HTTPS, przyjmuje JSON i odpowiada JSON-em. Nie ma obowiązkowego SDK: wystarczy dowolny język, który umie HTTP. Przykłady na tej stronie używają curl, Pythona i Node, bo to trzy najczęstsze przypadki.

Każda domena ma własną bazę API i własną cenę w lokalnej walucie. Klucz działa dla domeny, dla której został wydany. Kto obsługuje kilka rynków, dostaje kilka kluczy albo jeden klucz otwarty na kilka domen.

Dostęp

Świadomie nie ma automatycznej rejestracji. Klucze wydajemy ręcznie, bo za każdą piosenką stoją realne koszty produkcji i chcemy wiedzieć, do czego służy integracja. W praktyce to krótka wiadomość i jeden dzień roboczy.

Napisz na songs@maxkuch.com i podaj cztery rzeczy:

• Co chcesz zbudować, w dwóch, trzech zdaniach.
• Przybliżony wolumen miesięcznie.
• W jakich językach mają być śpiewane piosenki.
• Czy możesz odbierać webhooki, czy wolisz odpytywać API.

Dostaniesz dwa klucze: testowy z przedrostkiem sk_test_, bezpłatny, który zwraca stałe nagrania demonstracyjne, oraz produkcyjny z przedrostkiem sk_live_. Oba działają od razu, bez odblokowywania pojedynczych punktów końcowych.

Uwierzytelnianie

Każde zapytanie niesie klucz w nagłówku Authorization jako token bearer. Zapytania bez poprawnego nagłówka dostają 401 i typ błędu authentication_error.

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

Traktuj klucz jak hasło: tylko po stronie serwera, nigdy w kodzie frontendu, nigdy w publicznym repozytorium. Jeśli klucz wycieknie, napisz do nas: blokujemy go natychmiast i wydajemy nowy. Konto może mieć kilka aktywnych kluczy, więc wymiana odbywa się bez przerwy w działaniu.

Klucze testowe i produkcyjne korzystają z tych samych punktów końcowych. To, czy zapytanie poszło w trybie testowym, pokazuje pole livemode w każdym obiekcie.

Szybki start

Utworzenie piosenki to jedno wywołanie. Odpowiedź przychodzi od razu i zawiera identyfikator ze statusem queued. Cała reszta dzieje się w tle.

import os, time, requests

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

Dla prostoty przykład odpytuje co pięć sekund. Na produkcji lepszą drogą są webhooki, bo oszczędzają i otwarte połączenie, i czekanie. Obie drogi są obsługiwane, webhooki opisujemy niżej.

Decydujące pole to details. Tam trafiają konkrety o osobie: przezwisko, dziwactwo, wakacje, które poszły nie tak. Ogólne zdania w rodzaju "to ciepła osoba" dają ogólne wersy. Wystarczą trzy do pięciu konkretnych szczegółów i to one decydują, czy piosenka jest po prostu miła, czy naprawdę o kimś.

Punkty końcowe w skrócie

Tworzenie piosenki

POST /v1/songs przyjmuje brief i startuje od razu. Obowiązkowe są tylko trzy pola, pozostałe mają rozsądne wartości domyślne albo są dobierane do okazji.

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

Obiekt piosenki

Każdy punkt końcowy zwracający pojedynczą piosenkę zwraca ten sam obiekt. Pola, których jeszcze nie ma, mają wartość null i wypełniają się w trakcie produkcji.

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

Wartości statusu

Piosenka przechodzi przez stany w tej kolejności. Nigdy się nie cofa, a complete, failed i cancelled to stany końcowe.

Pojedyncza nieudana próba produkcji nie prowadzi od razu do failed. Wewnętrznie ponawiamy kilka razy i poddajemy się dopiero, gdy zawiodą wszystkie próby. Dlatego failed zdarza się rzadko i naprawdę znaczy: ta piosenka nie przyjdzie.

Pobieranie i listowanie

GET /v1/songs/{id} zwraca aktualny stan piosenki. Punkt końcowy jest lekki i znosi odpytywanie co sekundę, o ile mieścisz się w limicie częstotliwości.

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

Listy działają na kursorze. Dostajesz najwyżej limit pozycji, domyślnie 20 i maksymalnie 100, od najnowszych. Jeśli has_more jest prawdą, przekazujesz next_cursor jako starting_after w kolejnym wywołaniu. Filtrować możesz po status, occasion, language, paid oraz created_after i 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 i dźwięk

Tekst jest bezpłatny i kompletny, to nie fragment. GET /v1/songs/{id}/lyrics zwraca go jako text/plain, ze znacznikami zwrotek i refrenu. Ten sam tekst stoi w polu lyrics obiektu piosenki.

Przy dźwięku są dwa poziomy. Zapowiedź to pierwsze 45 sekund gotowego nagrania, a nie osobne demo: ten sam głos, ta sama aranżacja, ten sam tekst. Jest dostępna bez płatności i taka pozostaje. Cały plik wydaje GET /v1/songs/{id}/audio dopiero po odblokowaniu.

Oba adresy są podpisane i ważne 24 godziny. Służą do pobrania, nie do trwałego linkowania. Jeśli potrzebujesz pliku dłużej, pobierz go raz i przechowaj u siebie. Ponowne wywołanie punktu końcowego daje w każdej chwili świeży adres.

Format to zawsze MP3 320 kbit/s. Kto potrzebuje WAV, dodaje ?format=wav, dostępne dla kont z opcją studyjną.

Ponowne generowanie

Jeśli wynik nie przekonuje, ponowne generowanie nic nie kosztuje. POST /v1/songs/{id}/regenerate tworzy nową wersję pod tym samym identyfikatorem i ustawia status z powrotem na queued. Poprzednia wersja zostaje pod previous_versions.

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

Przy keep_lyrics: true tekst zostaje i powstaje tylko nowe nagranie. To właściwa droga, gdy tekst siedzi, a zawiódł tylko głos albo tempo. Przy false przepisujemy również tekst.

Pole note trafia wprost do ponownego generowania, więc konkretne zdanie się opłaca. "Niższy męski głos, wolniej" działa, "zrób lepiej" nie. Trzy ponowne generowania na piosenkę są bezpłatne, powyżej tego napisz do nas.

Płatność i odblokowanie

Są dwa sposoby odblokowania piosenki, zależnie od tego, kto płaci.

Płaci klient końcowy

POST /v1/songs/{id}/checkout tworzy u nas stronę płatności w walucie domeny, z metodami płatności typowymi dla danego kraju. Wysyłasz tam klienta i dostajesz zdarzenie song.paid, gdy płatność dojdzie do skutku.

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

Płacisz ty

Na kontach z fakturą zbiorczą POST /v1/songs/{id}/unlock odblokowuje piosenkę od razu i obciąża konto kwotą 59 zł. Bez objazdu przez stronę płatności, wygodne, gdy masz własną kasę.

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

W obu przypadkach obowiązuje to samo prawo do korzystania: niewyłączne, ale wyraźnie komercyjne. Gotową piosenkę możesz przekazywać dalej, sprzedawać i publikować w ramach swojej oferty.

Dopuszczalne wartości

Listy okazji, nastrojów, stylów, głosów i języków zmieniają się od czasu do czasu. Zamiast wpisywać je na sztywno, odpytaj GET /v1/options i trzymaj odpowiedź w pamięci podręcznej przez kilka godzin.

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

Każdą z tych wartości można też pominąć. Wartość surprise_me nie jest wypełniaczem, tylko prawdziwą instrukcją: wtedy świadomie dobieramy coś, co pasuje do okazji i szczegółów.

Webhooki

Podaj przy tworzeniu callback_url, a wyślemy tam każde zdarzenie metodą POST. To zalecana droga, bo oszczędza odpytywanie i czekanie.

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

Sprawdzanie podpisu

Każda dostawa niesie nagłówek ze znacznikiem czasu i HMAC-SHA256 po znaczniku czasu, kropce i surowym ciele. Sprawdź go, zanim zaufasz treści, i odrzuć wszystko starsze niż pięć minut.

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

Powtórzenia

Oczekujemy odpowiedzi 2xx w ciągu dziesięciu sekund. Jeśli jej nie ma, ponawiamy osiem razy w ciągu 24 godzin z rosnącymi odstępami. Dostawy mogą się więc powtarzać, a rzadko przyjść nie po kolei: zrób swój punkt końcowy idempotentnym i ufaj polu created_at, a nie godzinie nadejścia.

Idempotencja

Każdy POST przyjmuje nagłówek Idempotency-Key z dowolną unikalną wartością, zwykle UUID. Jeśli ten sam klucz wróci w ciągu 24 godzin, zwracamy pierwotną odpowiedź zamiast tworzyć drugą piosenkę.

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

To dokładnie ta ochrona, której trzeba przy błędach sieci: jeśli odpowiedź zginie, a twój kod powtórzy zapytanie, i tak powstanie jedna piosenka. Jeśli wyślesz ten sam klucz z innym ciałem, odpowiemy 409 z typem błędu conflict.

Błędy

Błędy przychodzą zawsze w tej samej formie, z czytelnymi maszynowo type i code, czytelnym komunikatem oraz, gdy to istotne, wskazaniem pola. Dołącz request_id do każdego zgłoszenia, wtedy znajdziemy wywołanie w logach.

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

Przy 429 i 5xx ponawianie ma sens, najlepiej z wykładniczo rosnącymi odstępami i odrobiną losowości. Przy 4xx innym niż 429 nie ma: to samo zapytanie znowu zawiedzie.

Limity

Każda odpowiedź niesie aktualny stan w nagłówkach, więc nie musisz zgadywać.

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

Wyższe limity nie są problemem, po prostu nie są ustawieniem startowym. Gdy wolumen rośnie, napisz dwa zdania, a je podniesiemy.

Wersjonowanie

Wersja główna stoi w ścieżce i pozostaje stabilna. Wewnątrz v1 pojawiają się tylko zmiany dodające: nowe pola, nowe wartości w listach, nowe punkty końcowe. Istniejące pola nie znikają i nie zmieniają znaczenia.

Dla większej pewności możesz przypiąć datę w nagłówku. Bez nagłówka obowiązuje zawsze najnowsze zachowanie.

X-Song-Version: 2026-09-01

Twój kod powinien ignorować nieznane pola w odpowiedziach, a nie się na nich wykładać. To jedyne założenie, jakie robimy wobec klientów.

Tryb testowy

Klucze z przedrostkiem sk_test_ przechodzą przez dokładnie te same punkty końcowe, ale nie uruchamiają prawdziwej produkcji i nic nie kosztują. Po kilku sekundach dostajesz stały tekst demonstracyjny i nagranie demonstracyjne, a każdy obiekt niesie livemode: false.

Dzięki temu da się przećwiczyć również przypadki nieprzyjemne. Pewne imiona w polu recipient_name wymuszają określony wynik: test_fail prowadzi do failed, test_slow do produkcji trwającej około dziesięciu minut, test_ratelimit do odpowiedzi 429. Obsługę błędów możesz więc przetestować, nie czekając na prawdziwą awarię.

Webhooki działają także w trybie testowym, z tym samym mechanizmem podpisu i własnym sekretem.

Prawa i dane

Wraz z odblokowaniem dostajesz niewyłączne, ale wyraźnie komercyjne prawo do korzystania z gotowej piosenki. Możesz ją przekazywać, sprzedawać, wykonywać publicznie i wbudować w swój produkt. Niewyłączne znaczy, że zachowujemy prawo do korzystania z nagrania również sami, na przykład jako z przykładu.

Co do praw autorskich do muzyki tworzonej przez sztuczną inteligencję wiele porządków prawnych nie ma jeszcze ostatecznej odpowiedzi. Prawo do korzystania gwarantujemy umownie, ale nie możemy zapewnić, że do nagrania powstaje odrębne prawo autorskie skuteczne wobec osób trzecich. Kto jest od tego zależny, powinien sprawdzić to wcześniej.

Dane wejściowe i gotowe piosenki trzymamy 90 dni, potem są usuwane. Do wcześniejszego usunięcia pojedynczej piosenki służy DELETE /v1/songs/{id}. Informacji z details używamy wyłącznie do wyprodukowania tej jednej piosenki i nigdy do trenowania własnych modeli.

Jeśli przekazujesz nam dane swoich klientów, to ty jesteś administratorem, a my podmiotem przetwarzającym. Umowa powierzenia jest dostępna na życzenie.

Wsparcie

Pytania, wyższe limity, umowa powierzenia, przypadki szczególne: songs@maxkuch.com. Przy problemach technicznych podaj request_id z odpowiedzi błędu, wtedy znajdziemy wywołanie od razu.

Dla integracji przez agentów sztucznej inteligencji jest dodatkowo serwer Model Context Protocol, opisany na /mcp/, korzystający z tych samych kluczy co REST API.