開発者向けAI音楽API：REST、MCP、CLIでボーカル入りの曲を

eroqの音楽APIは、ボーカルと楽器の入ったフル楽曲、またはインストを、一文から、あるいは自分の歌詞から作ります。エンジンは音楽スタジオと同じMusic Oneで、eroq APIのほかの機能と同じクレジット、同じキーで使えます。このガイドでは、リクエスト、非同期ジョブ、Webhook、課金、そしてエージェント向けのMCPツールを解説します。リファレンスは/docs/musicにあります。

曲の伝え方は2通り

• 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で数分かかるため、この呼び出しは課金を行い、テイクごとにジョブを1つ開始して、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をダウンロードするか保存しておきましょう。

または署名付きWebhookで受け取る

開発者ダッシュボードでエンドポイントを登録し、music.generation.succeededとmusic.generation.failedを購読させます。配信はそれぞれ、eroq-signatureヘッダー（t=<timestamp>,v1=<HMAC-SHA256 of "t.body">）で署名されたJSONのPOSTです。方式は動画のイベントと同じで、非同期ジョブと署名付きWebhookで解説しています。ペイロードに入っているのはジョブIDとresult_urlで、音声そのものが入ることはありません。

すぐに2xxを返し、処理はそのあとで行いましょう。通知を受け取れなかったものに備えて、ポーリングをフォールバックとして残しておきます。

課金

• リクエストした長さに対して、テイクごとに、曲の30秒（端数切り上げ）につき3クレジット。1分なら6クレジット、3分なら18、4分なら24です。
• n: 2なら2倍です。選ぶ必要がないときはn: 1を使いましょう。
• 失敗したテイクや、エンジンの制限時間内に終わらなかったテイクは、そのテイクだけ返金されます。もう一方のテイクはそのまま届きます。
• 同じクレジットで、画像、動画、音声合成、チャットも使えます。$10のパックは1,000クレジットで、プランは必要ありません。

コンテンツポリシー

ポリシーは、あなたが送るものすべてと、作詞機能が書くものに適用されます。その範囲内で、歌詞は検閲なしです。汚い言葉もダークなテーマも問題ありません。拒否されるのは、未成年者が関わるもの、本人の同意のない特定可能な実在の人物、違法なコンテンツ、性暴力です。作詞機能が実在のアーティストの名前を出すこともありません。拒否されたリクエストは400 content_blockedを返して課金されず、書かれた歌詞のほうが問題だった場合は返金されます。

デプロイ先でエンジンが稼働していない場合、呼び出しは引き落としの前に503 model_unavailableを返します。その状態はGET /v1/enginesで確認できます。

AIエージェント向け：MCP

eroqのMCPサーバーは、generate_musicをChatGPT、Claude、Claude Code、Cursor、Codexに提供しています。このツールは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が、一文から、または自分で書いたスタイルと歌詞から、ボーカル入りの曲やインストを作ります。非同期型で、テイクごとに1つのジョブが作られ、無料でポーリングするか、Webhookで受け取ります。

音楽APIの料金はいくらですか？

スタジオと同じく、テイクごとに30秒（端数切り上げ）につき3クレジットです。2分の曲なら、1テイク12クレジットです。

生成できる曲の長さは？

30〜240秒で、30秒刻みです。

曲ではどのWebhookイベントが送られますか？

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で使えます。