メディアガイド
Worlds
テキスト、画像、または動画から探索可能なMarbleワールドを作成します
Worldsは、ユーザーが開いて探索できるMarble環境を作成します。環境ではなくダウンロード可能なオブジェクトが必要な場合は、3D generationを使用してください。
スプラット、メッシュ、パノラマ画像などのダウンロード可能なWorldファイルは、TokenLabのメディア結果URLを使用して30日間の自動コピーとして保持されます。インタラクティブなWorldページおよびWorldレコードは保持されません。詳細はデータ保持を参照してください。
入力とメディアアセット
ワールドは、モデルに応じてテキスト、1つ以上の画像、または動画から開始できます。GET /v1/models?recommended_for=3d でMarbleモデル(marble-*)を確認してください。その操作は world-generation です。少なくとも1つの入力を送信してください:
| 入力 | フィールド |
|---|---|
| テキスト | prompt、最大4,000文字 |
| 1つの画像 | image_url、またはBase64もしくはデータURLとしての image。is_pano はそれが既にパノラマかどうかを指定します |
| 複数の画像 | images、最大4つ |
| 動画 | video_url |
| 高度な設定 | world_prompt、アップロードされたメディアアセットを参照できるネイティブプロンプトオブジェクト |
オプションのフィールドには、display_name(最大64文字)、seed、tags(最大10個)、permission があります。再利用可能なメディアは一度アップロードすれば、そのアセットIDで参照できます。
メディアおよびWorldレコードへのアクセスは、APIキーを所有する組織に対してチェックされます。ワールドを共有する前に、選択したモデルの permission オプションを確認してください。返されたアセットやビューアーURLには、独自のアクセスルールが適用される場合があります。
作成とポーリング
作成レスポンスにはタスクIDと通常 poll_url が含まれます。IDを保持し、ステータスが completed または failed になるまで GET /v1/tasks/{id} を呼び出してください。Worldsの poll_url は互換性パスである /v1/worlds/generations/{id} を指しますが、代わりに /v1/tasks/{id} を使用してください。
curl -X POST "https://api.tokenlab.sh/v1/worlds/generations" \
-H "Authorization: Bearer sk-your-api-key" \
-H "Content-Type: application/json" \
-d '{
"model": "marble-1.1",
"prompt": "A quiet coastal town at sunset with narrow alleys and warm lights"
}'作成レスポンスの id を使用してタスクをポーリングします:
curl "https://api.tokenlab.sh/v1/tasks/$TASK_ID" \
-H "Authorization: Bearer sk-your-api-key"完了したワールドの管理
アカウントで利用可能な完了済みのワールドには POST /v1/worlds/list および GET /v1/worlds/{id} を使用し、削除には DELETE /v1/worlds/{id} を使用します。保留中または失敗した生成タスクには GET /v1/tasks/{id} を使用してください。ユーザーが意図的に製品から生成されたワールドを削除した場合にのみ、削除を実行してください。
よくある落とし穴
- すべてのワールドモデルがすべての入力タイプをサポートしていると想定しないでください。
- 署名付きの画像または動画URLは、サービスのフェッチ再試行に十分な期間有効であることを確認してください。
- タイムアウト後の再試行に備えて、返されたタスクIDを保存してください。
- 探索可能なワールドではなく、ダウンロード可能なモデルファイルが必要な場合は3D generationを使用してください。
APIリファレンス
| トピック | リファレンス |
|---|---|
| ワールドの作成 | ワールドの作成 |
| タスクステータスの取得 | タスクステータスの取得 |
| ワールドステータスの取得(互換性) | ワールドステータスの取得 |
| メディアアセットアップロードの準備 | メディアアセットアップロードの準備 |
| メディアアセットの取得 | メディアアセットの取得 |
| ワールドの一覧表示 | World の一覧取得 |
| ワールドの取得 | World の取得 |
| ワールドの削除 | Worldの削除 |
| 非同期ジョブ | Async Jobs |
| 3D生成ガイド | 3D Generation Guide |