개발자용 AI 음악 API: REST, MCP, CLI로 만드는 보컬 곡

eroq의 음악 API는 한 문장이나 직접 쓴 가사로 보컬과 악기가 들어간 완성곡이나 연주곡을 만들어요. 음악 스튜디오와 같은 엔진인 Music One이 돌아가고, 크레딧과 키도 eroq API의 다른 기능과 같아요. 이 가이드에서는 요청, 비동기 작업, 웹훅, 과금, 그리고 에이전트용 MCP 도구를 다뤄요. 레퍼런스는 /docs/music에 있어요.

곡을 설명하는 두 가지 방법

• Simple: 곡을 한 문장으로 설명한 prompt를 보내세요. 작사 기능이 스타일, 가사, 제목을 써 주고, 그 비용은 가격에 포함돼 있어요.
• Custom: 직접 쓴 style(언어, 보컬, 장르, 템포, 악기)과 lyrics를 보내세요. 가사에는 섹션 태그를 한 줄씩 따로 넣어요. [Intro], [Verse], [Pre-Chorus], [Chorus], [Bridge], [Outro]. lyrics 없이 style만 보내면 그 스타일에 맞춰 가사를 써 줘요.

보컬을 빼려면 instrumental: true를 추가하세요(이때 가사는 무시돼요). prompt, style, lyrics 중 하나는 꼭 있어야 해요.

곡 시작하기

curl https://eroq.ai/v1/music/generations \
  -H "Authorization: Bearer $EROQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "eroq-music-one",
    "prompt": "a melancholy synth-pop song about leaving a small town at night, warm female vocal",
    "seconds": 120,
    "n": 2
  }'

중요한 파라미터는 이래요.

• seconds: 길이. 30에서 240까지 30 단위예요. 이 단위에 맞춰 조정되고, 요청한 길이로 과금돼요.
• n: 테이크 수. 1 또는 2(기본값 2)예요. 테이크마다 작업, 시드, 과금이 따로예요.
• seed: 재현 가능한 테이크. N번째 테이크는 seed + N - 1로 렌더돼요.
• title: 최대 80자. 생략하면 작사 기능이 제목을 붙여요.
• folder_id: 테이크가 저장될 라이브러리 폴더.

곡 하나에 GPU가 몇 분씩 돌아가기 때문에, 호출하면 요금을 차감하고 테이크마다 작업을 하나씩 시작한 뒤 202로 응답해요.

{
  "id": "4d2a91c0-…",
  "object": "music.generation",
  "status": "processing",
  "model": "eroq-music-one",
  "seconds": 120,
  "title": "Leaving Light",
  "style": "english, female vocals, synth-pop, 104 bpm, warm analog synths",
  "lyrics": "[Verse]\nStreetlights fade behind the bus\n…",
  "instrumental": false,
  "jobs": [
    { "id": "4d2a91c0-…", "poll": "/v1/music/generations/4d2a91c0-…", "take": 1, "seed": 182736 },
    { "id": "9b07e3f1-…", "poll": "/v1/music/generations/9b07e3f1-…", "take": 2, "seed": 182737 }
  ],
  "usage": { "credits_spent": 24, "credits_remaining": 852 }
}

응답에는 곡을 렌더하는 데 쓰는 title, style, lyrics가 그대로 담겨 있어서, Simple 모드에서도 작사 기능이 무엇을 썼는지 볼 수 있어요.

테이크마다 폴링하기

GET /v1/music/generations/{id} 폴링은 무료예요. status가 succeeded나 failed가 될 때까지 몇 초마다 폴링하세요.

const BASE = 'https://eroq.ai/v1'
const headers = { Authorization: `Bearer ${process.env.EROQ_API_KEY}` }

async function waitForTake(id, { every = 5000, deadline = 15 * 60_000 } = {}) {
  const started = Date.now()
  while (Date.now() - started < deadline) {
    const take = await fetch(`${BASE}/music/generations/${id}`, { headers }).then(r => r.json())
    if (take.status === 'succeeded') return take.data[0]   // { url, content_type, seconds, library_id }
    if (take.status === 'failed') throw new Error(take.error?.message ?? 'take failed')
    await new Promise(resolve => setTimeout(resolve, every))
  }
  throw new Error('still rendering — poll again later')
}

완성된 테이크에는 MP3 URL(audio/mpeg), seconds에 담긴 실제 길이(곡이 요청한 길이보다 조금 일찍 끝날 수 있어요), 그리고 library_id가 들어 있어요. 모든 테이크는 레시피와 함께 라이브러리에도 저장돼요. 작업 ID는 생성 후 24시간이 지나면 만료되니, MP3를 직접 서비스한다면 그 전에 다운로드하거나 저장해 두세요.

아니면 서명된 웹훅으로 받기

개발자 대시보드에서 엔드포인트를 등록하고 music.generation.succeeded와 music.generation.failed를 구독하세요. 전송은 매번 eroq-signature 헤더(t=<timestamp>,v1=<HMAC-SHA256 of "t.body">)로 서명된 JSON POST로 와요. 동영상 이벤트와 같은 방식이고, 비동기 작업과 서명된 웹훅에서 설명했어요. 페이로드에는 작업 ID와 result_url이 담기고, 오디오 자체는 절대 담기지 않아요.

2xx로 빠르게 응답하고 실제 처리는 그 뒤에 하세요. 알림을 받지 못한 건 폴링으로 보완하세요.

과금

• 요청한 길이를 기준으로, 테이크마다 곡의 시작된 30초당 3 크레딧이에요. 1분이면 6 크레딧, 3분이면 18 크레딧, 4분이면 24 크레딧이에요.
• n: 2면 두 배예요. 고를 필요가 없다면 n: 1을 쓰세요.
• 실패하거나 엔진의 처리 시간 안에 끝나지 않은 테이크는 그 테이크만 환불되고, 다른 테이크는 그대로 전달돼요.
• 같은 크레딧으로 이미지, 동영상, 음성, 채팅 비용도 내요. $10 팩은 1,000 크레딧이고, 플랜은 필요 없어요.

콘텐츠 정책

정책은 내가 보내는 모든 것과 작사 기능이 쓰는 가사에 똑같이 적용돼요. 그 안에서 가사는 무검열이라 욕설과 어두운 주제도 괜찮아요. 거절되는 건 미성년자가 관련된 모든 것, 동의 없는 식별 가능한 실존 인물, 불법 콘텐츠, 성폭력이에요. 작사 기능은 실제 아티스트 이름을 절대 쓰지 않아요. 거절된 요청은 400 content_blocked로 응답하고 아무것도 과금하지 않으며, 작사 기능이 쓴 가사가 문제였다면 환불돼요.

배포 환경에서 엔진이 아직 열려 있지 않으면, 호출은 크레딧을 차감하기 전에 503 model_unavailable로 응답해요. 그 상태는 GET /v1/engines에 나와요.

AI 에이전트용: MCP

eroq MCP 서버는 ChatGPT, Claude, Claude Code, Cursor, Codex에 generate_music 도구를 제공해요. 이 도구는 prompt(한 문장)나 style + lyrics에 title, instrumental, seconds를 받아 잠깐 기다린 뒤, 곡을 돌려주거나 get_music_status 도구로 확인할 작업 ID를 돌려줘요. MCP 페이지에서 연결하세요. 어시스턴트에게 "내 팟캐스트에 쓸 30초짜리 로파이 인트로 만들어 줘"라고 하면 도구를 호출해요.

터미널에서: CLI

eroq music "a melancholy synth-pop song about leaving a small town" -s 120
eroq music --style "English, warm male vocal, folk" --lyrics "[Verse]…" -n 1 -o song.mp3
eroq music "a calm lo-fi beat for studying" --instrumental -s 60

CLI는 MP3가 준비될 때까지 폴링한 뒤 파일로 저장해요. eroq mcp 명령은 곡을 작업 디렉터리에 파일로 저장하는 로컬 MCP 서버를 띄우는데, 코딩 에이전트에 잘 맞아요.

자주 묻는 질문

보컬이 들어간 AI 음악 생성 API가 있나요?

네. POST /v1/music/generations는 한 문장이나 직접 쓴 스타일과 가사로 보컬 곡이나 연주곡을 만들어요. 비동기식이라 테이크마다 작업이 하나씩 생기고, 무료로 폴링하거나 웹훅으로 받으면 돼요.

음악 API는 얼마인가요?

스튜디오와 똑같이 테이크마다 시작된 30초당 3 크레딧이에요. 2분짜리 곡은 테이크당 12 크레딧이에요.

생성한 곡은 얼마나 길게 만들 수 있나요?

30초에서 240초까지, 30초 단위예요.

곡은 어떤 웹훅 이벤트를 보내나요?

music.generation.succeeded와 music.generation.failed 두 가지이고, eroq-signature 헤더로 서명돼요.

API로 직접 쓴 가사를 보낼 수 있나요?

네. style과 lyrics를 보내세요. [Verse], [Chorus] 같은 섹션 태그는 한 줄씩 따로 쓰고, 가사는 3,000자까지 돼요.

AI 어시스턴트가 eroq로 곡을 만들 수 있나요?

네, MCP 도구 generate_music으로 만들어요. eroq를 연결하면 ChatGPT, Claude, Claude Code, Cursor, Codex에서 쓸 수 있어요.