aisplice

API リファレンス

音楽

このエンドポイントのモデル（1）

suno
ワークベンチで試す
POST/v1/music/generations
GET/v1/music/tasks/{task_id}
GET/v1/music/tasks/{task_id}/content

歌やインストゥルメンタルのワークフロー向けの非同期音楽生成。送信するとすぐに task_id が返ります。タスクをポーリングするか Webhook コールバックを受け取り、完成した音声を /content から読み取ります。

#リクエストパラメーター

  • modelstring必須

    モデルページにある音楽モデルの ID（例：suno）。

  • promptstring必須

    曲の内容、ムード、楽器構成、歌詞の方向性を記述します。

  • titlestring任意

    任意の曲名。対応するモデルファミリーに転送されます。

  • tagsstring | array任意

    任意のジャンルやスタイルのヒント（cinematic、pop、ambient など）。

  • versionstring任意

    プロバイダーが複数の世代を提供している場合の、モデルファミリーのバージョン切り替え。

  • mvstring任意

    プロバイダー固有の音楽モード選択。ユーザーが明示的に操作する必要がない限り、サーバー側で設定します。

  • instrumentalboolean任意

    モデルが対応している場合、ボーカルなしのインストゥルメンタルを生成します。

  • make_instrumentalboolean任意

    インストゥルメンタル出力用の別のベンダーフラグ。一部のプロバイダーは instrumental の代わりにこれを使います。

  • continue_clip_idstring任意

    新しい曲を始める代わりに、以前のクリップを継続・延長します。

  • continue_atnumber任意

    継続フローでの再開位置（秒）。

  • webhook_urlstring任意

    タスクが終了状態になったときに呼び出される HTTPS URL。

  • webhook_secretstring任意

    設定すると、配信に X-Xiaoxiang-Signature: sha256=hex(HMAC-SHA256(body, secret)) が付きます。

シンプルに始める

ほとんどのプロダクトでは、最初の統合は prompt だけで十分です。title、tags、version、継続用のフィールドは上級者向けの設定で、プロダクトに明確な必要が生じてから追加してください。

他のメディアタスクと同じ非同期の仕組み

音楽は画像や動画のタスクと同じ「送信 → ポーリングまたは Webhook → /content」のパターンに従うため、通常は 1 つのバックエンドのタスク処理で 3 種類すべてを扱えます。

#関連するエラー

  • 404 not_found不明なパス、不明なモデル名、または期限切れか他アカウントの task_id です。
  • 422 unprocessable_entityゲートウェイが転送したパラメーター値をベンダーが拒否しました（対応していないサイズや長さなど）。
  • 401Bearer トークンが無効か、ありません。このパスでは error.code が付きません — ステータスで判定してください。
  • 402 insufficient_user_quotaウォレット残高が事前確保の見積額に足りません。
  • 429キー単位のレート制限です。ボディは空なので、Retry-After の時間だけ待ってください。insufficient_user_quota が付いた 429 は、レート制限ではなく 1 日の利用上限額によるものです。
  • 503 model_not_found不明なモデルか、現在そのモデルを提供できる正常なチャネルがありません。

エラーコード一覧 →

#リクエスト例

# submit
curl https://www.aisplice.store/v1/music/generations \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "suno",
    "prompt": "a warm cinematic piano theme",
    "instrumental": true
  }'

# poll every 5s
curl https://www.aisplice.store/v1/music/tasks/$TASK_ID -H "Authorization: Bearer sk-YOUR_KEY"

# fetch the finished track
curl -L https://www.aisplice.store/v1/music/tasks/$TASK_ID/content \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -o song.mp3

#レスポンス

response.json
// POST — submit accepted
{"task_id": "task_xxx", "status": "queued"}

// GET /v1/music/tasks/{task_id}
{
  "task_id": "task_xxx",
  "status": "in_progress",
  "progress": "42%"
}

// GET /v1/music/tasks/{task_id}/content
{
  "task_id": "task_xxx",
  "status": "completed",
  "metadata": {
    "audio_url": "https://…",
    "lyric": "…"
  }
}

まだ解決しませんか？

リクエスト ID かエラーメッセージを送っていただければ、こちらで調査します。

前へ動画次へ3D モデル