개발자

API 문서

MeloLab API로 개발하는 데 필요한 모든 것: 인증, 크레딧, 생성, 작업, webhook, 라이브러리 검색.

시작하기

모든 요청은 Authorization: Bearer 헤더로 API 키를 사용해 인증합니다. 기본 URL은 https://melolab.ai입니다. 읽기 엔드포인트는 크레딧을 사용하지 않습니다. 생성 요청은 기존 MeloLab 크레딧을 사용하며 비용과 환불 규칙은 웹 앱과 동일합니다. 생성 시 Idempotency-Key 헤더를 보내면 재시도가 안전합니다. 성공 응답은 data 객체로 감싸지고, 오류는 code, message, request_id를 반환합니다.

계정

API 프로필, 크레딧 잔액, 최근 사용량을 확인합니다.

GET/api/v1/meprofile:read

계정 등급과 API 사용 가능 여부를 포함해 인증된 API 프로필을 반환합니다.

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

GET/api/v1/creditscredits:read

기존 MeloLab 크레딧 잔액을 반환합니다. 크레딧을 사용하지 않습니다.

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

GET/api/v1/usageprofile:read

사용량 요약과 최근의 마스킹된 요청 이벤트를 반환합니다.

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

모델

사용 가능한 MeloLab 모델과 크레딧 비용을 나열합니다.

GET/api/v1/modelsmodels:read

사용 가능한 MeloLab 모델과 크레딧 비용을 나열합니다.

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

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

id로 단일 모델을 반환합니다.

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

생성

음악 생성을 만들고, 최근 생성을 나열하며, 작업이 끝날 때까지 폴링합니다.

POST/api/v1/generationsgenerations:create

비동기 음악 생성을 만듭니다. 기존 MeloLab 크레딧을 사용하며 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

최근 생성 작업을 나열합니다.

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

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

생성을 폴링하고 완료되면 트랙을 반환합니다.

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

GET/api/v1/jobs/{job_id}

비동기 작업(음악, 스템 분리, 보컬 제거)을 폴링하고 제공자가 완료하면 출력을 반환합니다.

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

라이브러리

재생 가능한 트랙과 플레이리스트를 검색하고, 개별 트랙 또는 플레이리스트 세부 정보를 확인합니다.

GET/api/v1/library/searchlibrary:read

본인의 비공개 항목을 포함해 재생 가능한 트랙과 플레이리스트를 검색합니다.

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

트랙의 재생 메타데이터를 반환합니다.

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

GET/api/v1/playlistslibrary:read

사용 가능한 플레이리스트를 나열합니다.

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

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

플레이리스트와 그 트랙을 반환합니다.

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

Webhook

비동기 작업이 완료되면 알림을 받을 HTTPS 엔드포인트를 등록하면 폴링할 필요가 없습니다. 전체 서명 시크릿은 엔드포인트 생성 시 한 번만 표시됩니다.

GET/api/v1/webhook-endpoints

활성 webhook 엔드포인트를 나열합니다.

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

POST/api/v1/webhook-endpoints

공개 HTTPS webhook 엔드포인트를 등록합니다. 서명 시크릿은 한 번만 반환됩니다.

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}

webhook 엔드포인트의 URL 또는 상태를 업데이트합니다.

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}

webhook 엔드포인트를 삭제합니다.

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

로그

최근 30일간의 API 요청 로그를 검토합니다.

GET/api/v1/logs

최근 30일간의 API 요청 로그를 나열합니다.

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

속도 제한

읽기 엔드포인트는 분당 600회(일 50,000회)를 허용합니다. 음악 생성은 분당 12회(일 500회)입니다. 인증은 IP당 분당 120회로 제한됩니다. 제한을 초과하면 429 rate_limited를 반환합니다.

오류

오류는 HTTP 상태와 { error: { code, message, request_id } } JSON 본문을 반환합니다. 지원팀에 문의할 때 request_id를 포함하세요.

상태	코드	의미
401	authentication_required	Authorization 헤더에 API 키가 제공되지 않았습니다.
401	invalid_api_key	API 키가 유효하지 않거나 해지되었습니다.
403	insufficient_scope	API 키에 필요한 범위가 없습니다.
400	invalid_request	요청 본문 또는 매개변수가 유효하지 않습니다.
400	invalid_model	요청한 모델 id가 존재하지 않습니다.
402	insufficient_credits	이 생성을 만들기에 MeloLab 크레딧이 부족합니다.
409	idempotency_conflict	Idempotency-Key가 다른 요청 본문과 함께 재사용되었습니다.
404	not_found	요청한 리소스가 없거나 본인의 것이 아닙니다.
429	rate_limited	요청이 너무 많습니다. 잠시 후 다시 시도하세요.
502	provider_unavailable	업스트림 제공자를 일시적으로 사용할 수 없습니다.

API 문서

시작하기

계정

모델

생성

라이브러리

Webhook

로그

속도 제한

오류

무료로 만들기 시작

제작

음악 스타일

무드

악기

배경음악

비교

AI 모델

오디오 효과

AI 모델

회사