venice-audio-music

Venice Music / 非同期オーディオ

音楽、効果音、キャラクター単価の音声生成は非同期です。

メソッド	パス	認証	備考
POST	/api/v1/audio/quote	不要（キーは任意）	価格は USD です。
POST	/api/v1/audio/queue	Bearer キーまたは x402（SIWX）	課金してキューに追加します → queue_id。ユーザーあたり毎分 40 リクエストです。
POST	/api/v1/audio/retrieve	Bearer キーまたは x402（SIWX）	ステータス JSON またはオーディオバイト列を返します。ユーザーあたり毎分 120 リクエストです。
POST	/api/v1/audio/complete	Bearer キーまたは x402（SIWX）	保存されたメディアを削除します。

短い同期テキスト読み上げには venice-audio-speech を使用してください。ボイスチェンジャー（音声から音声への変換）モデルは、これら 4 つのエンドポイントでは 400 で拒否され、/audio/voice-changer/* が示されます（モデルを参照できない呼び出し元には、代わりに 404 が返されます）。詳しくは venice-audio-voice-changer をご覧ください。

使用する場面

• 曲、ジングル、楽譜、サウンドスケープ、効果音、または長いナレーションが必要な場合。
• モデルの料金が、時間、秒数、ジョブごと、または文字数に基づいており、送信前に価格を確認したい場合。
• 生成に時間がかかり、同期呼び出しではタイムアウトする場合。

モデル

GET /models?type=music を呼び出すと、現在の一覧と各モデルの model_spec を確認できます。代表的な ID（すべて現行リストに含まれます）：

種類	例
インストゥルメンタル／曲	elevenlabs-music、elevenlabs-music-v2-5、lyria-3-pro、sonilo-v1-1-music、stable-audio-25
歌詞付きの曲	minimax-music-v25、minimax-music-v26、minimax-music-v2（歌詞必須）、ace-step-15（歌詞は任意）
効果音	elevenlabs-sound-effects-v2（loop に対応）、sonilo-v1-1-sound-effects、mmaudio-v2-text-to-audio
音声（prompt にテキストを指定）	elevenlabs-tts-v4、elevenlabs-tts-v4-turbo、elevenlabs-tts-v3、elevenlabs-tts-multilingual-v2、seed-audio-1-0

ライフサイクル

1. POST /audio/quote — まず価格を確認

curl https://api.venice.ai/api/v1/audio/quote \
  -H "Content-Type: application/json" \
  -d '{ "model": "elevenlabs-music", "duration_seconds": 60 }'

応答：{"quote": 0.69}（USD）。API キーは不要です。キーを送信すると、アカウントから参照できるモデルだけを価格確認できます。

フィールド	備考
model	必須です。
duration_seconds	整数または数値文字列です。時間のメタデータ（min_duration／max_duration／duration_options）を公開しているモデルに限り指定できます。それ以外では拒否されます。省略すると、モデルの default_duration の価格が確認されます。
character_count	prompt_character_limit 以下の整数です。per_thousand_characters で料金が設定されているモデルでは必須です。

不明なフィールドを指定すると 400 が返されます。

2. POST /audio/queue — キューに追加

curl https://api.venice.ai/api/v1/audio/queue \
  -H "Authorization: Bearer $VENICE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "elevenlabs-music",
    "prompt": "Uplifting indie-folk acoustic track, 120 BPM, major key.",
    "duration_seconds": 60,
    "force_instrumental": true
  }'

歌詞付きの曲（minimax-music-v25 は歌詞、オプティマイザー、インストゥルメンタルモードをサポートしていますが、duration_seconds はサポートしていません）：

{
  "model": "minimax-music-v25",
  "prompt": "Warm indie-pop ballad, female vocals, acoustic guitar.",
  "lyrics_prompt": "[Verse]\nWalking through the city lights...\n[Chorus]\nWe are the dreamers..."
}

レスポンス：{ "model": "...", "queue_id": "...", "status": "QUEUED" }。

リクエスト本文は厳密に検証されます。以下の任意フィールドは、モデルの model_spec でサポート対象外とされている場合、すべて 400 で拒否されます。

フィールド	備考
model	必須です。
prompt	必須です。min_prompt_length（デフォルトは 10）以上、prompt_character_limit 以下である必要があります。前後の空白は削除されます。音声モデルでは、読み上げるテキストを指定します。
lyrics_prompt	lyrics_character_limit（デフォルトは 4096）以下である必要があります。lyrics_required=true の場合は必須です。supports_lyrics=false の場合は拒否されます。
duration_seconds	整数または数値文字列を指定します。指定する場合は duration_options のいずれか、または min_duration～max_duration の範囲内である必要があります。デフォルトは default_duration です。
force_instrumental	supports_force_instrumental=true のモデルのみ対応します。
lyrics_optimizer	prompt から歌詞を自動作成します。supports_lyrics_optimizer=true のモデルのみ対応し、この場合 lyrics_prompt は空である必要があります。
loop	シームレスなループをレンダリングします（末尾を先頭につなぎます）。supports_loop=true のモデルのみ対応します。現在は elevenlabs-sound-effects-v2 のみです。
voice	音声対応モデルのみ使用できます。voices のいずれかを指定します。デフォルトは default_voice です。supports_custom_voice_id=true のモデル（ElevenLabs の TTS モデル）では、ElevenLabs の Voice ID をそのまま指定することもできます。
language_code	ISO 639-1 を指定します。supports_language_code=true のモデルのみ対応します。現在のリストには、この設定を有効にしているモデルはありません。
speed	supports_speed=true のモデルのみ対応し、min_speed～max_speed の範囲内である必要があります。

モデル固有のルールも適用されます。minimax-music-v25 では、force_instrumental または lyrics_optimizer が true でない限り、lyrics_prompt は 10 文字以上必要です。minimax-music-v26 でも、force_instrumental が true でない限り同様です。minimax-music-v2 では、空白以外の文字を含む lyrics_prompt が必要です。

3. POST /audio/retrieve — ポーリング／ダウンロード

curl https://api.venice.ai/api/v1/audio/retrieve \
  -H "Authorization: Bearer $VENICE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"elevenlabs-music","queue_id":"..."}' \
  --output track.mp3

• 処理中：200 と JSON {"status":"PROCESSING","average_execution_time":<ms, P80 estimate>,"execution_duration":<ms since queued>} が返されます。
• 完了：音声バイトデータとともに 200 が返されます。Content-Type は音声の種類を示します。ヘッダーには x-venice-audio-format、x-venice-inference-time（秒）、x-venice-model-id、x-venice-model-name が含まれ、Seed Audio の場合はさらに x-venice-audio-duration と x-venice-audio-subtitle が含まれます。
• delete_media_on_completion: true を指定すると、このダウンロード後にメディアが削除されるため、手順 4 は省略できます。

生成に失敗した場合（コンテンツポリシー、キャパシティ、プロバイダーによる検証など）、料金は返金されます（前のエポックで発生した DIEM の料金を除く）。エラーはここで返されます。

4. POST /audio/complete — クリーンアップ

curl https://api.venice.ai/api/v1/audio/complete \
  -H "Authorization: Bearer $VENICE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"elevenlabs-music","queue_id":"..."}'

保存されたメディアが削除されると {"success": true} が返されます（削除できなかった場合は false）。バイトデータを保存した後に使用してください。ただし、delete_media_on_completion: true を指定して取得した場合は不要です。

一連の処理（TypeScript）

import fs from 'node:fs/promises'

const base = 'https://api.venice.ai/api/v1'
const headers = {
  Authorization: `Bearer ${process.env.VENICE_API_KEY}`,
  'Content-Type': 'application/json',
}

async function generateTrack() {
  // 1. Quote
  const quote = await fetch(`${base}/audio/quote`, {
    method: 'POST', headers,
    body: JSON.stringify({ model: 'elevenlabs-music', duration_seconds: 60 }),
  }).then(r => r.json())
  console.log('price:', quote.quote)

  // 2. Queue
  const { queue_id, model } = await fetch(`${base}/audio/queue`, {
    method: 'POST', headers,
    body: JSON.stringify({
      model: 'elevenlabs-music',
      prompt: 'Uplifting indie-folk acoustic track, 120 BPM.',
      duration_seconds: 60,
      force_instrumental: true,
    }),
  }).then(r => r.json())

  // 3. Poll
  while (true) {
    const res = await fetch(`${base}/audio/retrieve`, {
      method: 'POST', headers,
      body: JSON.stringify({ model, queue_id, delete_media_on_completion: true }),
    })
    if (!res.ok) throw new Error(`retrieve failed: ${res.status} ${await res.text()}`)
    const ct = res.headers.get('content-type') ?? ''
    if (!ct.startsWith('application/json')) {
      await fs.writeFile('track.mp3', Buffer.from(await res.arrayBuffer()))
      break
    }
    const { status } = await res.json()
    if (status !== 'PROCESSING') throw new Error(`unexpected ${status}`)
    await new Promise(r => setTimeout(r, 3000))
  }
  // delete_media_on_completion: true made /audio/complete unnecessary
}

機能の確認

各 GET /models?type=music エントリの model_spec には、次の情報が公開されています。

• supports_lyrics、lyrics_required、lyrics_character_limit、supports_lyrics_optimizer
• supports_force_instrumental、supports_loop、supports_language_code
• supports_speed、default_speed、min_speed、max_speed
• voices[]、default_voice、supports_custom_voice_id
• duration_options[]、min_duration、max_duration、default_duration
• min_prompt_length、prompt_character_limit
• supported_formats、default_format（出力コンテナです。参考情報であり、リクエストフィールドではありません）
• voice_changer: true は、/audio/voice-changer/* を使う音声から音声への変換モデルを示します
• pricing は次のいずれかです。
  • durations — { "<tier>": { usd, diem, min_seconds, max_seconds } }（例：elevenlabs-music、ace-step-15）
  • generation — ジョブごとの定額料金（例：minimax-music-v25、lyria-3-pro、stable-audio-25）
  • per_second — 生成秒数あたりの料金（例：elevenlabs-sound-effects-v2、sonilo-v1-1-music、seed-audio-1-0）
  • per_thousand_characters — prompt の文字数に応じた料金（ElevenLabs の TTS モデル）

エラー

コード	意味
400	スキーマエラー（厳格なリクエスト本文）、モデルでサポートされていないオプション、不正な duration_seconds、lyrics_optimizer と lyrics_prompt の併用、これらのエンドポイントでのボイスチェンジャーモデルの使用、取得時に報告されたプロバイダー側の検証失敗（返金されます）、または取得／完了時の不明な、もしくは別の環境の queue_id（"Request ID is invalid."）。音声のエラーには details.supported_voices が含まれます。
401	認証に失敗しました。
402	残高が不足しています。Bearer の場合は {"error":"Insufficient USD or Diem balance…"} が返されます。キー自体の利用上限に達した場合は `"API key USD
403	PRIVATE_ONLY キーで anonymized モデルを呼び出した場合、またはリージョン制限。
404	不明な model、または取得時にメディアが見つからない、期限切れ、もしくはすでに削除済みの場合。
422	コンテンツポリシー違反（キュー登録時または取得時）。suggested_prompt が含まれる場合があります。料金は返金されます（前のエポックで発生した DIEM の料金を除く）。
429	レート制限超過（ユーザーごとにキュー登録は 40 回／分、取得は 120 回／分）。
500	推論に失敗しました。
503	モデルが処理上限に達しています。時間をおいて再試行してください。

本文の形式については、venice-errors を参照してください。

注意点

• キュー登録前に見積もりを取得してください。 キュー登録時に料金が前払い（クレジット）されるか、x402 の残高が見積額を満たしているか確認されます。API キーの場合は、INFERENCE キーで利用でき、キーの利用上限がすでに適用されている GET /api_keys/rate_limits の data.balances と見積額を比較してください。リクエスト料金は、見積額全体をまかなえる最初の通貨から請求されます（DIEM、獲得クレジット、バンドルクレジット、USD の順。balances には獲得クレジットは表示されません）。ウォレットの場合は /x402/balance/... を使用してください。
• サポートされていないオプション（lyrics_prompt、voice、speed、language_code、loop、duration_seconds など）を送信すると、無視されるのではなく 400 エラーになります。model_spec に基づいてリクエスト本文を作成してください。
• queue_id と model を保存してください。以降のすべての呼び出しで両方が必要です。
• メディアは一時的なものです。取得時にデータを保存してください。complete（または delete_media_on_completion）の後、音声は削除されます。
• seed-audio-1-0 では duration_seconds を指定しません。キュー登録時に出力上限の 120 秒分が確保され、完了時に実際の長さに基づいて精算されます。
• 2～5 秒ごとにポーリングしてください。最初の待ち時間には average_execution_time を参考にしてください。ポーリングを速めてもジョブの処理は速くならず、120 回／分の取得制限を消費します。