音楽生成

音楽生成は非同期です。 POST /v1/music/generations は公開されたTokenLabタスクを作成し、id / task_id、status、通常はpoll_urlを返します。アプリケーションはそのタスクの識別子を保存し、進行状況を表示し、最終的なステータスになるまでポーリングする必要があります。

ワークフローの選択Copy Anchor Link

ハードコーディングされたモデルリストを出荷する前に、現在のモデルカタログをクエリします：

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

現在の公開例では、音楽生成にsuno_musicを使用し、chirp-v4などの公式Sunoモデルバージョンをmvに含めています。歌詞のみのフローの場合、歌詞生成を文書化したモデルと共にaction: "LYRICS"を送信し、mvは省略します。モデルIDは公開されたTokenLab IDとして扱い、プロバイダー固有のフィールドが対応状況フィールドであることを保証するものではありません。

音楽タスクの作成Copy Anchor Link

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-v4",
    "prompt": "温かいボーカルとクリーンなコーラスを持つアップビートなシンセポップトラック",
    "title": "モーニングスタティック",
    "tags": "シンセポップ, アップビート",
    "action": "MUSIC"
  }'

プロンプト、タイトル、タグはユーザーに見えるようにし、安全に保存してください。プロンプトフィールドに API キー、プライベート URL、または非公開の診断情報を入れないでください。

完了のポーリングCopy Anchor Link

まずpoll_urlを使用します。クライアントが固定ルートを必要とする場合は、返されたidまたはtask_idでGET /v1/tasks/{id}を呼び出します。

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

レスポンス形式Copy Anchor Link

作成レスポンスは最終音声ではなく、ポーリング可能なタスクレコードです。

{
  "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://cdn.example.com/music/abc123.mp3",
  "video_url": "https://cdn.example.com/music/abc123.mp4",
  "stream_audio_url": "https://cdn.example.com/music/abc123-stream.mp3",
  "image_url": "https://cdn.example.com/music/cover.jpg",
  "title": "Morning Static",
  "lyrics": "[Verse 1]\n..."
}

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

期待される公開ステータスはpending、processing、completed、およびfailedです。完了した音楽タスクにはaudio_url、video_url、title、lyrics、および正規化されたメタデータが含まれる場合があります。最終的なURLは自分のデータベースに保存し、ユーザーが生成を再開せずに結果を再度開けるようにします。

UIと状態管理Copy Anchor Link

• タスク作成後すぐに保留状態を表示します。
• 長いタスクの場合は、5-10秒ごとにポーリングし、completedまたはfailedで停止します。
• タスクがcompletedであり、audio_urlが存在するまで最終プレーヤーを表示しないでください。
• 歌詞のみのタスクの場合、ユーザーが購入している内容を理解できるように、オーディオタスクとは別にテキスト出力をレンダリングします。
• リフレッシュ時には、新しいタスクを作成するのではなく、保存されたtask_idから再開します。

請求と調整Copy Anchor Link

音楽タスクは作成時に推定額を予約し、最終ステータスがわかった後に決済できます。request_id、task_id、モデル、エンドポイント、およびbilling_transaction_idが表示されたときに保存します。プロバイダーのタスクIDの代わりに、管理APIの使用記録を調整に使用します。

一般的なエラーCopy Anchor Link

APIリファレンスCopy Anchor Link