Deweloperzy

Dokumentacja API

Wszystko, czego potrzebujesz do budowania z API MeloLab: uwierzytelnianie, kredyty, generowanie, zadania, webhooki i wyszukiwanie w bibliotece.

Pierwsze kroki

Uwierzytelniaj każde żądanie kluczem API za pomocą nagłówka Authorization: Bearer. Bazowy URL to https://melolab.ai. Punkty końcowe odczytu nie zużywają kredytów; utworzenie generacji wykorzystuje istniejące kredyty MeloLab z tymi samymi zasadami kosztów i zwrotów co aplikacja webowa. Wysyłaj nagłówek Idempotency-Key podczas tworzenia generacji, aby ponowne próby były bezpieczne. Udane odpowiedzi są opakowane w obiekt data; błędy zwracają code, message i request_id.

Konto

Odczytaj swój profil API, saldo kredytów i ostatnie użycie.

GET/api/v1/meprofile:read

Zwraca uwierzytelniony profil API, w tym poziom konta i dostępność API.

curl -X GET https://melolab.ai/api/v1/me \
  -H "Authorization: Bearer $MELOLAB_API_KEY"

GET/api/v1/creditscredits:read

Zwraca istniejące saldo kredytów MeloLab. Nie zużywa kredytów.

curl -X GET https://melolab.ai/api/v1/credits \
  -H "Authorization: Bearer $MELOLAB_API_KEY"

GET/api/v1/usageprofile:read

Zwraca podsumowanie użycia oraz ostatnie, zanonimizowane zdarzenia żądań.

curl -X GET https://melolab.ai/api/v1/usage \
  -H "Authorization: Bearer $MELOLAB_API_KEY"

Modele

Wyświetl dostępne modele MeloLab i ich koszt w kredytach.

GET/api/v1/modelsmodels:read

Wyświetla dostępne modele MeloLab wraz z ich kosztem w kredytach.

curl -X GET https://melolab.ai/api/v1/models \
  -H "Authorization: Bearer $MELOLAB_API_KEY"

GET/api/v1/models/{model_id}models:read

Zwraca jeden model według id.

curl -X GET https://melolab.ai/api/v1/models/suno/v5-5 \
  -H "Authorization: Bearer $MELOLAB_API_KEY"

Generacje

Utwórz generację muzyki, wyświetl ostatnie generacje i odpytuj zadanie aż do zakończenia.

POST/api/v1/generationsgenerations:create

Tworzy asynchroniczną generację muzyki. Wykorzystuje istniejące kredyty MeloLab; wymaga nagłówka Idempotency-Key.

curl -X POST https://melolab.ai/api/v1/generations \
  -H "Authorization: Bearer $MELOLAB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model_id":"suno/v5-5","prompt":"warm lofi beat for a focus playlist"}'

GET/api/v1/generationsgenerations:read

Wyświetla ostatnie zadania generowania.

curl -X GET https://melolab.ai/api/v1/generations \
  -H "Authorization: Bearer $MELOLAB_API_KEY"

GET/api/v1/generations/{id}generations:read

Odpytuje generację i zwraca jej utwory po zakończeniu.

curl -X GET https://melolab.ai/api/v1/generations/gen_123 \
  -H "Authorization: Bearer $MELOLAB_API_KEY"

GET/api/v1/jobs/{job_id}

Odpytuje zadanie asynchroniczne (muzyka, rozdzielanie ścieżek lub usuwanie wokalu) i zwraca wyniki po zakończeniu przez dostawcę.

curl -X GET https://melolab.ai/api/v1/jobs/job_123 \
  -H "Authorization: Bearer $MELOLAB_API_KEY"

Biblioteka

Wyszukuj odtwarzalne utwory i playlisty oraz odczytuj szczegóły pojedynczych utworów lub playlist.

GET/api/v1/library/searchlibrary:read

Wyszukuje odtwarzalne utwory i playlisty, w tym Twoje prywatne elementy.

curl -X GET https://melolab.ai/api/v1/library/search?q=lofi \
  -H "Authorization: Bearer $MELOLAB_API_KEY"

GET/api/v1/tracks/{id}library:read

Zwraca odtwarzalne metadane utworu.

curl -X GET https://melolab.ai/api/v1/tracks/track_123 \
  -H "Authorization: Bearer $MELOLAB_API_KEY"

GET/api/v1/playlistslibrary:read

Wyświetla playlisty dostępne dla Ciebie.

curl -X GET https://melolab.ai/api/v1/playlists \
  -H "Authorization: Bearer $MELOLAB_API_KEY"

GET/api/v1/playlists/{id}library:read

Zwraca playlistę i jej utwory.

curl -X GET https://melolab.ai/api/v1/playlists/playlist_123 \
  -H "Authorization: Bearer $MELOLAB_API_KEY"

Webhooki

Rejestruj punkty końcowe HTTPS, aby otrzymywać powiadomienia po zakończeniu zadań asynchronicznych, bez konieczności odpytywania. Pełny sekret podpisujący jest pokazywany tylko raz przy tworzeniu punktu końcowego.

GET/api/v1/webhook-endpoints

Wyświetla Twoje aktywne punkty końcowe webhooków.

curl -X GET https://melolab.ai/api/v1/webhook-endpoints \
  -H "Authorization: Bearer $MELOLAB_API_KEY"

POST/api/v1/webhook-endpoints

Rejestruje publiczny punkt końcowy webhooka HTTPS. Sekret podpisujący jest zwracany tylko raz.

curl -X POST https://melolab.ai/api/v1/webhook-endpoints \
  -H "Authorization: Bearer $MELOLAB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/melolab/webhook"}'

PATCH/api/v1/webhook-endpoints/{id}

Aktualizuje URL lub status punktu końcowego webhooka.

curl -X PATCH https://melolab.ai/api/v1/webhook-endpoints/wh_123 \
  -H "Authorization: Bearer $MELOLAB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status":"disabled"}'

DELETE/api/v1/webhook-endpoints/{id}

Usuwa punkt końcowy webhooka.

curl -X DELETE https://melolab.ai/api/v1/webhook-endpoints/wh_123 \
  -H "Authorization: Bearer $MELOLAB_API_KEY"

Logi

Przejrzyj logi żądań API z ostatnich 30 dni.

GET/api/v1/logs

Wyświetla logi żądań API z ostatnich 30 dni.

curl -X GET https://melolab.ai/api/v1/logs?limit=20 \
  -H "Authorization: Bearer $MELOLAB_API_KEY"

Limity zapytań

Punkty końcowe odczytu pozwalają na 600 żądań na minutę (50 000 dziennie). Generowanie muzyki pozwala na 12 żądań na minutę (500 dziennie). Uwierzytelnianie jest ograniczone do 120 żądań na minutę na IP. Przekroczenie limitu zwraca 429 rate_limited.

Błędy

Błędy zwracają status HTTP oraz treść JSON { error: { code, message, request_id } }. Podaj request_id, kontaktując się z pomocą techniczną.

Status	Kod	Znaczenie
401	authentication_required	W nagłówku Authorization nie podano klucza API.
401	invalid_api_key	Klucz API jest nieprawidłowy lub unieważniony.
401	revoked_api_key	Klucz API został unieważniony i nie można go już używać.
403	api_terms_not_accepted	Konto API nie jest gotowe, ponieważ warunki API nie zostały zaakceptowane.
403	insufficient_scope	Klucz API nie ma wymaganego zakresu.
400	invalid_request	Treść żądania lub parametry są nieprawidłowe.
400	invalid_model	Żądany id modelu nie istnieje.
402	insufficient_credits	Za mało kredytów MeloLab, aby utworzyć tę generację.
400	idempotency_key_required	To żądanie wymaga nagłówka Idempotency-Key.
409	idempotency_key_conflict	Klucz Idempotency-Key został ponownie użyty z inną formą żądania.
409	idempotency_conflict	Klucz Idempotency-Key został ponownie użyty z inną treścią żądania.
409	generation_concurrency_exceeded	Dla tego konta działa już zbyt wiele zadań generowania.
404	job_not_found	Żądane zadanie nie istnieje lub nie należy do tego konta.
404	track_not_found	Żądany utwór nie istnieje lub nie jest dostępny dla tego konta.
404	playlist_not_found	Żądana playlista nie istnieje lub nie jest dostępna dla tego konta.
404	webhook_endpoint_not_found	Żądany punkt końcowy webhooka nie istnieje lub nie należy do Ciebie.
400	webhook_url_invalid	URL webhooka jest nieprawidłowy.
400	webhook_https_required	Punkty końcowe webhooka muszą używać HTTPS.
400	webhook_credentials_forbidden	URL webhooka nie może zawierać osadzonych danych logowania.
400	webhook_host_blocked	URL webhooka nie może wskazywać localhost, hostów prywatnych ani zablokowanych.
429	rate_limited	Zbyt wiele żądań; zwolnij i spróbuj ponownie później.
502	provider_unavailable	Dostawca nadrzędny jest tymczasowo niedostępny.
502	provider_timeout	Dostawca nadrzędny przekroczył limit czasu.
500	generation_failed	Generowanie nie powiodło się po zaakceptowaniu.
500	internal_error	Nieoczekiwany błąd platformy API.

Dokumentacja API

Pierwsze kroki

Konto

Modele

Generacje

Biblioteka

Webhooki

Logi

Limity zapytań

Błędy

Zacznij za darmo

Twórz

Transform

Analyze

Firma