メディアガイド
音楽生成
楽曲や歌詞を作成し、音声の生成完了を待ちます
音楽生成は非同期で行われます。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_operation | audio_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リファレンス
| トピック | リファレンス |
|---|---|
| 音楽の作成 | 音楽の作成 |
| 音楽ステータスの取得 | 音楽ステータスの取得 |
| タスクステータスの取得 | タスクステータスの取得 |
| モデル一覧 | モデル一覧 |
| 課金と価格設定 | 課金と価格設定 |