メディアガイド

音楽生成

楽曲や歌詞を作成し、音声の生成完了を待ちます

音楽生成は非同期で行われます。POST /v1/music/generations はタスクID、ステータス、および通常は poll_url を返します。タスクが completed(完了)または failed(失敗)になるまで、そのIDを使用して GET /v1/tasks/{id} をポーリングしてください。

作成内容の選択

作成内容主要フィールド備考
フル楽曲またはインストゥルメンタルmodel, mv, prompt, オプションの title, tags, action: "MUSIC"ユーザーが最終的な音声を期待する場合に使用
歌詞のみmodel, prompt, action: "LYRICS"歌詞生成を公開しているモデルでのみ使用可能
既存クリップの続きを作成model, mv, prompt, continue_clip_id, オプションの continue_at前のクリップIDを保持すること
自身の音声のカバーまたは拡張model, mv, prompt, audio_url, オプションの audio_operationaudio_url は公開URLである必要があります。audio_operation はデフォルトで upload-cover です。upload-extend の場合は continue_at も必要です
インストゥルメンタル追加、セクション置換、ステム分離audio_operation: add-instrumental, replace-section, vocal-separate, multi-stem-separation, または advanced-split各操作にはそれぞれ必要なフィールドがあります。音楽の作成 を参照してください

現在の音楽モデルリストは以下から取得できます:

curl "https://api.tokenlab.sh/v1/models?recommended_for=music" \
  -H "Authorization: Bearer sk-your-api-key"

以下の例では mv: "chirp-v6" を指定した suno-music を使用しています。stable-audio-3 など他の音楽モデルでは、duration や output_format といった異なるフィールドを使用するため、事前にモデルの詳細を確認してください。歌詞のみの場合は、歌詞生成に対応したモデルを選択し、action: "LYRICS" を送信して mv を省略してください。

音楽タスクの作成

curl https://api.tokenlab.sh/v1/music/generations \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "suno-music",
    "mv": "chirp-v6",
    "prompt": "An upbeat synth-pop track with warm vocals and a clean chorus",
    "title": "Morning Static",
    "tags": "synth-pop, upbeat",
    "action": "MUSIC"
  }'

プロンプト、タイトル、タグは製品履歴に表示される場合があります。APIキー、プライベートURL、診断データなどは決して含めないでください。

完成した音声の取得

返された id または task_id を使用して GET /v1/tasks/{id} を呼び出します。

curl "https://api.tokenlab.sh/v1/tasks/$TASK_ID" \
  -H "Authorization: Bearer sk-your-api-key"

レスポンスの形式

作成時のレスポンスはタスクレコードであり、最終的な音声ではありません:

{
  "id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "task_id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "poll_url": "/v1/tasks/ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "status": "pending",
  "created": 1706000000,
  "model": "suno-music"
}

完了したポーリングレスポンスには、最終的なメディアフィールドが含まれる場合があります:

{
  "id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "task_id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "poll_url": "/v1/tasks/ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "status": "completed",
  "audio_url": "https://api.tokenlab.sh/v1/media-results/2d7e9a41-8c3b-4b6f-a1e5-7f0c3d9b8e26.mp3?token=…",
  "video_url": "https://api.tokenlab.sh/v1/media-results/9a3f5c17-2e8d-4b0a-b6c4-1d7e8f2a5b39.mp4?token=…",
  "image_url": "https://api.tokenlab.sh/v1/media-results/c4e8b2d6-7a1f-4e3c-9d5b-3f6a0e8c1b72.jpg?token=…",
  "title": "Morning Static",
  "lyrics": "[Verse 1]\n...",
  "media_retention": {
    "days": 30,
    "items": [
      {
        "url": "https://api.tokenlab.sh/v1/media-results/2d7e9a41-8c3b-4b6f-a1e5-7f0c3d9b8e26.mp3?token=…",
        "kind": "audio",
        "status": "saving",
        "expires_at": "2024-02-22T08:54:20.000Z"
      },
      {
        "url": "https://api.tokenlab.sh/v1/media-results/9a3f5c17-2e8d-4b0a-b6c4-1d7e8f2a5b39.mp4?token=…",
        "kind": "video",
        "status": "saving",
        "expires_at": "2024-02-22T08:54:20.000Z"
      },
      {
        "url": "https://api.tokenlab.sh/v1/media-results/c4e8b2d6-7a1f-4e3c-9d5b-3f6a0e8c1b72.jpg?token=…",
        "kind": "image",
        "status": "saving",
        "expires_at": "2024-02-22T08:54:20.000Z"
      }
    ]
  }
}

最終的なメディアフィールドは、status が completed になるまで存在しません。失敗したタスクは error とともに status: "failed" を返します。

ステータスには pending、processing、completed、failed があります。完了したタスクには audio_url、video_url、title、lyrics、その他のメタデータが含まれる場合があります。メディアURLはTokenLabのURLであり、30日間有効です。それ以上必要な場合は、結果をダウンロードまたは保存してください。

適切な状態の表示

  • タスク作成直後は保留(pending)状態を表示します。
  • 長いタスクの場合は 5-10秒 ごとにポーリングを行い、completed または failed になったら停止します。
  • タスクが completed になり audio_url が存在するまで、最終的なプレイヤーを表示しないでください。
  • 歌詞のみのタスクについては、ユーザーが何を購入しているかを理解できるよう、音声タスクとは別にテキスト出力をレンダリングしてください。
  • 更新時には、新しいタスクを作成するのではなく、保存された task_id から再開してください。

課金記録

音楽タスクは作成時に推定額を予約する場合があります。最終的な金額は完了または失敗後に記録されます。request_id、task_id、モデル、エンドポイント、および billing_transaction_id が表示されたら保存してください。最終的な請求にはManagement APIの利用記録を使用します。

一般的なエラー

症状考えられる原因修正方法
タスクは作成されたがプレイヤーが表示されないタスクが保留中、または audio_url なしで完了した終了するまでポーリングを続け、出力がない場合は失敗したジョブとして処理する
更新後に曲が重複するUIが再開ではなくタスクを再作成しているtask_id を保持して再利用する
歌詞タスクで音声が返されないaction: "LYRICS" はテキストのみである歌詞と音楽のUIパスを分ける
サポートされていないパラメータ選択したモデルがそのフィールドを受け付けていない削除するか、そのフィールドに対応したモデルを選択する

APIリファレンス

トピックリファレンス
音楽の作成音楽の作成
音楽ステータスの取得音楽ステータスの取得
タスクステータスの取得タスクステータスの取得
モデル一覧モデル一覧
課金と価格設定課金と価格設定

このページの内容