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

​
ワークフローの選択

ワークフロー主要フィールド注意事項
フルソングまたはインストゥルメンタルmodel, prompt, オプションの title, tags, action: "MUSIC"ユーザーが最終的なオーディオを期待する場合に使用
歌詞のみmodel, prompt, action: "LYRICS"歌詞生成を公開しているモデルのみで使用
既存のクリップを続行continue_clip_id, オプションの continue_at続行を提供する前に、前の公開クリップ/タスクの識別子を保存
ハードコーディングされたモデルリストを出荷する前に、現在のモデルカタログをクエリします： 
curl "https://api.tokenlab.sh/v1/models?recommended_for=music" \
  -H "Authorization: Bearer sk-your-api-key"
現在の公開例では、音楽生成にsuno_musicを使用しています。歌詞のみのフローの場合、歌詞生成を文書化したモデルと共にaction: "LYRICS"を送信します。モデルIDは公開されたTokenLab IDとして扱い、プロバイダー固有のフィールドが公開契約フィールドであることを保証するものではありません。

​
音楽タスクの作成

curl https://api.tokenlab.sh/v1/music/generations \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "suno_music",
    "prompt": "温かいボーカルとクリーンなコーラスを持つアップビートなシンセポップトラック",
    "title": "モーニングスタティック",
    "tags": "シンセポップ, アップビート",
    "action": "MUSIC"
  }'
プロンプト、タイトル、タグはユーザーに見えるようにし、安全に保存してください。プロンプトフィールドにAPIキー、プライベートURL、または内部ルーティング情報を配置しないでください。

​
完了のポーリング

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

​
UIと状態管理

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

​
請求と調整

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

​
一般的なエラー

症状考えられる原因修正
タスクが作成されたがプレーヤーがないタスクがまだ保留中またはaudio_urlなしで完了している最終状態になるまでポーリングし、出力が欠落している場合は失敗したユーザーのジョブとして処理
リフレッシュ後に重複した曲UIがタスクを再開するのではなく再作成したtask_idを保持して再利用
歌詞タスクがオーディオを返さないaction: "LYRICS"はテキストのみ歌詞と音楽のUIパスを分ける
サポートされていないパラメータフィールドがモデルの公開契約に含まれていないプロバイダー固有のフィールドを削除するか、それらを文書化したモデルを選択

​
APIリファレンス

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