メディアガイド

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

このページの内容